Skip to content

README.md

Latest commit

 

History

History
101 lines (74 loc) · 4.27 KB

README.md

File metadata and controls

101 lines (74 loc) · 4.27 KB
Raw

4WP Dev Toolkit

One place for code quality and tests of all 4wp-* plugins: shared PHPCS standard 4WP, PHPUnit helpers, MCP smoke tests for abilities, and a family check that runs lint/tests across every plugin.

  • Dev-only Composer package — not a WordPress plugin, not for wordpress.org, never activated on a site.
  • Installed per plugin into vendor/ (require-dev). No need to clone it beside the plugins, except to develop the toolkit itself.

How it works

Layer What Where it lives
Rules PHPCS standard 4WP = WPCS + PHPCompatibilityWP 4WP/ruleset.xml → plugin phpcs.xml: <rule ref="4WP"/>
Unit tests Brain Monkey base class, bootstrap template, example src/Testing/UnitTestCase.php, tests/*.dist
Integration tests WordPress test suite installer, wp-env template, ability assertions bin/4wp-install-wp-tests, templates/.wp-env.json.dist, src/Testing/AbilityAssertions.php
MCP / abilities Smoke test against server 4wp (4wp-mcp-connector) + per-plugin scenarios bin/4wp-mcp-smoke, scenarios/*.json
Whole family composer run lint / test in every 4wp-*, summary table bin/4wp-family-check
CI GitHub Actions template (PHP matrix) .github/workflows/php-quality.yml.dist

Plugin-specific tests stay in each plugin's tests/ (they ship with the plugin's code); shared tools, scenarios and runners live here.

Quick start (in a plugin)

composer config repositories.4wp-dev-toolkit vcs https://github.com/4wpdev/4wp-dev-toolkit
composer require --dev 4wpdev/4wp-dev-toolkit:dev-main

phpcs.xml:

<rule ref="4WP"/>
<config name="testVersion" value="8.3-"/>
<config name="minimum_supported_wp_version" value="6.9"/>

Details, legacy ../4wp-dev-toolkit setup and local toolkit development: docs/SETUP.md.

Commands

Command What
composer run lint / lint:fix PHPCS in the plugin (4WP standard)
composer run test PHPUnit (unit; integration when WP_TESTS_DIR is set)
vendor/bin/4wp-install-wp-tests WordPress core + test library for integration tests
vendor/bin/4wp-mcp-smoke List tools on server 4wp
vendor/bin/4wp-mcp-smoke 4wp-seo-helper Run scenarios/4wp-seo-helper.json (read-only calls)
vendor/bin/4wp-mcp-smoke --all All scenarios
vendor/bin/4wp-mcp-smoke --tool=<name> --args='{"k":"v"}' One call
vendor/bin/4wp-family-check [lint|test] All 4wp-* plugins, summary table

In the toolkit repo itself: composer run mcp-smoke -- --all, composer run family-check -- lint.

Configuration (env)

Every script reads shell env first, then .env (copy .env.dist; .env is git-ignored).

Variable Used by Default
WP_MCP_URL, WP_USER, WP_APP_PASSWORD mcp-smoke — (required)
WP_MCP_INSECURE=1 mcp-smoke 0 — only for Local self-signed TLS
FORWP_PLUGINS_DIR family-check parent dir of the toolkit
FORWP_PLUGINS family-check every 4wp-* with composer.json
FORWP_FAMILY_INSTALL=1 family-check 0 — composer install where vendor/ is missing
WP_VERSION, WP_TESTS_DIR, WP_CORE_DIR install-wp-tests latest, $TMPDIR/wordpress-tests-lib, $TMPDIR/wordpress
DB_NAME, DB_USER, DB_PASSWORD, DB_HOST install-wp-tests wordpress_tests, root, root, localhost (supports localhost:/path/mysql.sock)

MCP scenarios

scenarios/<plugin>.json:

{
	"plugin": "4wp-social",
	"calls": [
		{ "tool": "forwp-social-platforms", "arguments": {}, "readonly": true, "expect_keys": [ "result" ] }
	]
}

Tool name = ability name with / → -. Result per call: PASS, FAIL, or SKIP (tool not enabled in Settings → 4WP MCP, or a write call without --allow-write). Exit code 1 on any FAIL.

Ability assertions (integration tests)

final class AbilitiesTest extends WP_UnitTestCase {
	use \ForWP\DevToolkit\Testing\AbilityAssertions;

	public function test_get_meta_contract(): void {
		$this->assertAbilityContract( 'forwp-seo-helper/get-meta', 'forwp-seo-helper', true );
		$this->assertAbilityPermission( 'forwp-seo-helper/get-meta', 0, false );
	}
}

Changelog

See CHANGELOG.md.

License

GPL-2.0-or-later