104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# External WP-CLI Testing Setup
|
|
|
|
This guide explains how to enable and run External WP-CLI Testing from the Builder, with tools loaded into OpenCode only when the feature toggle is enabled.
|
|
|
|
## What This Adds
|
|
|
|
- A gated MCP tool named `test_plugin_external_wp` (plus a helper tool `external_wp_testing_config`).
|
|
- Tools are injected into OpenCode only when the Builder toggle is on.
|
|
- All connection/auth settings are controlled via environment variables.
|
|
|
|
## Prerequisites
|
|
|
|
1. A reachable WordPress host with WP-CLI installed.
|
|
2. SSH access to that host from the server running the chat app.
|
|
3. The SSH user must be able to run WP-CLI at the configured path.
|
|
|
|
## Required Environment Variables
|
|
|
|
Set these in the environment where the chat server runs (the same process that launches OpenCode).
|
|
|
|
- `TEST_WP_HOST` (or `EXTERNAL_WP_HOST`)
|
|
- Hostname or IP of the WordPress server.
|
|
- `TEST_WP_SSH_USER` (or `EXTERNAL_WP_SSH_USER`)
|
|
- SSH username for the WordPress server.
|
|
- `TEST_WP_SSH_KEY` (or `TEST_WP_SSH_KEY_PATH`, or `EXTERNAL_WP_SSH_KEY`)
|
|
- Path to the SSH private key file.
|
|
|
|
If these are missing, the tool will return a clear error.
|
|
|
|
## Optional Environment Variables
|
|
|
|
- `TEST_WP_PATH` (or `EXTERNAL_WP_PATH`)
|
|
- Default: `/var/www/html`
|
|
- Path to the WordPress root on the remote host.
|
|
- `TEST_WP_BASE_URL` (or `EXTERNAL_WP_BASE_URL`)
|
|
- Default: `https://<TEST_WP_HOST>`
|
|
- Base URL for the site.
|
|
- `TEST_WP_MULTISITE` (or `EXTERNAL_WP_MULTISITE`)
|
|
- Default: `true`
|
|
- Enables multisite subsite isolation.
|
|
- `TEST_WP_SUBSITE_PREFIX` (or `EXTERNAL_WP_SUBSITE_PREFIX`)
|
|
- Default: `test`
|
|
- Prefix for created subsites.
|
|
- `TEST_WP_SUBSITE_DOMAIN` (or `EXTERNAL_WP_SUBSITE_DOMAIN`)
|
|
- Default: empty (falls back to host)
|
|
- Domain used when subsite mode is subdomain.
|
|
- `TEST_WP_SUBSITE_MODE` (or `EXTERNAL_WP_SUBSITE_MODE`)
|
|
- Default: `subdirectory`
|
|
- Allowed values: `subdirectory`, `subdomain`.
|
|
- `TEST_WP_ERROR_LOG` (or `EXTERNAL_WP_ERROR_LOG`)
|
|
- Default: `/var/log/wp-errors.log`
|
|
- Used by the default "Scan error log" scenario.
|
|
- `TEST_SSH_STRICT` (or `EXTERNAL_WP_SSH_STRICT`)
|
|
- Default: `false`
|
|
- When `true`, enforces strict host key checking.
|
|
- `TEST_MAX_CONCURRENT` (or `EXTERNAL_WP_MAX_CONCURRENT`)
|
|
- Default: `20`
|
|
- Max concurrent tests.
|
|
- `TEST_QUEUE_TIMEOUT` (or `EXTERNAL_WP_QUEUE_TIMEOUT`)
|
|
- Default: `300000` (ms)
|
|
- `TEST_TIMEOUT` (or `EXTERNAL_WP_TEST_TIMEOUT`)
|
|
- Default: `600000` (ms)
|
|
- `TEST_AUTO_CLEANUP` (or `EXTERNAL_WP_AUTO_CLEANUP`)
|
|
- Default: `true`
|
|
- Cleans up subsites after tests complete.
|
|
- `TEST_CLEANUP_DELAY` (or `EXTERNAL_WP_CLEANUP_DELAY`)
|
|
- Default: `3600000` (ms)
|
|
|
|
## Example .env
|
|
|
|
TEST_WP_HOST=wp-test.example.com
|
|
TEST_WP_SSH_USER=wordpress
|
|
TEST_WP_SSH_KEY=C:\\keys\\wp-test.pem
|
|
TEST_WP_PATH=/var/www/html
|
|
TEST_WP_BASE_URL=https://wp-test.example.com
|
|
TEST_WP_MULTISITE=true
|
|
TEST_WP_SUBSITE_MODE=subdirectory
|
|
TEST_WP_SUBSITE_PREFIX=test
|
|
TEST_WP_ERROR_LOG=/var/log/wp-errors.log
|
|
TEST_SSH_STRICT=false
|
|
TEST_MAX_CONCURRENT=20
|
|
TEST_TIMEOUT=600000
|
|
|
|
## Builder Toggle Behavior
|
|
|
|
- Open the Builder and enable the "External WP CLI testing" toggle.
|
|
- When enabled, the chat server injects the MCP server definition via `OPENCODE_EXTRA_MCP_SERVERS`.
|
|
- When disabled, the environment variable is removed before OpenCode is spawned, so the tools are not exposed.
|
|
|
|
## Running a Test
|
|
|
|
1. Enable the toggle in Builder.
|
|
2. Proceed with the build or let the AI call `test_plugin_external_wp`.
|
|
3. The tool runs WP-CLI commands over SSH and returns a JSON report.
|
|
|
|
## Quick Sanity Check Tool
|
|
|
|
You can ask the AI to call `external_wp_testing_config` to validate your settings. It returns the resolved config and a list of missing required variables.
|
|
|
|
## Notes
|
|
|
|
- `test_plugin_external_wp` only supports `test_mode=cli` in the current implementation.
|
|
- Ensure the SSH user can execute WP-CLI and write to the plugin directory.
|