sebastianbergmann / phpunit-documentation Goto Github PK
View Code? Open in Web Editor NEWDocumentation for PHPUnit.
Home Page: https://phpunit.de/documentation.html
Documentation for PHPUnit.
Home Page: https://phpunit.de/documentation.html
Using the PHPUnit_Story
extension is discouraged and its development has stopped a long time ago. The logical next step is to remove the documentation for it.
Would it be possible to have some directions on how to recompile the docs ?
I'm caring because I'm thinking about packaging it for Debian, and would rather do it from the source in git, than from wgotten HTML pages
Thanks in advance.
In the documentation, $this call is used everywhere, e.g. $this->assertArrayHasKey, $this->assertEquals, etc.
However, those functions are all static functions.
Though PHP does support that, would it be great to use the 'right way' to call a static function?
I checked some other Unit, they are using Assert.assert.
I don't know how to get rid of those warnings. I assume I'd need to install some fonts to properly build the JA docs.
Can someone, maybe @m-takagi ?, add a little note to the readme what to do to avoid those warnigs?
WARNING: Glyph "テ" (0x30c6, tekatakana) not available in font "Times-Bold"
The manual does not tell one that the @dataProvider method is executed before setUp is run.
See sebastianbergmann/phpunit#936
I don't think many folks have problems downloading the library, but you can put the following into the PHAR section of the installation page (http://phpunit.de/manual/3.8/en/installation.html):
Use your browser or a command line tool to download the PHP archive (PHAR).
wget http://pear.phpunit.de/get/phpunit.phar
curl -O http://pear.phpunit.de/get/phpunit.phar
Navigate to http://pear.phpunit.de/get/phpunit.phar
in the browser of your choice.
Next, you should clarify the conventions at the top of the "Writing Tests for PHP Unit" page (http://phpunit.de/manual/3.8/en/writing-tests-for-phpunit.html), specifically number 3 should be more clear about the naming convention and it should provide an example of the docblock syntax. Consider the following:
The tests are public methods that are named test* (i.e. the function names in your class must begin with "test", e.g. "function test1" or "function test_log")
Alternatively, you can use the @test annotation in a method's docblock to mark it as a test method. For example:
/**
* This is my docblock that uses the test annotation.
* @test
*/
function test_something() {
// ... test goes here
}
-- You should clarify that the class name is not important. It normally matches the filename, but this is not required.
-- I think you also need to clarify if and when a test function accepts arguments. It would be appropriate to say something like "A test function may also accept arguments supplied by a function named "provider". See example 4.4."
However, you should probably clean up 4.4 -- it's not clear that the function name must be "provider" and it's not clear why it returns an array with 4 elements, but the function only accepts 3 arguments. Is that intentional? Or am I missing something? Is it getting the function name from the "dataProvider" docblock attribute? You can see how little things like that can be misleading. Every time you have some variation or behavior like that, you need to have at least 2 examples that demonstrate the behavior and a variant, otherwise, people fall off the wagon.
Next you need to provide full examples showing how to execute tests, including variations for executing them using the library installed via composer, via pear, or as a .phar. The following bit should be on the http://phpunit.de/manual/3.8/en/writing-tests-for-phpunit.html page. I would recommend you create a new section called "Running the Tests". Consider the following.
To demonstrate how to run PHP Unit tests, let's consider a simple test that asserts that 1 + 1 = 2. Copy and paste the following into a file named "MyFirstTest.php":
<?php
class MyFirstTest extends PHPUnit_Framework_TestCase
{
public function testFirst()
{
$this->assertEquals(1 + 1, 2);
}
}
?>
Next we will demonstrate how to run these tests. In all the variations
Make sure you've downloaded the PHAR into the same directory as your test class, so that your directory contents look something like this:
From that directory, run the following command:
php phpunit.phar MyFirstTest
Note that the name of the test (MyFirstTest) is the name of the file, minus the ".php" extension.
If you have installed PHP Unit via Composer, you can run your tests using the "phpunit" command:
vendor/bin/phpunit MyFirstTest
This is actually the install method that's being assumed in most of the documentation.
phpunit MyFirstTest
No matter which method you use to execute your test, you should see something like the following upon successful execution:
$ php phpunit.phar MyFirstTest.php
PHPUnit 3.7.21 by Sebastian Bergmann.
.
Time: 0 seconds, Memory: 2.50Mb
OK (1 test, 1 assertion)
Typically, your test classes will contain multiple testing functions. Let's augment our example of a test that succeeds (1 + 1 = 2) with a test that fails (2 + 2 = 5). Edit MyFirstTest.php so it looks like the following.
<?php
class MyFirstTest extends PHPUnit_Framework_TestCase
{
public function testFirst()
{
$this->assertEquals(1 + 1, 2);
}
public function testSecond()
{
$this->assertEquals(2 + 2, 5);
}
}
?>
Now when you run this test, your output should reflect some success and some failures. Execute the tests using the same command you used above. But now the output should look something like the following:
PHPUnit 3.7.21 by Sebastian Bergmann.
.F
Time: 0 seconds, Memory: 2.75Mb
There was 1 failure:
1) MyFirstTest::testSecond
Failed asserting that 5 matches expected 4.
/path/to/MyFirstTest.php:10
FAILURES!
Tests: 2, Assertions: 2, Failures: 1.
Sorry if this seems trivial and pedantic, but your docs are missing this section.
The phpunit documentation website is missing links to the following annotations on the left navigation
@codeCoverageIgnore
, @codeCoverageIgnoreStart
and @codeCoverageIgnoreEnd
The 3.6 fixtures example will no longer work since test output is swallowed in 3.6.
I am wondering whether maintaining separate versions of the PHPUnit Manual per version of PHPUnit is worth the effort.
Hello,
A. I've noticed a minor error on example about Story extension for Bowling example.
In chapter 13 on output result we may see
phpunit --printer PHPUnit_Extensions_Story_ResultPrinter_Text BowlingGameSpec
PHPUnit 3.6.0 by Sebastian Bergmann.
As --printer option does not exists, it should be replaced by --testdox
BTW, you should also add a note that users may use a --bootstrap to use Story extension Autoload
phpunit
--bootstrap \php-5.2.17\PEAR\PHPUnit\Extensions\Story\Autoload.php
--testdox BowlingGameSpec \path_to\BowlingGameSpec.php
B. As I've tried your example, I noticed that without implements of Bowling class we get fatal error due to roll method usage in scenario
Why not to add a default template for bowling class like this one :
<?php
class BowlingGame
{
public function __call($method, $args)
{
}
}
?>
Results gave (as expected or almost (see phpunit/phpunit-story#3) because none implements)
PHPUnit 3.5.15 by Sebastian Bergmann.
BowlingGameSpec
[ ] Score for gutter game is 0
[ ] Score for all ones is 20
[ ] Score for one spare and 3 is 16
[ ] Score for one strike and 3 and 4 is 24
[ ] Score for perfect game is 300
Regards
Laurent Laville
See sebastianbergmann/phpunit#577 and the comment sebastianbergmann/phpunit#577 (comment)
The docs should note how ->at()
works exactly.
That it matches on a object level and not on a method level is not clear at the moment.
See http://stackoverflow.com/questions/3367513/phpunit-mocked-method-does-not-exist-when-using-mock-expectsthis-at , sebastianbergmann/phpunit#674 and other closed issues on phpunit & mock-objects.
Japanese pdf manual corrupted. (http://www.phpunit.de/manual/3.6/ja/phpunit-book.pdf)
In this pdf file, all japanese characters have been shown as #.
Moved over from sebastianbergmann/phpunit#262 - If you fix that can you leave a note in the Readme how you did it? That would be nice
As mentioned in sebastianbergmann/phpunit#133, some core options for the XML configuration file are missing from the docs:
Add:
Add:
Delete:
Does the --filter parameter limit names of functions? Or the names of test classes? The explanation of the --filter parameter is unclear on http://phpunit.de/manual/3.7/en/textui.html Does the function name need to include "test" or can that part of the name be omitted?
An example of a regex for a filter would be helpful: do I need to include delimiters? Does the pattern need to be quoted?
Also example on http://phpunit.de/manual/3.7/en/organizing-tests.html does not clarify... there seems to be no relationship between the broad example test run:
phpunit Tests/FreezerTest
And the more "fine-grain" controlled example:
phpunit --filter testFreezingAnObjectWorks Tests
Are the same test classes even involved here?
Consider using the same class in both examples (assuming this is correct syntax):
phpunit --filter testSingleFunction Tests/FreezerTest
The "Automating Tests" chapter does not really constitute "documentation material".
From looking over the docs I didn't find a nice list explaining what --strict
mode implies.
Writing a small section shouldn't be an issue though.
Once there is a 3.8 branch document the following changes:
The manual tells us [1] how to test PHP errors, but does not state how to test the code after the errors - i.e. if the code to test contains
trigger_error('foo', E_USER_NOTICE);
return false;
calls.
http://phpunit.de/manual/3.7/fr/behaviour-driven-development.html
La classe PHPUnit_Extensions_Story_TestCase ajouter un framework d'histoire (story) qui facilite la définition d'un Langage spécifique au domaine pour le développement dirigé par le comportement. Il peut être installé comme ceci
ajouter -> ajoute (no r on the end)
Be sure to include the correlation between @preserveGlobalState
and process isolation.
The "Test-Driven Development" chapter does not really constitute "documentation material".
From sebastianbergmann/phpunit#741:
Following the documentation at http://www.phpunit.de/manual/3.7/en/test-doubles.html, it states that PHPUnit will ignore mocking static methods, as well as private methods. It seems that this is no longer the case (as of 3.5), and Sebastian has written examples of how to mock statics and privates that would be perfect for the documentation: http://sebastian-bergmann.de/archives/883-Stubbing-and-Mocking-Static-Methods.html
The documentation should begin with a "Getting Started" chapter that covers the following:
array()
and count()
)Please document @expectedExceptionMessage and provide an example in the following URL:
/**
* @expectedException InvalidArgumentException
*/
public function testException()
{
}
When typing in my browser
http://phpunit.de/manual/current/en/
I get redirected to
http://www.phpunit.de/manual/manual/current/en/
This is wrong, the "manual" should not be doubled.
Extends the @Covers section my sample usages of this shortcut in the 3.7 docs.
I keep forgetting to do it hence the issue
The "PHPUnit's Goals" chapter does not really constitute "documentation material".
http://phpunit.de/manual/current/en/writing-tests-for-phpunit.html
Would be nice if it was mentioned how to run the test a bit earlier in the documentation. Being a typical developer, I was trying to open the file from a browser before I realised I had to run it from the command line :)
eg: From the terminal run phpunit filename.php
Cheers, Russ
The PHPUnit call "setMethods()" can be called with "null" as an argument if you don't want to mock any methods on an object. This is useful if the only purpose you're mocking an object is so you can avoid calling its constructor, and you need to call a real method on that object to test it. setMethods(null) isn't covered in the PHPUnit documentation, however.
I recommend that two lines on "http://www.phpunit.de/manual/3.6/en/test-doubles.html" be modified:
It is there in the 3.6 manual:
http://www.phpunit.de/manual/3.6/en/appendixes.configuration.html#appendixes.configuration.logging
and missing in 3.7:
http://www.phpunit.de/manual/3.7/en/appendixes.configuration.html#appendixes.configuration.logging
it appears in the French 3.7 version, however:
http://www.phpunit.de/manual/3.7/fr/appendixes.configuration.html#appendixes.configuration.logging
It would be nice id this could be made a bit more consistent. Also, after reading both versions, I'm not entirely sure it this setting only applies to the text log. It sounds a bit like it, but it would be good if this could be explicitly stated (I'm asking because I woudl like to have this behaviour in the XML loggers, if that's at all possible)
If you look at all command line examples in the PDF version of the PHPUnit Documentation you would be confused to see that the actual phpunit command is missing from the example (Furthermore, each example is printed twice.)
For a beginner learning from the PDF version, they will not notice that the command is missing and could read the whole documentation before they notice the error.
Compare PDF version of "Example 4.3. Exploiting the dependencies between tests" (at Pg 8 http://www.phpunit.de/manual/3.6/en/phpunit-book.pdf ) with the same example "Example 4.3. Exploiting the dependencies between tests" on the web at http://www.phpunit.de/manual/3.6/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.examples.DependencyFailureTest.php
Note: the PDF example is missing the crucial first line:
phpunit --verbose DependencyFailureTest
PDF version of "Example 4.3. Exploiting the dependencies between tests" (at Pg 8 http://www.phpunit.de/manual/3.6/en/phpunit-book.pdf ):
PHPUnit 3.6.0 by Sebastian Bergmann. FS Time: 0 seconds, Memory: 4.00Mb There was 1 failure: 1) DependencyFailureTest::testOne Failed asserting that is true. /home/sb/DependencyFailureTest.php:6 There was 1 skipped test: 1) DependencyFailureTest::testTwo This test depends on "DependencyFailureTest::testOne" to pass. FAILURES! Tests: 1, Assertions: 1, Failures: 1, Skipped: 1.phpunit --verbose DependencyFailureTest PHPUnit 3.6.0 by Sebastian Bergmann. FS Time: 0 seconds, Memory: 4.00Mb There was 1 failure: 1) DependencyFailureTest::testOne Failed asserting that is true. /home/sb/DependencyFailureTest.php:6 There was 1 skipped test: 1) DependencyFailureTest::testTwo This test depends on "DependencyFailureTest::testOne" to pass. FAILURES! Tests: 1, Assertions: 1, Failures: 1, Skipped: 1.
Same example "Example 4.3. Exploiting the dependencies between tests" on the web:
phpunit --verbose DependencyFailureTest PHPUnit 3.6.0 by Sebastian Bergmann. FS Time: 0 seconds, Memory: 4.00Mb There was 1 failure: 1) DependencyFailureTest::testOne Failed asserting that is true. /home/sb/DependencyFailureTest.php:6 There was 1 skipped test: 1) DependencyFailureTest::testTwo This test depends on "DependencyFailureTest::testOne" to pass. FAILURES! Tests: 1, Assertions: 1, Failures: 1, Skipped: 1.
It would be quite helpful if the published documentation pages (e.g. on http://phpunit.de/manual/3.7/en/writing-tests-for-phpunit.html) included a link to this project on Github with a label saying something like "Did we miss something in our documentation? Click here to recommend changes."
The configuration documentation page[1] misses docs for
[1] http://www.phpunit.de/manual/current/en/appendixes.configuration.html
Page: http://www.phpunit.de/manual/3.6/en/test-doubles.html
Stubs, after Example 10.2 -code
By default, all methods of the given class are replaced with a test double that just returns NULL unless a return value is configured using will($this->returnValue(), for instance.
last should be:
... will($this->returnValue()), for instance.
Page 83 & 84, in listing under Tip: Use your own Abstract Database TestCase,
final public fucntion getConnection()
typo appearing twice ....
I have php 5.4.10 and after following the installation instructions, the latest version I get is 3.7.22. The Upgrading Instructions on the site now are about as useless as a one legged ass kicking competition
Hi!
I just made a translation of PHPUnit3.7 documentation, but I could not figure out how to send it to the community (I'm totally new to GitHub).
How can I contribute with this translation? It's still in .odt format.
Thank you!
As described in:
sebastianbergmann/phpunit#58 and the configuration options
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.