Testing guidelines

docs/en/reference/testing.rst

@@ -0,0 +1,45 @@
+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
+------------
+
+Each pull request that adds new or changes the existing logic must have tests.
+
+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).
+
+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.