From ec6ac7f9cbde54116254a916f7fdc8d250ba6aa6 Mon Sep 17 00:00:00 2001 From: Nuno Maduro Date: Tue, 12 Jan 2021 13:57:52 +0100 Subject: [PATCH 1/3] Adds parallel testing documention --- testing.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 71 insertions(+), 7 deletions(-) diff --git a/testing.md b/testing.md index 0b5650a50f5..8b760743585 100644 --- a/testing.md +++ b/testing.md @@ -2,8 +2,9 @@ - [Introduction](#introduction) - [Environment](#environment) -- [Creating & Running Tests](#creating-and-running-tests) - - [Artisan Test Runner](#artisan-test-runner) +- [Creating Tests](#creating-tests) +- [Running Tests](#running-tests) + - [Running Tests In Parallel](#running-tests-in-parallel) ## Introduction @@ -17,14 +18,14 @@ An `ExampleTest.php` file is provided in both the `Feature` and `Unit` test dire ## Environment -When running tests via `vendor/bin/phpunit`, Laravel will automatically set the configuration environment to `testing` because of the environment variables defined in the `phpunit.xml` file. Laravel also automatically configures the session and cache to the `array` driver while testing, meaning no session or cache data will be persisted while testing. +When running tests, Laravel will automatically set the configuration environment to `testing` because of the environment variables defined in the `phpunit.xml` file. Laravel also automatically configures the session and cache to the `array` driver while testing, meaning no session or cache data will be persisted while testing. You are free to define other testing environment configuration values as necessary. The `testing` environment variables may be configured in the `phpunit.xml` file, but make sure to clear your configuration cache using the `config:clear` Artisan command before running your tests! In addition, you may create a `.env.testing` file in the root of your project. This file will override the `.env` file when running PHPUnit tests or executing Artisan commands with the `--env=testing` option. - -## Creating & Running Tests + +## Creating Tests To create a new test case, use the `make:test` Artisan command: @@ -59,8 +60,12 @@ Once the test has been generated, you may define test methods as you normally wo > {note} If you define your own `setUp` / `tearDown` methods within a test class, be sure to call the respective `parent::setUp()` / `parent::tearDown()` methods on the parent class. - -### Artisan Test Runner + +## Running Tests + +As mentioned previously, once you've written tests, you may run them using `phpunit`: + + ./vendor/bin/phpunit In addition to the `phpunit` command, you may use the `test` Artisan command to run your tests. The Artisan test runner provides verbose test reports in order to ease development and debugging: @@ -69,3 +74,62 @@ In addition to the `phpunit` command, you may use the `test` Artisan command to Any arguments that can be passed to the `phpunit` command may also be passed to the Artisan `test` command: php artisan test --testsuite=Feature --stop-on-failure + + + +### Running Tests In Parallel + +The `test` Artisan command also provides the `--parallel` option that you may use to speed up your tests by running tests in parallel: + + php artisan test --parallel + +By default, the number of processes equal to the number of available cores on the machine. You may adjust the number of processes by using the `--processes` option: + + php artisan test --parallel --processes=4 + +When using database traits in your tests, Laravel automatically handles creating and migrating a test database for each process. The test databases will be suffixed with the process token, which is unique per process. For example, if you have 2 processes, Laravel will create and use the `your_db_test_1` and `your_db_test_2` test databases. + +By default, the test databases persist between `test` runs, but you may re-create them using the `--refresh-databases` option: + + php artisan test --parallel --refresh-databases + +While Laravel works out of the box with parallel testing, you may need to prepare certain resources in your application so they can be used in parallel. + +Using the `ParallelTesting` facade you may specify code to be executed on the `setUp` and `tearDown` of a process or a test case. The given closures receive the `$token` and `$testCase` variables that contain the process token and the current test case, respectively. + + Date: Tue, 12 Jan 2021 14:06:00 +0100 Subject: [PATCH 2/3] Wording --- testing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/testing.md b/testing.md index 8b760743585..1c43973c47c 100644 --- a/testing.md +++ b/testing.md @@ -83,7 +83,7 @@ The `test` Artisan command also provides the `--parallel` option that you may us php artisan test --parallel -By default, the number of processes equal to the number of available cores on the machine. You may adjust the number of processes by using the `--processes` option: +By default, the number of processes is equal to the number of available cores on the machine. You may adjust the number of processes by using the `--processes` option: php artisan test --parallel --processes=4 @@ -122,6 +122,7 @@ Using the `ParallelTesting` facade you may specify code to be executed on the `s }); ParallelTesting::tearDownTestCase(function ($token, $testCase) { + // .. }); ParallelTesting::tearDownProcess(function ($token) { From 74dee87d3616e4e1ad1ecd4fd0cb8e512d599347 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Tue, 12 Jan 2021 16:18:23 -0600 Subject: [PATCH 3/3] formatting and additions to parallel testing docs --- testing.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/testing.md b/testing.md index 1c43973c47c..45a9f3b51a3 100644 --- a/testing.md +++ b/testing.md @@ -79,23 +79,29 @@ Any arguments that can be passed to the `phpunit` command may also be passed to ### Running Tests In Parallel -The `test` Artisan command also provides the `--parallel` option that you may use to speed up your tests by running tests in parallel: +By default, Laravel and PHPUnit execute your tests sequentially within a single process. However, you may greatly reduce the amount of time it takes to run your tests by running tests simultaneously across multiple processes. To get started, include the `--parallel` option when executing the `test` Artisan command: php artisan test --parallel -By default, the number of processes is equal to the number of available cores on the machine. You may adjust the number of processes by using the `--processes` option: +By default, Laravel will create as many processes as there are available CPU cores on your machine. However, you may adjust the number of processes using the `--processes` option: php artisan test --parallel --processes=4 -When using database traits in your tests, Laravel automatically handles creating and migrating a test database for each process. The test databases will be suffixed with the process token, which is unique per process. For example, if you have 2 processes, Laravel will create and use the `your_db_test_1` and `your_db_test_2` test databases. + +#### Parallel Testing & Databases -By default, the test databases persist between `test` runs, but you may re-create them using the `--refresh-databases` option: +Laravel automatically handles creating and migrating a test database for each parallel process that is running your tests. The test databases will be suffixed with a process token which is unique per process. For example, if you have two parallel test processes, Laravel will create and use `your_db_test_1` and `your_db_test_2` test databases. - php artisan test --parallel --refresh-databases +By default, test databases persist between calls to the `test` Artisan command so that they can be used again by subsequent `test` invocations. However, you may re-create them using the `--recreate-databases` option: -While Laravel works out of the box with parallel testing, you may need to prepare certain resources in your application so they can be used in parallel. + php artisan test --parallel --recreate-databases -Using the `ParallelTesting` facade you may specify code to be executed on the `setUp` and `tearDown` of a process or a test case. The given closures receive the `$token` and `$testCase` variables that contain the process token and the current test case, respectively. + +#### Parallel Testing Hooks + +Occasionally, you may need to prepare certain resources used by your application's tests so they may be safely used by multiple test processes. + +Using the `ParallelTesting` facade, you may specify code to be executed on the `setUp` and `tearDown` of a process or test case. The given closures receive the `$token` and `$testCase` variables that contain the process token and the current test case, respectively: