diff --git a/docs/index.rst b/docs/index.rst index 6d04003c..068655ed 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,8 +31,9 @@ We think it's really neat, and we hope you do to! practices/code_coverage practices/git-lfs practices/linting + practices/namespace_project practices/pipx practices/precommit practices/pypi + practices/unit_testing practices/sphinx - practices/namespace_project diff --git a/docs/practices/unit_testing.rst b/docs/practices/unit_testing.rst new file mode 100644 index 00000000..cc95c759 --- /dev/null +++ b/docs/practices/unit_testing.rst @@ -0,0 +1,35 @@ +Unit testing +=============================================================================== + +What is it? Why do it? +------------------------------------------------------------------------------- + +Unit testing is a method for testing very specific aspects of a code base. The +various different types of tests cover a wide range of use cases, for a quick intro +take a look at RealPython's article about unit testing: https://realpython.com/python-testing/#unit-tests-vs-integration-tests + +How to manage +------------------------------------------------------------------------------- + +Our template makes use of `pytest `_ +as the unit testing framework. You have the option to change that at any time, +but you'll need to make modifications in a few files: + +* ``pyproject.toml`` +* ``.github/workflows/testing-and-coverage.yml`` +* ``.github/workflows/smoke-test.yml`` +* ``.pre-commit-config.yaml`` + +Additionally, we advise that unit tests be placed in the ``./tests`` directory. +This is not a requirement, but the Continuous Integration and pre-commit checks +will only look in that directory for tests. If you decide to keep your tests +elsewhere, you should update the ``[tool.pytest.ini_options]`` section in +``pyproject.toml`` with the new location so that CI and pre-commit will work as +expected. + +It's also worth noting that if you want to write exploratory tests as you develop +your code, but you *do not* want those tests to be included in automated test runs, +feel free to place those tests in a directory outside of the ``./tests`` directory. + +Note that ``pytest`` will recursively search subdirectories inside of ``./tests`` +while searching for tests to run. diff --git a/python-project-template/pyproject.toml.jinja b/python-project-template/pyproject.toml.jinja index a4df3814..509f4c07 100644 --- a/python-project-template/pyproject.toml.jinja +++ b/python-project-template/pyproject.toml.jinja @@ -60,6 +60,11 @@ build-backend = "setuptools.build_meta" [tool.setuptools_scm] write_to = "src/{{package_name}}/_version.py" + +[tool.pytest.ini_options] +testpaths = [ + "tests", +] {%- if preferred_linter == 'black' %} [tool.black]