Running tests in separate processes
PHPUnit offers the possibility to run tests in a separate PHP process; Codeception does not officially support the option as of version 4.0.
The wp-browser project tries to fill that gap by supporting the
@runInSeparateProcess annotation.
This support comes with some caveats, though:- 1.The support is only for test cases extending the
Codeception\TestCase\WPTestCaseclass (the base test case for integration or "WordPress unit" tests) - 2.The support wp-browser provides only supports the
@preserveGlobalStateannotation with thedisabledvalue; this means there is no support for preserving global state between tests.
Read more about what this means in PHPUnit documentation.
Why run tests in a separate PHP process?
One main reason: isolation.
What does "isolation" means?
Before answering that question, it's essential to understand, via an example, why a lack of isolation might be an issue.
I want to test the
get_api function. The function will return the correct singleton instance of an API handling class: an instance of Api when the function is called in non-admin context, and an instance of AdminApi when the function is called in admin context. The get_api function is acting as a service locator.1
<?php
2
function get_api(){
3
static $api;
4
​
5
if(null !== $api){
6
return $api;
7
}
8
​
9
if( is_admin() ) {
10
$api = new Admin_Api();
11
} else {
12
$api = new Api();
13
}
14
​
15
return $api;
16
}
Copied!
There are two challenges to testing this function:
- 1.The
is_adminfunction, defined by WordPress, looks up aWP_ADMINconstant to know if the context of the current request is an administration UI one or not. - 2.The
get_apifunction will check for the context and resolve and build the correct instance only once, the first time it's called in the context of a request.
There are some possible solutions to this problem:
a. Refactor the
get_api function into a method of an Api_Factory object taking the context as a dependency, thus allowing injection of the "context" (which implies the creation of a Context adapter that will proxy its is_admin method to the is_admin function). You can find the code for such refactoring in the OOP refactoring of get_api section. b. Refactor the get_api function to accept the current is_admin value as an input argument, get_api( $is_admin ), this refactoring moves part of the complexity of getting hold of the correct instance of the API handler on the client code. Adding more build condition and checks, e.g., if the current request is a REST request or not or some tests on the user authorizations, then, requires adding more input arguments to the get_api function: the knowledge of the implementation of the get_api method will "leak" to the client code having to replicate complexity throughout the system.I want to layout possible solutions to the problem to show there is always a design alternative to make code testable that might or might not fit the current time or scope constraint.
In this example, I've inherited the
get_api function from the existing code, and it cannot be changed, yet I want to test it dealing with the two problems outlined above.Running tests in separate PHP processes
To test the
get_api function shown above I've created a new wpunit type of test:1
vendor/bin/codecept g:wpunit integration "api"
Copied!
The command scaffolds a
test/integration/apiTest.php file that I've modified to ensure full coverage of the get_api function:1
<?php
2
​
3
class apiTest extends \Codeception\TestCase\WPTestCase
4
{
5
public function test_get_api_exists()
6
{
7
$this->assertTrue(function_exists('get_api'));
8
}
9
​
10
public function test_get_api_will_cache()
11
{
12
$this->assertSame(get_api(), get_api());
13
}
14
​
15
/**
16
* @runInSeparateProcess
17
* @preserveGlobalState disabled
18
*/
19
public function test_get_api_will_return_api_if_not_admin()
20
{
21
// Let's make sure we're NOT in admin context.
22
define('WP_ADMIN', false);
23
​
24
$api = get_api();
25
​
26
$this->assertInstanceOf(Api::class, $api);
27
}
28
​
29
/**
30
* @runInSeparateProcess
31
* @preserveGlobalState disabled
32
*/
33
public function test_get_api_will_cache_api_if_not_admin()
34
{
35
// Let's make sure we're NOT in admin context.
36
define('WP_ADMIN', false);
37
​
38
$api = get_api();
39
​
40
$this->assertSame(get_api(), $api);
41
}
42
​
43
/**
44
* @runInSeparateProcess
45
* @preserveGlobalState disabled
46
*/
47
public function test_get_api_will_return_api_if_is_admin()
48
{
49
// Let's make sure we're NOT in admin context.
50
define('WP_ADMIN', true);
51
​
52
$api = get_api();
53
​
54
$this->assertInstanceOf(AdminApi::class, $api);
55
}
56
​
57
/**
58
* @runInSeparateProcess
59
* @preserveGlobalState disabled
60
*/
61
public function test_get_api_will_cache_api_if_is_admin()
62
{
63
// Let's make sure we're NOT in admin context.
64
define('WP_ADMIN', true);
65
​
66
$api = get_api();
67
​
68
$this->assertSame(get_api(), $api);
69
}
70
}
Copied!
Some pieces of this code are worth pointing out:
- 1.There are two test methods,
test_get_api_existsandtest_get_api_will_cachethat are not running in a separate process. Running tests in a separate process provide isolation at the cost of speed, only tests that require isolation should run in a separate PHP process. - 2.I instruct the Codeception and PHPUnit test runner to run a test method in a different process by adding two annotations that are both required precisely as shown:1/**2* @runInSeparateProcess3* @preserveGlobalState disabled4*/Copied!
- 3.The isolation part of this testing approach shines through when I
define, in the last four tests, theWP_ADMINconstant multiple times. If I try to do that in test code running in the same PHP process, then the seconddefinecall would cause a fatal error. - 4.The isolation has also taken care of the second issue where the
get_apifunction caches the$apiinstance after its first resolution in astaticvariable: since each test happens in a self-contained, dedicated PHP process, thestatic $apivariable will benullat the start of each test.
Can I run some tests in the same process and some in a separate process?
Yes. In the example test code in the previous section, the
test_get_api_exists and test_get_api_will_cache test methods are not running in separate processes.In your test cases extending the
Codeception\TestCase\WPTestCase, you can mix test methods running in the primary PHP process and those running in a separate PHP process without issues.OOP refactoring of get_api
In the Why run tests in a separate PHP process? section I've outlined a possible refactoring of the
get_api function to make it testable without requiring the use of separate PHP processes.I'm providing this refactoring code below for the sake of completeness, the judgment of which approach is "better" is up to the reader.
1
<?php
2
​
3
class Context_Adapter{
4
​
5
public function is_admin(){
6
return \is_admin();
7
}
8
​
9
}
10
​
11
class Api_Factory{
12
​
13
private $api;
14
private $context;
15
​
16
public function __construct(Context_Adapter $context){
17
$this->context = $context;
18
}
19
​
20
public function getApi(){
21
if(null !== $this->api){
22
return $this->api;
23
}
24
​
25
if($this->context->is_admin()){
26
$api = new Admin_Api;
27
} else {
28
$api = new Api;
29
}
30
​
31
return $api;
32
}
33
}
Copied!
Now the
Api_Factory class can be injected by injecting a mocked Context_Adapter class, modifying the return value of the Context_Adapter::is_admin method.Due to the supposed requirement of the API instance being a singleton, this solution will also require some container or service-locator to ensure at most only one instance of the
Api_Factory exists at any given time in the context of a request.Last modified 2yr ago