[This duplicates this ticket https://github.com/sebastianbergmann/phpunit-documentation/issues/488 which has been closed since the documentation was moved to separate projects per language]

In phpunit-mock-objects/src/Builder/InvocationMocker.php there's a willReturnOnConsecutiveCalls method, which isn't mentioned in the PHPUnit documentation.
https://github.com/sebastianbergmann/phpunit-mock-objects/blob/master/src/Builder/InvocationMocker.php#L173

Can we get that added please?

Import content from https://github.com/epdenouden/phpunit/wiki/PHPUnit-test-running-order-management into documentation.

• Figure out a strategy (branching and tagging) for maintaining multiple versions of the documentation (ReadTheDocs does not render branches other than master and requires tags for alternative versions)
• Document how to contribute to an existing language edition of the documentation
• Document how to build the documentation on a local machine
• Document how to start a new language edition of the documentation

(Re-created for sebastianbergmann/phpunit-documentation#492)

This was added in: sebastianbergmann/phpunit#2496

[This relates to this ticket https://github.com/sebastianbergmann/phpunit-documentation/issues/314 which has been closed since the documentation was moved to separate projects per language]

https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.ticket

This annotation doesn't have any documentation for what it is, how to use it etc.

The docs about mocking the filesystem seem to be incomplete as I miss the stepps needed to use vfsStreamWrapper.

Moved here from sebastianbergmann/phpunit-mock-objects#260.

According to this issue sebastianbergmann/phpunit#1936 the feature mapTestClassNameToCoveredClassName has been removed, however it's still present in the documentation in the XML Configuration File but without an explanation: https://phpunit.readthedocs.io/en/7.3/configuration.html#phpunit.
So is it working or is the documentation outdated?

See sebastianbergmann/phpunit#3224 and sebastianbergmann/phpunit#2085

• "Risky Tests" > "Test Execution Timeout": here is a "Note" panel that should also mention the new option for default timeout
• "Annotations" > "@Small": here is a "Note" panel that may be removed (because it is also not there for "@Medium" and "@large"), or replaced like above
• "The XML Configuration File"

Oh and in "The XML Configuration File" the existing option "enforceTimeLimit" is also not documented (this is only mentioned in "Risky Tests"

The "Edit on GitHub" links do not work on Read the Docs for es, fr, pt, ja and zh languages

ex:
https://phpunit.readthedocs.io/ja/latest/

https://github.com/sebastianbergmann/phpunit-documentation-japanese//master/src/index.rst

e.g: https://phpunit.de/manual/current/en/test-doubles.html

Hi @sebastianbergmann

I translated this documentation into Russian, the repository is available at this link.

I understand, now I have to transfer you this repository? Do I still have access to it?

And another question that is interesting to me - why not create an organization on GitHub for official repositories that are related to PHPUnit, why this was not done before? For example, here https://github.com/phpspec

http://phpunit.readthedocs.io/en/7.1/annotations.html#testwith
more info on data format would help, I needed to check the sources to find out that it's treated as json

it may be simplest to change provided example to test count of associative array instead of string length

Repost of sebastianbergmann/phpunit-documentation#494.

I noticed that the introductory documentation chapter uses assertEquals(). I suggest that it can be replaced with assertSame(), which is stricter a may prevent unexpected type conversion bugs.

What do you think?

If you think it is a good idea, I can prepare a PR.

Document that using @depends to depend on all tests of a test case class to pass is not possible.

Hello,

It seems that the attributes failOnRisky and failOnWarning are missing from the XML documentation, I found these on the phpunit.xsd file in the main repository.

Note that --fail-on-risky and --fail-on-warning seems to be missing too in the command line options, even though it's in the --help command

$ phpunit --help
PHPUnit 5.5.4 by Sebastian Bergmann and contributors.

Usage: phpunit [options] UnitTest [UnitTest.php]
       phpunit [options] <directory>

Code Coverage Options:

  --coverage-clover <file>  Generate code coverage report in Clover XML format.
  --coverage-crap4j <file>  Generate code coverage report in Crap4J XML format.
  --coverage-html <dir>     Generate code coverage report in HTML format.
  --coverage-php <file>     Export PHP_CodeCoverage object to file.
  --coverage-text=<file>    Generate code coverage report in text format.
                            Default: Standard output.
  --coverage-xml <dir>      Generate code coverage report in PHPUnit XML format.
  --whitelist <dir>         Whitelist <dir> for code coverage analysis.
  --disable-coverage-ignore Disable annotations for ignoring code coverage.

Logging Options:

  --log-junit <file>        Log test execution in JUnit XML format to file.
  --log-tap <file>          Log test execution in TAP format to file.
  --log-teamcity <file>     Log test execution in TeamCity format to file.
  --log-json <file>         Log test execution in JSON format.
  --testdox-html <file>     Write agile documentation in HTML format to file.
  --testdox-text <file>     Write agile documentation in Text format to file.
  --testdox-xml <file>      Write agile documentation in XML format to file.
  --reverse-list            Print defects in reverse order

Test Selection Options:

  --filter <pattern>        Filter which tests to run.
  --testsuite <pattern>     Filter which testsuite to run.
  --group ...               Only runs tests from the specified group(s).
  --exclude-group ...       Exclude tests from the specified group(s).
  --list-groups             List available test groups.
  --list-suites             List available test suites.
  --test-suffix ...         Only search for test in files with specified
                            suffix(es). Default: Test.php,.phpt

Test Execution Options:

  --report-useless-tests    Be strict about tests that do not test anything.
  --strict-coverage         Be strict about @covers annotation usage.
  --strict-global-state     Be strict about changes to global state
  --disallow-test-output    Be strict about output during tests.
  --disallow-resource-usage Be strict about resource usage during small tests.
  --enforce-time-limit      Enforce time limit based on test size.
  --disallow-todo-tests     Disallow @todo-annotated tests.

  --process-isolation       Run each test in a separate PHP process.
  --no-globals-backup       Do not backup and restore $GLOBALS for each test.
  --static-backup           Backup and restore static attributes for each test.

  --colors=<flag>           Use colors in output ("never", "auto" or "always").
  --columns <n>             Number of columns to use for progress output.
  --columns max             Use maximum number of columns for progress output.
  --stderr                  Write to STDERR instead of STDOUT.
  --stop-on-error           Stop execution upon first error.
  --stop-on-failure         Stop execution upon first error or failure.
  --stop-on-warning         Stop execution upon first warning.
  --stop-on-risky           Stop execution upon first risky test.
  --stop-on-skipped         Stop execution upon first skipped test.
  --stop-on-incomplete      Stop execution upon first incomplete test.
  --fail-on-warning         Treat tests with warnings as failures.
  --fail-on-risky           Treat risky tests as failures.
  -v|--verbose              Output more verbose information.
  --debug                   Display debugging information during test execution.

  --loader <loader>         TestSuiteLoader implementation to use.
  --repeat <times>          Runs the test(s) repeatedly.
  --tap                     Report test execution progress in TAP format.
  --teamcity                Report test execution progress in TeamCity format.
  --testdox                 Report test execution progress in TestDox format.
  --testdox-group           Only include tests from the specified group(s).
  --testdox-exclude-group   Exclude tests from the specified group(s).
  --printer <printer>       TestListener implementation to use.

Configuration Options:

  --bootstrap <file>        A "bootstrap" PHP file that is run before the tests.
  -c|--configuration <file> Read configuration from XML file.
  --no-configuration        Ignore default configuration file (phpunit.xml).
  --no-coverage             Ignore code coverage configuration.
  --include-path <path(s)>  Prepend PHP's include_path with given path(s).
  -d key[=value]            Sets a php.ini value.
  --generate-configuration  Generate configuration file with suggested settings.

Miscellaneous Options:

  -h|--help                 Prints this usage information.
  --version                 Prints the version and exits.
  --atleast-version <min>   Checks that version is greater than min and exits.

Cheers :}

I suggest removing the substring "it is evaluated for" from the following table, because it complicates the general sentence.

Is it not better, compare:

Currently some lines of this table do not contain this substring (Constraint that accepts any input value.)

@sebastianbergmann what do you think about this?

If a test does this:

    public function testException()
    {
        $this->expectException(\Exception::class);
        
        throw new \Exception;

        throw new \Exception;

    }

then a developer might expect that expectException() will handle the first thrown exception, and fail the second one.

That is not however the case: both exceptions (and presumably an unlimited number) are handled.

The documentation should mention this.

• On https://phpunit.readthedocs.io/en/7.2/installation.html it reads "You are not using the most up to date version of the library. 7.3 is the newest version." but PHPUnit 7.4 is the newest version
• On https://phpunit.readthedocs.io/en/7.3/installation.html the |version| placeholder is not replaced

PHPUnit should not be installed globally. Remove any instructions we have in the documentation that explain how to do this.

rm -rf build/ && make html
…
/Users/klee/src/php/phpunit-documentation-english/src/assertions.rst:1168: WARNING: Could not lex literal_block as "bash". Highlighting skipped.

I'll take care of this.

How about to slightly simplify the code examples, and remove the closing PHP tags, and maybe even opening PHP tags?

<?php
use PHPUnit\Framework\TestCase;

class ContainsTest extends TestCase
{
    public function testFailure()
    {
        $this->assertContains('baz', 'foobar');
    }
}
?>

The example above will look like this:

use PHPUnit\Framework\TestCase;

class ContainsTest extends TestCase
{
    public function testFailure()
    {
        $this->assertContains('baz', 'foobar');
    }
}

Or even remove the closing tags, because it is customary to omit them. What do you think, @sebastianbergmann?

(Re-created for sebastianbergmann/phpunit-documentation#424)

(This is of course just a minor issue...)

See https://phpunit.de/manual/current/en/textui.html#textui.clioptions

At the top it correctly mentions the new option:

Test Execution Options:
--dont-report-useless-tests Do not report tests that do not test anything.

But further down it then explains the old option:

--report-useless-tests
Be strict about tests that do not test anything. See Chapter 6 for details.

Ad comment from @farwish (from 4 April 2017):

The manual may be older, we should see command line.

=> This issue is really only about the minor inconsistency issue in the documentation; the CLI shows:

--dont-report-useless-tests Do not report tests that do not test anything.

Is there a standard for updating the documentation for dealing with deprecated features?

For example, with the release of PHPUnit 8, annotations for expecting exceptions have been deprecated. Should the documentation about these simply be removed, or marked as deprecated then removed in the documentation for PHPUnit 9 (when they will actually be removed)?

Hi, I would like to hear opinions about this block in the documentation.

The PHPUnit documentation is a reference for the PHP community, so, I think that could be worth it to re-think it:

A common question, especially from developers new to PHPUnit, is whether using $this->assertTrue() or self::assertTrue(), for instance, is “the right way” to invoke an assertion. The short answer is: there is no right way. And there is no wrong way, either. It is a matter of personal preference.

If you try to do the same with properties, you will get a PHP Notice like:

Notice: Accessing static property Foo::$bar as non static in /xxx on line N

Proof here: https://3v4l.org/BtqfT

Based on that error, I won't be surprised if PHP also deprecates dynamic access to static methods.

what do you think?

Hello.
In the documentation about test doubles we can read:

Limitation: final, private, and static methods

Please note that final, private, protected, and static methods cannot be stubbed or mocked.

In the body of this limitation block protected method is mentioned though it is not correct because it is possible to create a stub for protected method

sebastianbergmann/phpunit#3100 (comment)

I just upgraded to PHPUnit 8, but the latest version of documentation on https://phpunit.readthedocs.io/ is for PHPUnit 7.4. Any ideas when this might be updated, or if the documentation for version 8 is available anywhere else?

[This duplicates this ticket https://github.com/sebastianbergmann/phpunit-documentation/issues/345 which has been closed since the documentation was moved to separate projects per language]

There's no mention of the getObjectForTrait method in the documentation.

There was a blog article mentioning this method from 2011 https://sebastian-bergmann.de/archives/906-Testing-Traits.html but that seems to have vanished.

The undocumented code is in phpunit/src/Framework/TestCase.php

I'm following the docs at https://phpunit.readthedocs.io/en/8.0/writing-tests-for-phpunit.html, trying to write my first phpunit tests. I installed phpunit with composer and created a broken test, to validate. However the test won't run. Here's what I did: what am I missing?

$project-dir> composer --dev require phpunit
$project-dir> mkdir tests
$project-dir/tests> // create test file TestTheTest.php

<?php
use PHPUnit\Framework\TestCase;
class TestTheTest extends TestCase
{
    public function testFailure()
    {
        $this->assertEmpty([]);
    }
}
?>

$project-dir/tests>phpunit TestTheTest.php
PHP Fatal error: Class 'PHPUnit\Framework\TestCase' not found in project-dir\tests\TestTheTest.php on line 3
Fatal error: Class 'PHPUnit\Framework\TestCase' not found in project-dir\tests\TestTheTest.php on line 3

This issue probably is related to #41 (i.e., it probably blocks it).

Steps to reproduce:

1. go to https://phpunit.readthedocs.io/en/8.0/ (which is the English version of the docs)
2. at the bottom of the left sidebar, select any of the following branches: 7.1., 7.2., 7.3., 7.4, 7.5, 8.0
3. click on the "Edit on GitHub" link at the top of the page

Expected results:
The corresponding file on GitHub, and a URL like this:
https://github.com/sebastianbergmann/phpunit-documentation-english/blob/7.0/src/index.rst

Actual results:
A page that has the text "Not found" on it, and a URL like this:
https://github.com/sebastianbergmann/phpunit-documentation-english//7.1/src/index.rst

Apart from the different version number, the most striking difference seems to be that the broken URLs are missing the "blob" segment. Adding that segment to the broken URL makes it work fine.

With version 7.0, the Edit link is fine. Starting with 7.1, the problem occurs.

In https://phpunit.de/manual/5.4/en/textui.html#textui.clioptions it states that the --configuration option takes a "file" as an argument, but it does not mention anywhere that a directory may also be used.

[Note: this was migrated from sebastianbergmann/phpunit-documentation#352 - it appears that the latest documentation at https://phpunit.readthedocs.io/en/latest/textui.html still has the issue.]

The French version has syntax highlighting, e.g. http://phpunit.readthedocs.io/fr/latest/database.html#executer-les-tests-verifier-les-resultats-et-nettoyer

From https://twitter.com/dbu/status/1056974784251207685:

for the symfony doc, i did a regular expression search with " (simply|simple|just|easy|easily|quick|of course|logically|clearly|obviously|merely|basically|trivial)". "simply" and "of course" are mostly superflous and particularly annoying. the rest is very dependening on context.

The documentation for the @requires annotation makes no mention of comparison operators.

Comparison operator support was added in PHPUnit 5.2. See sebastianbergmann/phpunit#1984.

The code emits a warning when assertContains is used with strings: Using assertContains() with string haystacks is deprecated and will not be supported in PHPUnit 9. Refactor your test to use assertStringContainsString() or assertStringContainsStringIgnoringCase() instead. but assertStringContainsString() and its siblings are not documented.

See the current docs link:

http://phpunit.readthedocs.io/en/7.1/extending-phpunit.html#extending-phpunit-examples-basetestlistener-php

Note: This is a copy of sebastianbergmann/phpunit-documentation#236

After adding a setUp() method to my database testing class, the database initialization process wasn't happening properly anymore.This seems to be the same problem that was asked and answered here:
http://stackoverflow.com/questions/9490397/dbunit-in-phpunit-is-not-truncating-the-tables

So I added parent::setUp(); as the first line of my setUp() method, and it's working again.
It would be helpful if the phpunit documentation would make it clear that it is important to call parent::setUp() when overriding the setUp() method, in at least some conditions.

It should probably be mentioned in chapter 4 "Fixtures" where it talks about the setUp() method. Perhaps something like: "If you do override setUp(), don't forget to begin with a call to parent::setUp() if this or that condition applies. Otherwise, this or that thing won't happen anymore, with these undesireable results."

And it should probably also be mentioned somewhere in chapter 8 "Database Testing". Perhaps something like: "If you override setUp() as described in chapter 4, be sure to call parent::setUp(), for this and that reason. Otherwise, this or that other thing won't happen, with these undesireable results.

Of course, if one should always start setUp() with a call to parent::setUp(), a short note to that effect in the appropriate place(s) could save those who don't know or remember to do this some time and frustration.

In logging.rst there is an example for junit log format showing pass, failure and error.
Could this please be extended to also show skip and ignore?

BTW, do we not want to inclde examples for the teamcity format (--log-teamcity)?

Updated from sebastianbergmann/phpunit-documentation#348

While working on #3 I noticed that in the documentation there are many references to PHPUnit_ classes which were already renamed.

They can be found by searching for PHPUnit_ string in the IDE.

Hi

Is it planned to have new docs not only for newest version, but also for older ones ?
Like, even when having phpunit 6, there are a lot of ppl still using v4

See: Example 3.2 and Example 3.3 at https://phpunit.readthedocs.io/en/latest/textui.html

In 7.0 and 7.1 there is no description for the annotation @ticket.

cc @sebastianbergmann

When was the last time the documentation on https://phpunit.readthedocs.io was updated?

New changes, which are currently in the repository, there are no in that online documentation.

cc @sebastianbergmann

Ported issue by @llernestal from archived phpunit-documentation repo:
sebastianbergmann/phpunit-documentation#395

The documentation says:

Please note that final, private and static methods cannot be stubbed or mocked. They are ignored by PHPUnit's test double functionality and retain their original behavior.

But static methods DO NOT retain their original behavior. The method body is replaced with:

throw new PHPUnit_Framework_MockObject_BadMethodCallException('Static method "{method_name}" cannot be invoked on mock object');

Maybe the documentation should say something about that?

Code reference

        if ($static) {
            $templateFile = 'mocked_static_method.tpl';
        } else {

https://github.com/sebastianbergmann/phpunit-mock-objects/blob/master/src/Generator.php#L995-L997

    {modifier} function {reference}{method_name}({arguments_decl}){return_delim}{return_type}
    {
        throw new \PHPUnit\Framework\MockObject\BadMethodCallException('Static method "{method_name}" cannot be invoked on mock object');
    }

https://github.com/sebastianbergmann/phpunit-mock-objects/blob/master/src/Generator/mocked_static_method.tpl.dist

[This duplicates this ticket https://github.com/sebastianbergmann/phpunit-documentation/issues/488 which has been closed since the documentation was moved to separate projects per language]

In phpunit-mock-objects/src/Builder/InvocationMocker.php there's a willReturnOnConsecutiveCalls method, which isn't mentioned in the PHPUnit documentation. Can we get that added please?

[This duplicates this ticket https://github.com/sebastianbergmann/phpunit-documentation/issues/477 which has been closed since the documentation was moved to separate projects per language]

By chance discovered this issue:
sebastianbergmann/phpunit#1222

Which requested a @usesDefaultClass annotation similar to the @coversDefaultClass annotation.

It would be useful if this was documented. Can we get an update to the annotations.rst to include it please?

My pull request #104 is probably also relevant for older versions:

Unfortunately, I am unable to judge which versions are affected because it actually references the php-code-coverage project.

Furthermore, also the other languages might be affected since the respective version.