Skip to content

Commit

Permalink
docs(Unittest): strip redundant tabs or replace with 4 spaces
Browse files Browse the repository at this point in the history
  • Loading branch information
kilofox committed Aug 4, 2023
1 parent 22ae718 commit 292f45f
Show file tree
Hide file tree
Showing 3 changed files with 89 additions and 89 deletions.
66 changes: 33 additions & 33 deletions modules/unittest/guide/unittest/test_doubles.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The `createMock()` and `getMockBuilder()` methods provided by PHPUnit can be use

Most of the time you'll only need to use the createMock() method, i.e.:

$mock = $this->createMock('ORM');
$mock = $this->createMock('ORM');

The creation of this mock is performed using best practice defaults. The `__construct` and `__clone` methods of the original class are not executed and the arguments passed to a method of the test double will not be cloned. If these defaults don't match your needs then you can use the `getMockBuilder() ` method to customize the test double generation. Here is a list of methods provided by the Mock Builder:

Expand All @@ -26,7 +26,7 @@ The creation of this mock is performed using best practice defaults. The `__cons

You start off by telling PHPUnit how many times the method should be called by calling expects() on the mock object:

$mock->expects($matcher);
$mock->expects($matcher);

`expects()` takes one argument, an invoker matcher which you can create using factory methods defined in `PHPUnit_Framework_TestCase`:

Expand All @@ -52,29 +52,29 @@ You start off by telling PHPUnit how many times the method should be called by c

In our example we want `check()` to be called once on our mock object, so if we update it accordingly:

$mock = $this->getMockBuilder('ORM')
->setMethods(['check'])
->getMock();
$mock->expects($this->once());
$mock = $this->getMockBuilder('ORM')
->setMethods(['check'])
->getMock();

$mock->expects($this->once());

### What is the method we're mocking?

Although we told PHPUnit what methods we want to mock, we haven't actually told it what method these rules we're specifiying apply to.
You do this by calling `method()` on the returned from `expects()`:

$mock->expects($matcher)
->method($methodName);
$mock->expects($matcher)
->method($methodName);

As you can probably guess, `method()` takes one parameter, the name of the method you're mocking.
There's nothing very fancy about this function.

$mock = $this->getMockBuilder('ORM')
->setMethods(['check'])
->getMock();
$mock->expects($this->once())
->method('check');
$mock = $this->getMockBuilder('ORM')
->setMethods(['check'])
->getMock();

$mock->expects($this->once())
->method('check');


### What parameters should our mock method expect?
Expand All @@ -86,20 +86,20 @@ There are two ways to do this, either

The former can be achieved by calling `withAnyParameters()` on the object returned from `method()`.

$mock->expects($matcher)
->method($methodName)
->withAnyParameters();
$mock->expects($matcher)
->method($methodName)
->withAnyParameters();

To only allow specific parameters you can use the `with()` method which accepts any number of parameters.
The order in which you define the parameters is the order that it expects them to be in when called.

$mock->expects($matcher)
->method($methodName)
->with($param1, $param2);
$mock->expects($matcher)
->method($methodName)
->with($param1, $param2);

Calling `with()` without any parameters will force the mock method to accept no parameters.

PHPUnit has a fairly complex way of comparing parameters passed to the mock method with the expected values, which can be summarised like so -
PHPUnit has a fairly complex way of comparing parameters passed to the mock method with the expected values, which can be summarised like so -

* If the values are identical, they are equal.
* If the values are of different types they are not equal.
Expand All @@ -118,9 +118,9 @@ If a parameter passed to `with()` is not an instance of a constraint object (one

i.e., the following methods produce the same result:

->with('foo', 1);
->with($this->equalTo('foo'), $this->equalTo(1));
->with('foo', 1);

->with($this->equalTo('foo'), $this->equalTo(1));

Here are some of the wrappers PHPUnit provides for creating constraint objects:

Expand Down Expand Up @@ -183,9 +183,9 @@ There are more constraint objects than listed here, look in `PHPUnit_Framework_A

If we continue our example, we have the following:

$mock->expects($this->once())
->method('check')
->with();
$mock->expects($this->once())
->method('check')
->with();

So far PHPUnit knows that we want the `check()` method to be called once, with no parameters. Now we just need to get it to return something.

Expand All @@ -203,7 +203,7 @@ Specifying a return value is easy, just call `will()` on the object returned by

The function is defined like so:

public function will(PHPUnit_Framework_MockObject_Stub $stub)
public function will(PHPUnit_Framework_MockObject_Stub $stub)

PHPUnit provides some MockObject stubs out of the box, you can access them via (when called from a testcase):

Expand All @@ -222,10 +222,10 @@ Obviously if you really want to you can create your own MockObject stub, but the

