How to use the command 'pest' (with examples)

Pest is a PHP testing framework that aims to provide simplicity in testing. It allows developers to initialize a testing configuration, run tests in the current directory, run tests annotated with specific groups, generate coverage reports, and set a minimum coverage threshold.

Use case 1: Initialize a standard Pest configuration in the current directory

Code:

pest --init

Motivation: Initializing a Pest configuration in the current directory is the first step to start using the Pest testing framework. This command creates a pest.php file that includes the necessary configuration and sets up the testing environment.

Explanation:

• --init: This option initializes a standard Pest testing configuration in the current directory.

Example output:

Pest configuration generated successfully in pest.php file.

Use case 2: Run tests in the current directory

Code:

pest

Motivation: Running tests is crucial in ensuring the quality and correctness of the code. Using the pest command without any arguments will execute all the tests in the current directory.

Explanation:

• No additional arguments: Running pest without any additional arguments will execute all the tests in the current directory.

Example output:

..FFF

Failures:

  1) Tests\Unit\ExampleTest
     ExampleTest::test_example
     Failed asserting that false is true.

  2) Tests\Feature\ExampleFeatureTest
     ExampleFeatureTest::test_example
     Failed asserting that false is true.
     
  3) Tests\Integration\ExampleIntegrationTest
     ExampleIntegrationTest::test_example
     Failed asserting that false is true.
     
  ...

Time: X seconds, Memory: Y MB

FAILURES!
Tests: XX, Assertions: XX, Failures: XX.

Use case 3: Run tests annotated with the given group

Code:

pest --group name

Motivation: In complex applications, tests might be organized into different groups based on functionality or priority. Running specific groups of tests helps in focusing on particular areas and saves time during the testing process.

Explanation:

• --group name: This option allows running tests annotated with the specified group name. Replace name with the actual group name.

Example output:

...SSS

Skipped:

  1) Tests\Unit\ExampleTest
     Skipped: Test skipped due to group: name.

  2) Tests\Feature\ExampleFeatureTest
     Skipped: Test skipped due to group: name.
     
  3) Tests\Integration\ExampleIntegrationTest
     Skipped: Test skipped due to group: name.
     
  ...

Time: X seconds, Memory: Y MB

OK, but incomplete, skipped, or risky tests!
Tests: XX, Assertions: XX, Skipped: XX.

Use case 4: Run tests and print the coverage report to stdout

Code:

pest --coverage

Motivation: Code coverage reports provide valuable insights into the effectiveness of tests, highlighting untested areas of the code. By printing the coverage report to stdout, developers can quickly assess the coverage without the need to access an additional file.

Explanation:

• --coverage: This option generates a coverage report and prints it to stdout.

Example output:

...X.

1 / 5 tests failed.

Coverage report:
-----------------------+---------+----------+--------+
File                   | % Stmts | % Branch | % Funcs |
-----------------------+---------+----------+--------+
app/Example.php        |   50    |   100    |   0    |
tests/ExampleTest.php  |  100    |    50    |   100  |
-----------------------+---------+----------+--------+
All files              |   66.6  |    75    |    50  |
-----------------------+---------+----------+--------+

Use case 5: Run tests with coverage and fail if the coverage is less than the minimum percentage

Code:

pest --coverage --min=80

Motivation: Setting a minimum coverage threshold ensures that the codebase has a certain level of test coverage, reducing the chances of undetected bugs. Failing the tests if coverage falls below the threshold forces developers to write more tests and improve coverage.

Explanation:

• --coverage: This option generates a coverage report.
• --min=80: This option sets the minimum coverage percentage threshold to 80%.

Example output:

.....X

1 / 6 tests failed.

Coverage report:
-----------------------+---------+----------+--------+
File                   | % Stmts | % Branch | % Funcs |
-----------------------+---------+----------+--------+
app/Example.php        |   50    |   100    |   0    |
tests/ExampleTest.php  |  100    |   100    |   100  |
-----------------------+---------+----------+--------+
All files              |   66.6  |    75    |    50  |
-----------------------+---------+----------+--------+

Code coverage (66.6%) is below the minimum threshold of 80%.

Conclusion:

The pest command provides a simple and straightforward way to write and execute tests in PHP using the Pest testing framework. It covers various use cases, such as initializing a testing configuration, running all tests or specific groups, generating coverage reports, and setting coverage thresholds. By following these examples and understanding the available options, developers can effectively utilize the Pest testing framework to ensure the stability and quality of their PHP applications.