Skip to content

Commit 66989ae

Browse files
dereuromarkdereuromark
authored
Update PHPUnit documentation for CakePHP 5.x requirements (#8186)
CakePHP 5.x now requires PHPUnit ^11.5.3 || ^12.1.3, making the previous PHPUnit 10 documentation outdated. This updates the guide to cover: - Current version requirements (PHPUnit 11.5+ or 12.1+) - Migration from annotations to PHP 8 attributes - Data provider static requirements - Test double changes (createStub vs createMock) - PHPUnit 12 specific breaking changes - Comprehensive upgrade checklist Fixes #8172
1 parent 0e83463 commit 66989ae

1 file changed

Lines changed: 114 additions & 32 deletions

File tree

‎docs/en/appendices/phpunit10.md‎

Lines changed: 114 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
1-
# PHPUnit 10 Upgrade
1+
# PHPUnit Migration Guide
22

3-
With CakePHP 5 the minimum PHPUnit version has changed from `^8.5 || ^9.3` to `^10.1`. This introduces a few breaking changes from PHPUnit as well as from CakePHP's side.
3+
This guide covers the PHPUnit version requirements and migration steps for CakePHP 5.x applications.
4+
5+
## Current Requirements
6+
7+
CakePHP 5.x requires **PHPUnit ^11.5.3 or ^12.1.3**. This means:
8+
9+
- PHPUnit 11.5.3+ requires **PHP 8.2** or later
10+
- PHPUnit 12.1.3+ requires **PHP 8.3** or later
11+
12+
> [!NOTE]
13+
> PHPUnit 10 is no longer supported in CakePHP 5.x. If you are still on PHPUnit 10,
14+
> you must upgrade to PHPUnit 11 or 12.
415
516
## phpunit.xml adjustments
617

@@ -9,60 +20,131 @@ It is recommended to let PHPUnit update its configuration file via the following
920
vendor/bin/phpunit --migrate-configuration
1021

1122
> [!NOTE]
12-
> Make sure you are already on PHPUnit 10 via `vendor/bin/phpunit --version` before executing this command!
23+
> Make sure you verify your PHPUnit version via `vendor/bin/phpunit --version` before executing this command!
1324
14-
With this command out of the way your `phpunit.xml` already has most of the recommended changes present.
25+
### Extension Configuration
1526

16-
### New event system
27+
CakePHP's fixture extension uses PHPUnit's event system. Your `phpunit.xml` should have:
1728

18-
PHPUnit 10 removed the old hook system and introduced a new [Event system](https://docs.phpunit.de/en/10.5/extending-phpunit.html#extending-the-test-runner)
19-
which requires the following code in your `phpunit.xml` to be adjusted from:
20-
21-
``` php
29+
``` xml
2230
<extensions>
23-
<extension class="Cake\TestSuite\Fixture\PHPUnitExtension"/>
31+
<bootstrap class="Cake\TestSuite\Fixture\Extension\PHPUnitExtension"/>
2432
</extensions>
2533
```
2634

27-
to:
35+
## Migrating from PHPUnit 10 to 11
36+
37+
### Annotations to Attributes
38+
39+
PHPUnit 11 deprecates docblock annotations and PHPUnit 12 removes them entirely.
40+
You should migrate to PHP 8 attributes:
2841

2942
``` php
30-
<extensions>
31-
<bootstrap class="Cake\TestSuite\Fixture\Extension\PHPUnitExtension"/>
32-
</extensions>
43+
// Old way (deprecated in PHPUnit 11, removed in PHPUnit 12)
44+
/**
45+
* @dataProvider myProvider
46+
*/
47+
public function testSomething($value): void
48+
{
49+
}
50+
51+
// New way (required for PHPUnit 12+)
52+
use PHPUnit\Framework\Attributes\DataProvider;
53+
54+
#[DataProvider('myProvider')]
55+
public function testSomething($value): void
56+
{
57+
}
3358
```
3459

35-
## `->withConsecutive()` has been removed
60+
Common attributes to use:
61+
62+
| Old Annotation | New Attribute |
63+
|---------------|---------------|
64+
| `@test` | `#[Test]` |
65+
| `@dataProvider name` | `#[DataProvider('name')]` |
66+
| `@depends methodName` | `#[Depends('methodName')]` |
67+
| `@group name` | `#[Group('name')]` |
68+
| `@covers ClassName` | `#[CoversClass(ClassName::class)]` |
69+
| `@uses ClassName` | `#[UsesClass(ClassName::class)]` |
70+
71+
Remember to import the attribute classes from `PHPUnit\Framework\Attributes`.
3672

37-
You can convert the removed `->withConsecutive()` method to a
38-
working interim solution like you can see here:
73+
### Data Providers Must Be Static
74+
75+
Data provider methods must be both `public` and `static`:
3976

4077
``` php
41-
->withConsecutive(['firstCallArg'], ['secondCallArg'])
78+
// Required format
79+
public static function myProvider(): array
80+
{
81+
return [
82+
['value1'],
83+
['value2'],
84+
];
85+
}
4286
```
4387

44-
should be converted to:
88+
### Test Double Changes
89+
90+
PHPUnit 11 made changes to mock object creation:
91+
92+
- **Use `createStub()`** when you only need to stub return values and don't need
93+
to verify method calls
94+
- **Use `createMock()`** when you need to set expectations and verify interactions
4595

4696
``` php
47-
->with(
48-
...self::withConsecutive(['firstCallArg'], ['secondCallArg'])
49-
)
97+
// For isolating dependencies (no expectations)
98+
$stub = $this->createStub(SomeClass::class);
99+
$stub->method('getValue')->willReturn('test');
100+
101+
// For testing object communication (with expectations)
102+
$mock = $this->createMock(SomeClass::class);
103+
$mock->expects($this->once())
104+
->method('doSomething')
105+
->with('argument');
50106
```
51107

52-
the static `self::withConsecutive()` method has been added via the `Cake\TestSuite\PHPUnitConsecutiveTrait`
53-
to the base `Cake\TestSuite\TestCase` class so you don't have to manually add that trait to your Testcase classes.
108+
> [!WARNING]
109+
> Configuring expectations (like `expects()`) on objects created with `createStub()`
110+
> triggers deprecation warnings in PHPUnit 11 and errors in PHPUnit 12.
111+
112+
## Migrating from PHPUnit 11 to 12
113+
114+
PHPUnit 12 requires **PHP 8.3** or later and enforces all deprecations from PHPUnit 11:
115+
116+
- Docblock annotations are completely removed
117+
- Expectations on stubs are no longer allowed
118+
- Abstract class and trait mocking methods are removed
119+
120+
Run your test suite with PHPUnit 11.5 and resolve all deprecation warnings before
121+
upgrading to PHPUnit 12.
122+
123+
## CakePHP Test Utilities
54124

55-
## data providers have to be static
125+
### withConsecutive() Replacement
56126

57-
If your testcases leverage the data provider feature of PHPUnit then
58-
you have to adjust your data providers to be static:
127+
The removed `->withConsecutive()` method can be replaced using CakePHP's trait:
59128

60129
``` php
61-
public function myProvider(): array
130+
// Old way (removed in PHPUnit 10+)
131+
->withConsecutive(['firstCallArg'], ['secondCallArg'])
132+
133+
// New way using CakePHP's trait
134+
->with(
135+
...self::withConsecutive(['firstCallArg'], ['secondCallArg'])
136+
)
62137
```
63138

64-
should be converted to:
139+
The static `self::withConsecutive()` method is provided via the `Cake\TestSuite\PHPUnitConsecutiveTrait`
140+
which is automatically included in the base `Cake\TestSuite\TestCase` class.
65141

66-
``` text
67-
public static function myProvider(): array
68-
```
142+
## Upgrade Checklist
143+
144+
Before upgrading PHPUnit versions, ensure:
145+
146+
1. Your test suite runs without deprecation warnings on your current PHPUnit version
147+
2. All data providers are `public static` methods
148+
3. You're using attributes instead of annotations (required for PHPUnit 12)
149+
4. Mock expectations are only used with `createMock()`, not `createStub()`
150+
5. Run `vendor/bin/phpunit --migrate-configuration` after upgrading

0 commit comments

Comments
 (0)