From 44bdf73774d515b5d236c98c8f7710ad7f9182d1 Mon Sep 17 00:00:00 2001 From: Pedro Bressan Date: Mon, 25 Nov 2024 19:51:29 +0100 Subject: [PATCH] DOC: Clarify testing structure on testing docs. --- docs/development/build_docs.rst | 6 ++-- docs/development/testing.rst | 50 +++++++++++++++++++++++++++++++-- 2 files changed, 50 insertions(+), 6 deletions(-) diff --git a/docs/development/build_docs.rst b/docs/development/build_docs.rst index 77d916137..144b59d12 100644 --- a/docs/development/build_docs.rst +++ b/docs/development/build_docs.rst @@ -44,7 +44,7 @@ This command will install the requirements and generate the documentation in the .. note:: This requires the ``make`` command to be available in your system. Check out - GNU Make documentation on how to install it in your system. + GNU Make documentation on how to install it. To see the documentation, open the ``docs/_build/html/index.html`` file in your browser. @@ -60,10 +60,10 @@ Sometimes you may face problems when building the documentation after several times of building it. This may happen because sphinx does not clean the ``docs/_build`` folder before building the documentation again. -One can use the internal Makefile inside the ``docs``folder generated by sphinx +One can use the internal Makefile inside the ``docs`` folder generated by sphinx to have specific commands to build and clean the documentation. -To clean the ``docs/_build`` folder, run the following command in your terminal: +To clean the ``docs/_build`` folder, run the following commands in your terminal: .. code-block:: bash diff --git a/docs/development/testing.rst b/docs/development/testing.rst index 032287ee3..853db9d81 100644 --- a/docs/development/testing.rst +++ b/docs/development/testing.rst @@ -68,6 +68,49 @@ Do not get caught by the size of that docstring. The only requirements it has to that the docstring contains precise information on the expected behaviour and/or behaviour to be tested. +Testing Structure +----------------- + +In order to keep the tests easily readable and maintainable, RocketPy encourages +the use of the AAA pattern (Arrange, Act, Assert) for structuring the tests. + +* **Arrange:** Set up the necessary preconditions and inputs (often done by *Fixtures* as it will be described below); +* **Act:** Execute the code under test; +* **Assert:** Verify that the code under test behaves as expected. + +The following example illustrates the AAA pattern: + +.. code-block:: python + + @pytest.mark.parametrize( + "latitude, longitude", [(-21.960641, -47.482122), (0, 0), (21.960641, 47.482122)] + ) # Arrange: Done by the fixtures and the parameters of the test + def test_location_set_location_saves_location(latitude, longitude, example_plain_env): + """Tests location is saved correctly in the environment obj. + + Parameters + ---------- + example_plain_env : rocketpy.Environment + latitude: float + The latitude in decimal degrees. + longitude: float + The longitude in decimal degrees. + """ + # Act: Set the location + example_plain_env.set_location(latitude, longitude) + # Assert: Check if the location was saved correctly + assert example_plain_env.latitude == latitude + assert example_plain_env.longitude == longitude + +This pattern is a general guideline, of course specific tests cases might +modify it to better fit the specific needs of the test. + +.. note:: + + Parameterization is a powerful feature of ``pytest.mark.parametrize`` that allows + you to run the same test with different inputs. This is highly recommended when + there multiple testing scenarios for the same method. + Directory Structure ------------------- @@ -234,7 +277,7 @@ This test contains two fundamental traits which defines it as an integration tes The motivation behind lies in the fact that it interacts and calls too many methods, being too broad to be considered an unit test. -Please be aware that Integration tests are not solely classfied when interacting with external dependencies, +Please be aware that Integration tests are not solely classified when interacting with external dependencies, but also encompass verifying the interaction between classes or too many methods at once, such as ``all_info()``. Further clarification: Even if the test contains traits of unit tests and use dependencies which are stable, such as @@ -305,5 +348,6 @@ documenting purposes, such as below: [[-10. 10.]] """ -This is not common practice, but it is optional and can be done. RocketPy however encourages -the use of other means to test its software, as described. +This is not common practice, but it is optional and can be done, specially to provide +an usage example for the function under testing. RocketPy however encourages the use +of other means to test its software, as described.