PHPUnit Testing

Ensuring the stability of core logic and custom WordPress contributions is vital for the UditAkhourii/wordpress project. This suite utilizes PHPUnit alongside the official WordPress testing library to simulate a WordPress environment without requiring a live web server.

Prerequisites

Before running tests, ensure your environment meets the following requirements:

PHP: 7.4 or higher.
Composer: For managing dependencies.
Subversion (svn): Required by the WordPress test suite setup script.
Database: A dedicated MySQL/MariaDB database for testing (data will be wiped frequently).

Environment Setup

To initialize the testing environment, run the included setup script. This will download the WordPress unit testing library and create a temporary WordPress installation.

# Usage: bin/install-wp-tests.sh <db-name> <db-user> <db-pass> [db-host] [wp-version]
bash bin/install-wp-tests.sh wp_test root root localhost latest

Once installed, ensure your phpunit.xml file is configured to point to the correct bootstrap file (usually located in tests/bootstrap.php).

Writing Test Cases

All test classes should be located in the tests/ directory and must extend the WP_UnitTestCase class. This provides access to WordPress-specific factories and assertions.

Example: Testing Core Utility Logic

If you are contributing a utility function to the core logic, create a test file following the naming convention test-*.php.

/**
 * Class SampleTest
 * 
 * Tests the public utility methods in the UditAkhourii core.
 */
class SampleTest extends WP_UnitTestCase {

    /**
     * Verify that our custom formatting logic returns the expected string.
     */
    public function test_format_contribution_title() {
        $input = "wordpress-mvp";
        $expected = "Wordpress Mvp";
        
        $output = \UditAkhourii\Core\format_title($input);
        
        $this->assertEquals($expected, $output);
    }

    /**
     * Ensure that the custom post type registration is successful.
     */
    public function test_post_type_registration() {
        $this->assertContains('contribution', get_post_types());
    }
}

Using Factories

The WP_UnitTestCase provides factories to quickly create mock data (posts, users, comments) for your tests.

Usage Example:

public function test_contribution_count_logic() {
    // Create 3 mock posts
    $this->factory->post->create_many(3, ['post_type' => 'contribution']);
    
    $count = \UditAkhourii\Core\get_contribution_count();
    $this->assertEquals(3, $count);
}

Running the Suite

You can execute the full test suite or target specific files using the following commands:

Run all tests:

./vendor/bin/phpunit

Run a specific test file:

./vendor/bin/phpunit tests/test-core-logic.php

Run tests with a specific group tag:

./vendor/bin/phpunit --group core-logic

Best Practices for Contributions

Isolation: Do not rely on existing database content. Use the provided factories to create the state required for your test.
Naming: Use descriptive method names prefixing with test_ (e.g., test_user_cannot_access_private_contributions).
Assertions: Use the most specific assertion possible (e.g., assertWPError() instead of assertInstanceOf()) to gain better debug feedback when tests fail.