Updating our example gives:

$mock->expects($this->once())
->method('check')
->with()
->will($this->returnValue(true));
$mock->expects($this->once())
->method('check')
->with()
->will($this->returnValue(true));

And we're done!

Expand Down
110 changes: 55 additions & 55 deletions modules/unittest/guide/unittest/testing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Usage

$ phpunit --bootstrap=modules/unittest/bootstrap.php modules/unittest/tests.php
$ phpunit --bootstrap=modules/unittest/bootstrap.php modules/unittest/tests.php

Alternatively you can use a phpunit.xml to have a more fine grained control over which tests are included and which files are whitelisted.

Expand All @@ -22,26 +22,26 @@ Sometimes you want to be able to run a specific test with different sets of data

Ordinarily you could use a foreach loop to iterate over an array of test data, however PHPUnit already can take care of this for us rather easily using "Data Providers". A data provider is a function that returns an array of arguments that can be passed to a test.

<?php

Class ReallyCoolTest extends Unittest_TestCase
{
public function providerStrLen()
{
return [
['One set of testcase data', 24],
['This is a different one', 23],
];
}

/**
* @dataProvider providerStrLen
*/
public function testStrLen($string, $length)
{
$this->assertSame($length, strlen($string));
}
}
<?php

Class ReallyCoolTest extends Unittest_TestCase
{
public function providerStrLen()
{
return [
['One set of testcase data', 24],
['This is a different one', 23],
];
}

/**
* @dataProvider providerStrLen
*/
public function testStrLen($string, $length)
{
$this->assertSame($length, strlen($string));
}
}

The key thing to notice is the `@dataProvider` tag in the DocComment, this is what tells PHPUnit to use a data provider. The provider prefix is totally optional but it's a nice standard to identify providers.

Expand All @@ -53,54 +53,54 @@ For more info see:

To allow users to selectively run tests you need to organise your tests into groups. Here's an example test showing how to do this:

<?php

/**
* This is a description for my testcase.
*
* @group somegroup
* @group somegroup.morespecific
*/
Class AnotherReallyCoolTest extends Unittest_TestCase
{
/**
* Tests can also be grouped too!
*
* @group somegroup.morespecific.annoyingstuff
*/
public function testSomeAnnoyingCase()
{
// CODE!!
}
}
<?php

/**
* This is a description for my testcase.
*
* @group somegroup
* @group somegroup.morespecific
*/
Class AnotherReallyCoolTest extends Unittest_TestCase
{
/**
* Tests can also be grouped too!
*
* @group somegroup.morespecific.annoyingstuff
*/
public function testSomeAnnoyingCase()
{
// CODE!!
}
}

Our convention is to use lowercase group names, with more specific levels in a group separated by periods. For example, the Validate helper tests are part of the following groups:

kohana
kohana.validation
kohana.validation.helpers
kohana
kohana.validation
kohana.validation.helpers

To actually limit your testing to the "somegroup" group, use:

$ phpunit --boostrap=modules/unittest/bootstrap.php --group=somegroup modules/unittest/tests.php
$ phpunit --boostrap=modules/unittest/bootstrap.php --group=somegroup modules/unittest/tests.php

This functionality can be used to record which bug reports a test is for:

/**
*
* @group bugs.1477
*/
function testAccountCannotGoBelowZero()
{
// Some arbitary code
}
/**
*
* @group bugs.1477
*/
function testAccountCannotGoBelowZero()
{
// Some arbitary code
}

To see all groups that are available in your code run:

$ phpunit --boostrap=modules/unittest/bootstrap.php --list-groups modules/unittest/tests.php
$ phpunit --boostrap=modules/unittest/bootstrap.php --list-groups modules/unittest/tests.php

*Note:* The `--list-groups` switch should appear before the path to the test suite loader.

You can also exclude groups while testing using the `--exclude-group` switch. This can be useful if you want to ignore all kohana tests:

$ phpunit --bootstrap=modules/unittest/bootstrap.php --exclude-group=kohana modules/unittest/tests.php
$ phpunit --bootstrap=modules/unittest/bootstrap.php --exclude-group=kohana modules/unittest/tests.php
2 changes: 1 addition & 1 deletion modules/unittest/guide/unittest/testing_workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ If you're developing in a text editor such as textmate, vim, gedit etc. chances

In such situations you can run a simple bash script to loop over the tests every X seconds, here's an example script:

while(true) do clear; phpunit; sleep 8; done;
while(true) do clear; phpunit; sleep 8; done;

You will probably need to adjust the timeout (`sleep 8`) to suit your own workflow, but 8 seconds seems to be about enough time to see what's erroring before the tests are re-run.

Expand Down

0 comments on commit 292f45f

Please sign in to comment.