Skip to content

testing.md

Latest commit

 

History

History
75 lines (47 loc) · 4.79 KB

testing.md

File metadata and controls

75 lines (47 loc) · 4.79 KB

Testing

The test suite uses PHPUnit. Unit tests should use fake HTTP/client responses and must not require a live WordPress site.

Test filenames must match their test class names. Name test classes after the production class, domain, or behavior under test, and keep paths traceable to source paths, for example src/Services/PluginsService.php to tests/Unit/Services/PluginsServiceTest.php.

Shared helpers should use purpose-based names. Do not use phase, planning, temporary, or vague bucket names in test files, classes, methods, traits, or helpers, including P1, P2, Phase1, Phase2, Sprint, Milestone, Temporary, Temp, Misc, Bucket, NewEndpoints, OldEndpoints, Legacy, or WIP.

composer test
composer test:unit
composer test:integration
composer test:all
composer test:coverage
composer test:coverage:gate
composer test:coverage-map

composer test and composer test:coverage run the unit suite so normal validation does not depend on WordPress. composer test:integration runs the integration suite and must only be used with a disposable local WordPress test site.

composer test:coverage now runs a Clover XML coverage gate after PHPUnit writes coverage.xml. Aggregate statement coverage must stay at or above 90%. The gate also fails when any coverable production file, class, or method under src/ is left at 0% coverage. Do not rely on the aggregate percentage alone.

Unit Tests

Unit tests cover DTO hydration and serialization, query DTO output, endpoint path builders, auth middleware, response decoding, exception redaction, pagination helpers, service request construction, and generic builder support. They must use fake clients or deterministic local values and must not make network calls.

Integration Tests

Integration tests must run only against a disposable local WordPress environment created for SDK testing.

composer test:integration

The 1.2.0 release does not ship Docker/WP Composer aliases because the Docker runner files are not present in this repository. Do not add composer test:wordpress, composer test:wordpress:extended, or Docker aliases back without committing the complete local-only runner, setup scripts, fixtures, and safety guards in the same change.

Template-specific integration tests live in jooservices/wordpress-content-templates. SDK integration tests stay focused on native WordPress REST API endpoints, generic post payload creation, media uploads, and Gutenberg content builder behavior.

The local test site uses disposable credentials only. Do not commit real WordPress credentials.

Safety Guard

Do not run SDK integration tests against production, staging, or personal WordPress sites. Until a complete Docker/WP runner is restored, contributors should treat the integration suite as manually provisioned and keep normal release validation on unit tests, coverage, coverage-map, static analysis, and security audit.

Coverage Map

composer test:coverage-map reflects over src/**/*.php and verifies that production classes are mapped to unit coverage and concrete services are mapped to integration coverage. Pure interfaces are excluded. Abstract helpers, traits, and grouped tests require an explicit reason in tools/test-coverage-map.php.

Coverage Gate

composer test:coverage:gate reads PHPUnit's Clover XML output from coverage.xml. It is deterministic and CI-safe because it does not parse HTML. The gate fails when any of these conditions are true:

  • overall statement coverage is below 90%
  • a coverable production file in src/ has 0 covered statements
  • a coverable production class in src/ has 0 covered statements or 0 covered methods
  • a coverable production method in src/ has 0 execution count

If a production file, class, or method is truly non-coverable by project convention, add a documented exclusion reason in tools/test-coverage-gate.php. Do not exclude code only because it is inconvenient to test. Run the coverage gate before calling coverage work complete.

Skip and Version-Gate Policy

Integration tests must check /wp-json route availability before skipping feature-dependent endpoints. Skip messages must include the service method, exact route, WordPress version, and active theme. Prefer Docker setup fixes over skips.

Acceptable reasons include:

  • route missing in the tested WordPress version
  • feature requires a block theme
  • feature requires an optional plugin
  • WordPress did not generate a revision for the test resource

Troubleshooting

  • Missing WordPress environment values: set WORDPRESS_URL, WORDPRESS_USER, and WORDPRESS_APP_PASSWORD for a disposable local test site only.
  • WordPress server is unreachable: start the local test site and verify /wp-json/ is reachable.
  • Integration failures after resource creation: clean up the disposable local test site before rerunning.