Skip to content

Commit 7a2c971

Browse files
kenjiskenjis
committed
docs: update README
1 parent d94d67e commit 7a2c971

File tree

1 file changed

+306
-9
lines changed

1 file changed

+306
-9
lines changed

‎README.md

Lines changed: 306 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,311 @@
1-
# kenjis/php-unit-helper
1+
# PHPUnit Heler
2+
3+
Provides helper traits for PHPUnit.
24

35
## Installation
46

5-
composer install
7+
Run
8+
9+
```sh
10+
$ composer require --dev kenjis/phpunit-helper
11+
```
12+
13+
## Usage
14+
15+
### `TestDouble`
16+
17+
This trait provides helper methods to create mock objects and to verify invocations.
18+
19+
Import the `Kenjis\PhpUnitHelper\TestDouble` trait into your test class:
20+
21+
```php
22+
<?php
23+
24+
declare(strict_types=1);
25+
26+
namespace Foo\Bar\Test\Unit;
27+
28+
use Kenjis\PhpUnitHelper\TestDouble;
29+
use PHPUnit\Framework;
30+
31+
final class BazTest extends Framework\TestCase
32+
{
33+
use TestDouble;
34+
}
35+
```
36+
37+
#### `$this->getDouble()`
38+
39+
| param | type | description |
40+
|---------------------|-------------|--------------------------------------------------------|
41+
|`$classname` | string | class name |
42+
|`$params` | array | [method_name => return_value] |
43+
| | | [[method_name => [return_value1, return_value2 [, ...]]] |
44+
|`$constructor_params`| false/array | false: disable constructor / array: constructor params |
45+
46+
`returns` (object) PHPUnit mock object.
47+
48+
Gets PHPUnit mock object.
49+
50+
```php
51+
$email = $this->getMockBuilder(CI_Email::class)
52+
->disableOriginalConstructor()
53+
->setMethods(['send'])
54+
->getMock();
55+
$email->method('send')
56+
->willReturn(true);
57+
```
58+
59+
You could write code above like below:
60+
61+
```php
62+
$email = $this->getDouble(CI_Email::class, ['send' => true]);
63+
```
64+
65+
You can set Closure as the return value of a mocked method.
66+
67+
```php
68+
$ret = function () {
69+
throw new RuntimeException('Cannot send email!');
70+
};
71+
$mock = $this->getDouble(CI_Email::class, ['send' => $ret]);
72+
```
73+
74+
You can also set the mock itself as the return value of a mocked method with using `$this->returnSelf()`.
75+
76+
```php
77+
$mock = $this->getDouble(CI_Email::class, [
78+
'to' => $this->returnSelf(),
79+
'subject' => $this->returnSelf(),
80+
'send' => true,
81+
]);
82+
```
83+
84+
You can create mocks with consecutive calls.
85+
86+
```php
87+
$mock = $this->getMockBuilder(CI_Email::class)
88+
->disableOriginalConstructor()
89+
->setMethods(['method'])
90+
->getMock();
91+
$mock->expects($this->any())->method('method')
92+
->will($this->onConsecutiveCalls('GET', 'POST' ,'DELETE'));
93+
```
94+
95+
You could write code above like below:
96+
97+
```php
98+
$mock = $this->getDouble(
99+
CI_Input::class,
100+
[
101+
['method' => ['GET', 'POST' ,'DELETE']],
102+
]
103+
);
104+
```
105+
106+
#### `$this->verifyInvoked()`
107+
108+
| param | type | description |
109+
|---------|--------|---------------------|
110+
|`$mock` | object | PHPUnit mock object |
111+
|`$method`| string | method name |
112+
|`$params`| array | arguments |
113+
114+
Verifies a method was invoked at least once.
115+
116+
```php
117+
$loader->expects($this->atLeastOnce())
118+
->method('view')
119+
->with(
120+
'shopConfirm', $this->anything(), true
121+
);
122+
```
123+
124+
You could write code above like below:
125+
126+
```php
127+
$this->verifyInvoked(
128+
$loader,
129+
'view',
130+
[
131+
'shopConfirm', $this->anything(), TRUE
132+
]
133+
);
134+
```
135+
136+
#### `$this->verifyInvokedOnce()`
137+
138+
| param | type | description |
139+
|---------|--------|---------------------|
140+
|`$mock` | object | PHPUnit mock object |
141+
|`$method`| string | method name |
142+
|`$params`| array | arguments |
143+
144+
Verifies that method was invoked only once.
145+
146+
```php
147+
$loader->expects($this->once())
148+
->method('view')
149+
->with(
150+
'shopConfirm', $this->anything(), true
151+
);
152+
```
153+
154+
You could write code above like below:
155+
156+
```php
157+
$this->verifyInvokedOnce(
158+
$loader,
159+
'view',
160+
[
161+
'shopConfirm', $this->anything(), true
162+
]
163+
);
164+
```
165+
166+
#### `$this->verifyInvokedMultipleTimes()`
167+
168+
| param | type | description |
169+
|---------|--------|---------------------|
170+
|`$mock` | object | PHPUnit mock object |
171+
|`$method`| string | method name |
172+
|`$times` | int | times |
173+
|`$params`| array | arguments |
174+
175+
Verifies that method was called exactly $times times.
176+
177+
```php
178+
$loader->expects($this->exactly(2))
179+
->method('view')
180+
->withConsecutive(
181+
['shopConfirm', $this->anything(), true],
182+
['shopTmplCheckout', $this->anything()]
183+
);
184+
```
185+
186+
You could write code above like below:
187+
188+
```php
189+
$this->verifyInvokedMultipleTimes(
190+
$loader,
191+
'view',
192+
2,
193+
[
194+
['shopConfirm', $this->anything(), true],
195+
['shopTmplCheckout', $this->anything()]
196+
]
197+
);
198+
```
199+
200+
#### `$this->verifyNeverInvoked()`
201+
202+
| param | type | description |
203+
|---------|--------|---------------------|
204+
|`$mock` | object | PHPUnit mock object |
205+
|`$method`| string | method name |
206+
|`$params`| array | arguments |
207+
208+
Verifies that method was not called.
209+
210+
```php
211+
$loader->expects($this->never())
212+
->method('view')
213+
->with(
214+
'shopConfirm', $this->anything(), true
215+
);
216+
```
217+
218+
You could write code above like below:
219+
220+
```php
221+
$this->verifyNeverInvoked(
222+
$loader,
223+
'view',
224+
[
225+
'shopConfirm', $this->anything(), true
226+
]
227+
);
228+
```
229+
230+
### `ReflectionHelper`
231+
232+
This trait provides helper methods to access private or protected properties and methods.
233+
234+
But generally it is not recommended testing non-public properties or methods, so think twice before you use the methods in this trait.
235+
236+
Import the `Kenjis\PhpUnitHelper\ReflectionHelper` trait into your test class:
237+
238+
```php
239+
<?php
240+
241+
declare(strict_types=1);
242+
243+
namespace Foo\Bar\Test\Unit;
244+
245+
use Kenjis\PhpUnitHelper\ReflectionHelper;
246+
use PHPUnit\Framework;
247+
248+
final class BazTest extends Framework\TestCase
249+
{
250+
use ReflectionHelper;
251+
}
252+
```
253+
254+
#### `$this->getPrivateProperty()`
255+
256+
| param | type | description |
257+
|-----------|---------------|---------------------|
258+
|`$obj` | object/string | object / class name |
259+
|`$property`| string | property name |
260+
261+
`returns` (mixed) property value.
262+
263+
Gets private or protected property value.
264+
265+
~~~php
266+
$obj = new SomeClass();
267+
$private_propery = $this->getPrivateProperty(
268+
$obj,
269+
'privatePropery'
270+
);
271+
~~~
272+
273+
#### `$this->setPrivateProperty()`
274+
275+
| param | type | description |
276+
|-----------|---------------|---------------------|
277+
|`$obj` | object/string | object / class name |
278+
|`$property`| string | property name |
279+
|`$value` | mixed | value |
280+
281+
Sets private or protected property value.
282+
283+
~~~php
284+
$obj = new SomeClass();
285+
$this->setPrivateProperty(
286+
$obj,
287+
'privatePropery',
288+
'new value'
289+
);
290+
~~~
291+
292+
#### `$this->getPrivateMethodInvoker()`
293+
294+
| param | type | description |
295+
|---------|---------------|---------------------|
296+
|`$obj` | object/string | object / class name |
297+
|`$method`| string | method name |
298+
299+
`returns` (closure) method invoker.
6300

7-
## Available Commands
301+
Gets private or protected method invoker.
8302

9-
composer test // Run unit test
10-
composer tests // Test and quality checks
11-
composer cs-fix // Fix the coding style
12-
composer sa // Run static analysys tools
13-
composer run-script --list // List all commands
14-
303+
~~~php
304+
$obj = new SomeClass();
305+
$method = $this->getPrivateMethodInvoker(
306+
$obj, 'privateMethod'
307+
);
308+
$this->assertEquals(
309+
'return value of the privateMethod() method', $method()
310+
);
311+
~~~

0 commit comments

Comments
 (0)