Testing Protocols

Testing Protocols

To maintain the stability of our WordPress contributions, all submissions must adhere to our multi-layered testing suite. We utilize PHPUnit for backend logic, Jest for JavaScript components, and Playwright for end-to-end user workflows.

1. PHPUnit (Backend Integration & Unit Tests)

PHPUnit is used to validate PHP logic, hook registrations, and REST API endpoints. All backend contributions must maintain a minimum of 80% code coverage for public-facing functions.

Requirements:

• Tests must extend WP_UnitTestCase.
• Database interactions should use the core WordPress test suite to ensure transactions are rolled back after each test.

Usage: To run the PHPUnit suite locally, ensure your environment (e.g., wp-env) is active:

# Run all PHP tests
composer test:php

# Run a specific test file
vendor/bin/phpunit tests/phpunit/test-sample-plugin.php

Example Test Structure:

public function test_plugin_activation_registers_post_type() {
    $this->assertTrue( post_type_exists( 'custom_contribution' ) );
}

2. Jest (JavaScript & Block Testing)

For Gutenberg blocks and frontend interactive components, we use Jest along with @testing-library/react. This ensures that UI components render correctly and handle state changes as expected.

Requirements:

• Mock all external API calls using jest.fn() or specialized MSW handlers.
• Focus on user interactions (clicks, inputs) rather than internal state variables.

Usage:

# Run Jest in watch mode
npm run test:unit -- --watch

# Generate coverage reports
npm run test:unit -- --coverage

Example Test Structure:

import { render, screen, fireEvent } from '@testing-library/react';
import MyBlockEdit from './edit';

test('updates text on input change', () => {
    render(<MyBlockEdit attributes={{ content: '' }} />);
    const input = screen.getByRole('textbox');
    fireEvent.change(input, { target: { value: 'New Contribution' } });
    expect(input.value).toBe('New Contribution');
});

3. Playwright (End-to-End Testing)

Playwright covers the critical user journey, ensuring that the WordPress admin and frontend work in harmony across different browsers.

Requirements:

• Tests should be independent and handle their own setup/teardown (e.g., creating a post before testing its frontend display).
• Use the @wordpress/e2e-test-utils-playwright package for authenticated sessions.

Usage:

# Install Playwright browsers
npx playwright install

# Run E2E tests in headed mode
npm run test:e2e -- --headed

# Run tests against a specific URL
WP_BASE_URL=http://localhost:8888 npm run test:e2e

Common E2E Scenarios:

• Publishing Flow: Verifying a user can create, save, and publish a post.
• Plugin Settings: Ensuring configuration changes are persisted in the database and reflected in the UI.
• Theme Responsiveness: Checking that core components remain visible at mobile breakpoints.

4. Continuous Integration (CI)

Upon opening a Pull Request, our GitHub Actions workflow automatically executes the following:

1. Linting: PHPCS (WordPress Coding Standards) and ESLint.
2. Unit/Integration: PHPUnit and Jest suites.
3. E2E: Playwright suite against a headless Chromium instance.

All checks must pass before a contribution is eligible for review. If a test fails in the CI environment but passes locally, ensure your wp-env configuration matches the production PHP/WordPress version specifications.