From 0a8c6502ff9c5b9620dc57ffbdaf038166cd5653 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Sun, 23 Jun 2024 19:03:30 +0800 Subject: [PATCH 1/3] doc: add documentation for tests --- README.md | 2 +- docs/development/index.md | 1 + docs/development/tests.md | 27 +++++++++++++++++++++++++++ includes/sample.jinja | 2 +- 4 files changed, 30 insertions(+), 2 deletions(-) create mode 100644 docs/development/tests.md diff --git a/README.md b/README.md index 835cc978..534d8021 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons - Manage dependencies and virtual environments with [pdm](https://pdm-project.org/). - Build with [setuptools](https://github.com/pypa/setuptools) and versioned with [setuptools-scm](https://github.com/pypa/setuptools_scm/). - Lint with [pre-commit](https://pre-commit.com), [mypy](http://www.mypy-lang.org/), [ruff](https://github.com/charliermarsh/ruff), [toml-sort](https://github.com/pappasam/toml-sort) and [commitlint](https://commitlint.js.org/). -- Test with [pytest](https://pytest.org/) and [coverage](https://coverage.readthedocs.io) for threshold and reports. +- Test with [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) for threshold and reports. - Documentation with [sphinx](https://www.sphinx-doc.org/), the [furo](https://pradyunsg.me/furo) theme and [MyST parser](https://myst-parser.readthedocs.io/) for markdown. - Develop Command Line Interfaces with [typer](https://typer.tiangolo.com/). - Manage configurations with [pydantic-settings](https://docs.pydantic.dev/latest/usage/pydantic_settings/). diff --git a/docs/development/index.md b/docs/development/index.md index 03fc20fb..24ff799a 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -7,4 +7,5 @@ git-workflow setup-dev-env cleanup-dev-env commit +tests ``` diff --git a/docs/development/tests.md b/docs/development/tests.md new file mode 100644 index 00000000..212a5251 --- /dev/null +++ b/docs/development/tests.md @@ -0,0 +1,27 @@ +# Tests + +With all those automation of the CI/CD, the dependency update and the release process, tests play an even more important role in daily development. We leverage [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) with proper configuration to ensure everything works as expected. This page shows the general information and convention wish you to follow. + +## Run tests + +After [setting up development environment](./setup-dev-env.md), tests can be run with the command: + +```bash +make test +``` + +With the default configuration, it shows the result for each test cases, the execution time for the slow test cases and the report about the test coverage. + +## Write tests + +For the guideline on how to write tests, you may refer to [the official documentation](https://docs.pytest.org/how-to/assert.html). Here are some convention expected to be followed: + +1. Organize all the tests cases under the `tests` directory. +1. Keep the test modules align with the modules to be tested. + + For example, tests for `ss_python.cli` module should be located in the file `tests/cli_test.py`. If there are too many test cases, we can split them in the files `tests/cli/_test.py`. +1. Unless necessary, it is not recommended to lower the threshold of the test coverage. + +## Coverage Report + +After running the tests, coverage report will not only be printed on the screen but also be generated as part of the documentation, you can view it [here](../reports/coverage/index.md). diff --git a/includes/sample.jinja b/includes/sample.jinja index ebdc7b4d..b75c623c 100644 --- a/includes/sample.jinja +++ b/includes/sample.jinja @@ -16,7 +16,7 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons - Manage dependencies and virtual environments with [pdm](https://pdm-project.org/). - Build with [setuptools](https://github.com/pypa/setuptools) and versioned with [setuptools-scm](https://github.com/pypa/setuptools_scm/). - Lint with [pre-commit](https://pre-commit.com), [mypy](http://www.mypy-lang.org/), [ruff](https://github.com/charliermarsh/ruff), [toml-sort](https://github.com/pappasam/toml-sort) and [commitlint](https://commitlint.js.org/). -- Test with [pytest](https://pytest.org/) and [coverage](https://coverage.readthedocs.io) for threshold and reports. +- Test with [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) for threshold and reports. - Documentation with [sphinx](https://www.sphinx-doc.org/), the [furo](https://pradyunsg.me/furo) theme and [MyST parser](https://myst-parser.readthedocs.io/) for markdown. - Develop Command Line Interfaces with [typer](https://typer.tiangolo.com/). - Manage configurations with [pydantic-settings](https://docs.pydantic.dev/latest/usage/pydantic_settings/). From 212cf12d0c6ba99bf4e9e8a30d507464654c78f3 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Sun, 23 Jun 2024 19:08:39 +0800 Subject: [PATCH 2/3] refined by GPT --- docs/development/tests.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/development/tests.md b/docs/development/tests.md index 212a5251..3f98ff91 100644 --- a/docs/development/tests.md +++ b/docs/development/tests.md @@ -1,27 +1,27 @@ # Tests -With all those automation of the CI/CD, the dependency update and the release process, tests play an even more important role in daily development. We leverage [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) with proper configuration to ensure everything works as expected. This page shows the general information and convention wish you to follow. +In the context of CI/CD automation, dependency updates, and the release process, tests play a crucial role in daily development. We utilize [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) with proper configuration to ensure everything works as expected. This page provides general information and conventions we wish you to follow. -## Run tests +## Running Tests -After [setting up development environment](./setup-dev-env.md), tests can be run with the command: +After [setting up the development environment](/development/setup-dev-env.md), tests can be run with the command: ```bash make test ``` -With the default configuration, it shows the result for each test cases, the execution time for the slow test cases and the report about the test coverage. +With the default configuration, this command displays the result for each test case, the execution time for slow test cases, and a report on test coverage. -## Write tests +## Writing Tests -For the guideline on how to write tests, you may refer to [the official documentation](https://docs.pytest.org/how-to/assert.html). Here are some convention expected to be followed: +For guidelines on how to write tests, refer to [the official documentation](https://docs.pytest.org/how-to/assert.html). Here are some conventions we expect you to follow: -1. Organize all the tests cases under the `tests` directory. -1. Keep the test modules align with the modules to be tested. +1. Organize all test cases under the `tests` directory. +2. Align test modules with the modules to be tested. - For example, tests for `ss_python.cli` module should be located in the file `tests/cli_test.py`. If there are too many test cases, we can split them in the files `tests/cli/_test.py`. -1. Unless necessary, it is not recommended to lower the threshold of the test coverage. + For example, tests for the `ss_python.cli` module should be located in the file `tests/cli_test.py`. If there are too many test cases, they can be split into files within the `tests/cli/` directory, using a prefix for each test file. +3. Unless necessary, do not lower the threshold of the test coverage. ## Coverage Report -After running the tests, coverage report will not only be printed on the screen but also be generated as part of the documentation, you can view it [here](../reports/coverage/index.md). +After running the tests, the coverage report will be printed on the screen and generated as part of the documentation. You can view it [here](/reports/coverage/index.md). From 5f3ae55addc13d29d324dcddfd0d735996d85fc4 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Sun, 23 Jun 2024 19:11:16 +0800 Subject: [PATCH 3/3] update template --- template/docs/development/index.md | 1 + template/docs/development/tests.md.jinja | 27 ++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 template/docs/development/tests.md.jinja diff --git a/template/docs/development/index.md b/template/docs/development/index.md index 03fc20fb..24ff799a 100644 --- a/template/docs/development/index.md +++ b/template/docs/development/index.md @@ -7,4 +7,5 @@ git-workflow setup-dev-env cleanup-dev-env commit +tests ``` diff --git a/template/docs/development/tests.md.jinja b/template/docs/development/tests.md.jinja new file mode 100644 index 00000000..ea2063fc --- /dev/null +++ b/template/docs/development/tests.md.jinja @@ -0,0 +1,27 @@ +# Tests + +In the context of CI/CD automation, dependency updates, and the release process, tests play a crucial role in daily development. We utilize [pytest](https://docs.pytest.org/) and [coverage](https://coverage.readthedocs.io) with proper configuration to ensure everything works as expected. This page provides general information and conventions we wish you to follow. + +## Running Tests + +After [setting up the development environment](/development/setup-dev-env.md), tests can be run with the command: + +```bash +make test +``` + +With the default configuration, this command displays the result for each test case, the execution time for slow test cases, and a report on test coverage. + +## Writing Tests + +For guidelines on how to write tests, refer to [the official documentation](https://docs.pytest.org/how-to/assert.html). Here are some conventions we expect you to follow: + +1. Organize all test cases under the `tests` directory. +2. Align test modules with the modules to be tested. + + For example, tests for the `{{ module_name}}.cli` module should be located in the file `tests/cli_test.py`. If there are too many test cases, they can be split into files within the `tests/cli/` directory, using a prefix for each test file. +3. Unless necessary, do not lower the threshold of the test coverage. + +## Coverage Report + +After running the tests, the coverage report will be printed on the screen and generated as part of the documentation. You can view it [here](/reports/coverage/index.md).