diff --git a/docs/en/reference/testing.rst b/docs/en/reference/testing.rst new file mode 100644 index 00000000000..a02976983e9 --- /dev/null +++ b/docs/en/reference/testing.rst @@ -0,0 +1,72 @@ +Testing Guidelines +=================== + +Some intro. + +Purpose +------- + +1. Help maintainers understand what problem the given code change is trying to solve. +2. Make sure that the problem being solved needs to be solved in the DBAL. +3. Prevent breakages of the logic by new code changes. + +Requirements +------------ + +1. Each pull request that adds new or changes the existing logic must have tests. +2. The test that covers certain logic must fail without the changes in the code it covers. + +Unit Tests +---------- + +Unit test are meant to cover the logic of a given unit (e.g. a class or a method) including the logic of its interaction +with other units. In this case, the other units could be mocked. + +Unit tests are mostly welcomed for testing the logic that the DBAL itself defines (e.g. logging). They also could be +used as a secondary tier of testing for the logic that requires integration testing. + +Integration Tests +----------------- + +Integration (a.k.a. functional) test are required when the behavior under the test is dictated by the logic +defined outside of the DBAL. It could be: + +1. The underlying database platform. +2. The underlying database driver. +3. SQL syntax and the standard as such. + +It is important to have integration tests for the cases above. Unlike unit tests, they make the external components +the source of truth and help make sure that the logic implemented in the DBAL is correct even if the external components +change (e.g. a new version of a database platform is supported). + +When Integration Testing Is Not Required +---------------------------------------- + +Some cases cannot be reproduced with the existing integration testing suite. It could be the scenarios that involve +multiple concurrent database connections, transactions, locking, performance-related issues, etc. + +In such cases, it is still important that a pull request fixing the issues is accompanied with a free-form test that +reproduces the issue being fixed. + +Testing Different Database Platforms +------------------------------------ + +Despite the fact that most of the issues are originally discovered on a specific database platform, +the integration tests for all issues by default should be implemented at the database abstraction level +and run against all the platforms that support the API being tested. + +This allows to ensure that the same scenario that was found failing on one platform also works on others. Or otherwise, +the same issue could be reproduced on the platforms where it wasn't originally tested. + +If the newly added test fails on other platforms, and fixing it is out of the scope, the test can be explicitly marked +as incomplete which will clearly identify the issue. + +Examples of such tests could be found under the the +`Doctrine\Tests\DBAL\Functional\Platform `_ +namespace. + +Other Notes +----------- + +Do not mix the unit and the integration approaches in one test. Each of the approaches has its own area of application +and purpose. Mixing them makes it harder to identify the reason and the impact of a failing mixed-type test.