Testing guidelines

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 <https://github.com/doctrine/dbal/tree/2.11.3/tests/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.