wp-phpunit-writing-tests

Name: wp-phpunit-writing-tests
Author: Lonsdale201

21stars1forks

How to install wp-phpunit-writing-tests?

lonsdale201/wp-agent-skills/wp-phpunit-writing-tests

$npx -y skills add Lonsdale201/wp-agent-skills --skill wp-phpunit-writing-tests

Installs into the current project.

Summary

Write PHPUnit tests for a WordPress plugin or theme. Covers the integration base class WP_UnitTestCase and its snake_case set_up() / tear_down() fixtures (and why WordPress uses them via phpunit-polyfills), the per-test DB transaction rollback, the factory system (`self::fa

Files · 1

View on GitHub

SKILL.md

1	# Writing WordPress PHPUnit tests
2
3	Once the harness is in place (`wp-phpunit-test-setup`), this skill is about the tests themselves: which base class, how to build fixtures, how to mock, and the integration-vs-unit decision that trips most people up.
4
5	## When to use this skill
6
7	- Writing the first real tests for a plugin/theme.
8	- Reviewing tests for correct fixtures, isolation, and mocking.
9	- Deciding between an integration test and a true unit test.
10	- Mocking outbound HTTP (`wp_remote_*`) or WP functions.
11
12	## Integration vs unit — get this right first
13
14	`WP_UnitTestCase` boots the full WordPress environment and uses a real (test) database, with each test wrapped in a transaction that is rolled back afterwards. Despite the name, that is an integration test, not a pure unit test. Use it when you need real WP behavior: DB writes, `WP_Query`, hooks firing against core, rewrite rules, user capabilities.
15
16	For true unit tests — fast, isolated, no WP boot, no DB — you mock WordPress functions with one of:
17
18	- Brain Monkey (`brain/monkey`, 2.7.x) — Mockery + Patchwork based; expressive `when()` / `expect()`.
19	- WP_Mock (`10up/wp_mock`, 1.1.x) — explicit per-function expectations, action/filter helpers.
20
21	Rule of thumb: test your own logic (a calculator, a formatter, a class method) as a unit test with mocked WP calls; test interaction with WordPress (it really saved the post, the hook really ran) as a `WP_UnitTestCase` integration test. Most plugins want both, in separate test suites.
22
23	## Integration tests: WP_UnitTestCase
24
25	### Fixtures are snake_case — and that matters
26
27	```php
28	class Test_My_Plugin extends WP_UnitTestCase {
29
30	public function set_up(): void {
31	parent::set_up(); // MUST be the first line
32	// per-test arrange
33	}
34
35	public function tear_down(): void {
36	// per-test cleanup
37	parent::tear_down(); // MUST be the last line
38	}
39
40	public function test_it_does_a_thing(): void {
41	$this->assertTrue( my_plugin_does_a_thing() );
42	}
43	}
44	```
45
46	Use `set_up()` / `tear_down()` (snake_case), not PHPUnit's `setUp()` / `tearDown()`. Reason: PHPUnit 8 added a `void` return type to the camelCase fixtures, which breaks signature compatibility across PHP/PHPUnit versions. `yoast/phpunit-polyfills` (loaded by the WP test suite) exposes the snake_case variants and routes them to the correctly-typed camelCase methods per PHPUnit version. Never call `parent::setUp()` from a snake_case method — call `parent::set_up()`. Class-level fixtures are `set_up_before_class()` / `tear_down_after_class()`.
47
48	### The factory system
49
50	Build test data with factories instead of hand-inserting:
51
52	```php
53	$post_id = self::factory()->post->create( [ 'post_title' => 'Hello' ] );
54	$post = self::factory()->post->create_and_get(); // returns WP_Post
55	$user_id = self::factory()->user->create( [ 'role' => 'editor' ] );
56	$tag_ids = self::factory()->term->create_many( 3, [ 'taxonomy' => 'post_tag' ] );
57	$comment_id = self::factory()->comment->create( [ 'comment_post_ID' => $post_id ] );
58	```
59
60	`create()` returns an ID, `create_and_get()` the object, `create_many( $n, $args )` a batch. Factories exist for post, user, term, comment, attachment, and more. For fixtures shared across all tests in a class, create them once in the static hook and keep them in static properties:
61
62	```php
63	public static function wpSetUpBeforeClass( $factory ) {
64	self::$author_id = $factory->user->create( [ 'role' => 'author' ] );
65	}
66	```
67
68	Use the `$factory` argument passed in (not `self::factory()`) inside `wpSetUpBeforeClass()`.
69
70	### WP-specific assertions and helpers
71
72	- `assertWPError( $thing )` / `assertNotWPError

People who liked this also viewed

6 picks

Type

wp-phpunit-writing-tests

21stars1forks

View on GitHub

How to install wp-phpunit-writing-tests?

lonsdale201/wp-agent-skills/wp-phpunit-writing-tests

$npx -y skills add Lonsdale201/wp-agent-skills --skill wp-phpunit-writing-tests

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Writing WordPress PHPUnit tests
2
3	Once the harness is in place (`wp-phpunit-test-setup`), this skill is about the tests themselves: which base class, how to build fixtures, how to mock, and the integration-vs-unit decision that trips most people up.
4
5	## When to use this skill
6
7	- Writing the first real tests for a plugin/theme.
8	- Reviewing tests for correct fixtures, isolation, and mocking.
9	- Deciding between an integration test and a true unit test.
10	- Mocking outbound HTTP (`wp_remote_*`) or WP functions.
11
12	## Integration vs unit — get this right first
13
14	`WP_UnitTestCase` boots the full WordPress environment and uses a real (test) database, with each test wrapped in a transaction that is rolled back afterwards. Despite the name, that is an integration test, not a pure unit test. Use it when you need real WP behavior: DB writes, `WP_Query`, hooks firing against core, rewrite rules, user capabilities.
15
16	For true unit tests — fast, isolated, no WP boot, no DB — you mock WordPress functions with one of:
17
18	- Brain Monkey (`brain/monkey`, 2.7.x) — Mockery + Patchwork based; expressive `when()` / `expect()`.
19	- WP_Mock (`10up/wp_mock`, 1.1.x) — explicit per-function expectations, action/filter helpers.
20
21	Rule of thumb: test your own logic (a calculator, a formatter, a class method) as a unit test with mocked WP calls; test interaction with WordPress (it really saved the post, the hook really ran) as a `WP_UnitTestCase` integration test. Most plugins want both, in separate test suites.
22
23	## Integration tests: WP_UnitTestCase
24
25	### Fixtures are snake_case — and that matters
26
27	```php
28	class Test_My_Plugin extends WP_UnitTestCase {
29
30	public function set_up(): void {
31	parent::set_up(); // MUST be the first line
32	// per-test arrange
33	}
34
35	public function tear_down(): void {
36	// per-test cleanup
37	parent::tear_down(); // MUST be the last line
38	}
39
40	public function test_it_does_a_thing(): void {
41	$this->assertTrue( my_plugin_does_a_thing() );
42	}
43	}
44	```
45
46	Use `set_up()` / `tear_down()` (snake_case), not PHPUnit's `setUp()` / `tearDown()`. Reason: PHPUnit 8 added a `void` return type to the camelCase fixtures, which breaks signature compatibility across PHP/PHPUnit versions. `yoast/phpunit-polyfills` (loaded by the WP test suite) exposes the snake_case variants and routes them to the correctly-typed camelCase methods per PHPUnit version. Never call `parent::setUp()` from a snake_case method — call `parent::set_up()`. Class-level fixtures are `set_up_before_class()` / `tear_down_after_class()`.
47
48	### The factory system
49
50	Build test data with factories instead of hand-inserting:
51
52	```php
53	$post_id = self::factory()->post->create( [ 'post_title' => 'Hello' ] );
54	$post = self::factory()->post->create_and_get(); // returns WP_Post
55	$user_id = self::factory()->user->create( [ 'role' => 'editor' ] );
56	$tag_ids = self::factory()->term->create_many( 3, [ 'taxonomy' => 'post_tag' ] );
57	$comment_id = self::factory()->comment->create( [ 'comment_post_ID' => $post_id ] );
58	```
59
60	`create()` returns an ID, `create_and_get()` the object, `create_many( $n, $args )` a batch. Factories exist for post, user, term, comment, attachment, and more. For fixtures shared across all tests in a class, create them once in the static hook and keep them in static properties:
61
62	```php
63	public static function wpSetUpBeforeClass( $factory ) {
64	self::$author_id = $factory->user->create( [ 'role' => 'author' ] );
65	}
66	```
67
68	Use the `$factory` argument passed in (not `self::factory()`) inside `wpSetUpBeforeClass()`.
69
70	### WP-specific assertions and helpers
71
72	- `assertWPError( $thing )` / `assertNotWPError

People who liked this also viewed

6 picks

Type