# Kind Site Framework tests

These are WordPress integration tests for the KSF REST API. They use PHPUnit,
the wp-phpunit/wp-phpunit WordPress test library, and a separate test
database. They should not run against the normal site database.

## Requirements

- PHP 8.0 or newer
- PHPUnit and the WordPress test dependencies installed with Composer
- PHP extensions required by PHPUnit, especially mbstring
- A MySQL or MariaDB test database
- The plugin's WordPress installation available locally

Install the development dependencies from the plugin directory:

~~~bash
composer install
~~~

If the host PHP is missing mbstring, install or enable it before running
Composer and PHPUnit. Using Composer's --ignore-platform-req option can
resolve packages, but it does not make PHPUnit runnable without the extension.

## Test database configuration

Create a separate wp-tests-config.php outside the repository. For example:

~~~php
<?php

define( 'ABSPATH', '/absolute/path/to/wordpress/' );
define( 'DB_NAME', 'wordpress_tests' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'root' );
define( 'DB_HOST', '127.0.0.1' );
define( 'DB_CHARSET', 'utf8mb4' );
define( 'DB_COLLATE', '' );

define( 'WP_TESTS_DOMAIN', 'localhost' );
define( 'WP_TESTS_EMAIL', 'admin@example.com' );
define( 'WP_DEBUG', true );

$table_prefix = 'wptests_';
~~~

Use the actual database credentials and absolute WordPress path for the
environment where the tests run. The test database must already exist.

## Running the tests

From the plugin directory:

~~~bash
export WP_TESTS_DIR="$PWD/vendor/wp-phpunit/wp-phpunit"
export WP_PHPUNIT__TESTS_CONFIG="/absolute/path/to/wp-tests-config.php"

vendor/bin/phpunit --configuration phpunit.xml.dist
~~~

To run only one endpoint test class:

~~~bash
vendor/bin/phpunit --configuration phpunit.xml.dist \
  tests/Unit/ApiStructuredDataUpdateTest.php
~~~

To run one test method:

~~~bash
vendor/bin/phpunit --configuration phpunit.xml.dist \
  --filter testDryRunDoesNotWrite
~~~

The bootstrap loads the plugin and dispatches requests through WordPress's
REST server. This is intentional: the tests cover route registration,
permissions, post metadata, database writes, and generated structured data
together.

## Troubleshooting

If PHPUnit reports that WP_TESTS_DIR is not set, export it as shown above.
If it reports that wp-tests-config.php is missing, check
WP_PHPUNIT__TESTS_CONFIG and make sure the file is readable.

If the editor reports WP_UnitTestCase as undefined, ensure Composer
development dependencies are installed and that the IDE indexes
vendor/wp-phpunit/wp-phpunit.