diff --git a/docs/contributing/tests.md b/docs/contributing/tests.md index ab381d8c..61d92359 100644 --- a/docs/contributing/tests.md +++ b/docs/contributing/tests.md @@ -1 +1,22 @@ -# Image Tests \ No newline at end of file +# Image Tests + +We greatly appreciate pull requests that extend the automated tests that vet the basic functionality of the Docker images. + +## How the Tests Work + +Travis executes `make build-test-all` against every pull request submitted to the `jupyter/docker-stacks` repository. The `make` command builds every docker image. After building each image, the `make` command executes `pytest` to run both image-specific tests like those in [base-notebook/test/](https://github.com/jupyter/docker-stacks/tree/master/base-notebook/test) and common tests defined in [test/](https://github.com/jupyter/docker-stacks/tree/master/test). Both kinds of tests make use of global [pytest fixtures](https://docs.pytest.org/en/latest/fixture.html) defined in the [conftest.py](https://github.com/jupyter/docker-stacks/blob/master/conftest.py) file at the root of the projects. + +## Contributing New Tests + +Please follow the process below to add new tests: + +1. If the test should run against every image built, add your test code to one of the modules in [test/](https://github.com/jupyter/docker-stacks/tree/master/test) or create a new module. +2. If your test should run against a single image, add your test code to one of the modules in `some-notebook/test/` or create a new module. +3. Build one or more images you intend to test and run the tests locally. If you use `make`, call: +``` +make image/somestack-notebook +make test/somestack-notebook +``` +4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. +5. Watch for Travis to report a build success or failure for your PR on GitHub. +6. Discuss changes with the maintainers and address any issues running the tests on Travis. \ No newline at end of file