diff --git a/docs/contributing/tests.rst b/docs/contributing/tests.rst index f4e554e..7532463 100644 --- a/docs/contributing/tests.rst +++ b/docs/contributing/tests.rst @@ -8,17 +8,17 @@ Unit and integration tests are a core part of TLJH, as important as the code & documentation. They help validate that the code works as we think it does, and continues to do so when changes occur. They also help communicate in precise terms what we expect our code -to do. +to do. Integration tests ================= -TLJH is a *distribution* where the primary value is the many +TLJH is a *distribution* where the primary value is the many opinionated choices we have made on components to use and how they fit together. Integration tests are perfect for testing that the various components fit together and work as they should. So we write a lot of integration tests, and put in more effort -towards them than unit tests. +towards them than unit tests. All integration tests are run on `CircleCI `_ for each PR and merge, making sure we don't have broken tests @@ -33,18 +33,16 @@ Running integration tests locally --------------------------------- You need ``docker`` installed and callable by the user running -the integration tests without needing sudo. +the integration tests without needing sudo. You can then run the tests with: .. code-block:: bash - .circleci/integration-test run-test + .circleci/integration-test.py run-test - -```` is an identifier for the tests - you can choose -anything you want. ``>`` is list of test files -(under ``integration-tests``) that should be run in one go. +- ```` is an identifier for the tests - you can choose anything you want +- ``>`` is list of test files (under ``integration-tests``) that should be run in one go. For example, to run all the basic tests, you would write: @@ -56,4 +54,12 @@ For example, to run all the basic tests, you would write: test_extensions.py This will run the tests in the three files against the same installation -of TLJH and report errors. \ No newline at end of file +of TLJH and report errors. + +If you would like to run the tests with a custom pip spec for the bootstrap script, you can use the ``--bootstrap_pip_spec`` +parameter: + +.. code-block:: bash + + .circleci/integration-test.py run-test \ + --bootstrap_pip_spec="git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name"