diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76691031e4..d61ff68c88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,8 @@ from the architecture of the project to how you should test any code changes. ### How to Guides * [How to run the code formatting tools](./dev-docs/howtoguides/code_formatting.md) -* [How to run the tests](./dev-docs/howtoguides/testing.md) +* [How to run unit tests](./dev-docs/howtoguides/unit_testing.md) +* [How to run integration tests](./dev-docs/howtoguides/integration_testing.md) * [How to release a new version](./dev-docs/howtoguides/release_a_new_version.md) * [How to release a hotfix](./dev-docs/howtoguides/release_a_hotfix.md) * [How to use the contract staging environment](./dev-docs/howtoguides/use_staging_environment.md) diff --git a/dev-docs/howtoguides/testing.md b/dev-docs/howtoguides/integration_testing.md similarity index 84% rename from dev-docs/howtoguides/testing.md rename to dev-docs/howtoguides/integration_testing.md index 8c3879170c..0fecc953cf 100644 --- a/dev-docs/howtoguides/testing.md +++ b/dev-docs/howtoguides/integration_testing.md @@ -1,33 +1,6 @@ -# Testing -All unit and lint tests are run using `tox`, with different versions of Python with specific constraints. We also use `tox-setuptools-version` to specify the correct setuptools version based on what is present in each release, and `tox-pyenv` to recognize the different local [pyenv interpreters](https://github.com/pyenv/pyenv). +# Integration Testing -First, run the script to install and configure `pyenv`, and the `tox` dependencies: - -```shell -./tools/setup_pyenv.sh -``` - -After that you need to [set up your shell environment](https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv), according to the pyenv documentation. -The guide has quick snippets to configure `bash`, `zsh` and `fish` shells. - -Refresh your terminal to make sure pyenv is working. Then you can run the unit and lint tests: - -```shell -tox -``` - -> **Note** -> There are a number of `autouse` mocks in our unit tests. These are intended to prevent accidental side effects on the host system from running the unit tests, as well as prevent leaks of the system environment into the unit tests. -> One such `autouse` mock tells the unit tests that they are run as root (unless the mock is overriden for a particular test). -> These `autouse` mocks have helped, but may not be preventing all side effects or environment leakage. - -The client also includes built-in dep8 tests. These are run as follows: - -```shell -autopkgtest -U --shell-fail . -- lxd ubuntu:xenial -``` - -## Integration Tests +Before proceeding with the unit tests, please ensure you have completed the setup instructions in the [Getting Started Tutorial](../tutorials/getting-started.md). This guide covers essential setup information required to run the integration tests. Ubuntu Pro Client uses [behave](https://behave.readthedocs.io) for its integration testing. @@ -57,7 +30,7 @@ The testing can be overridden to install ubuntu-advantage-tools from other sourc > **Note** > Note that we cache the source when running with `UACLIENT_BEHAVE_INSTALL_FROM=local` based on a hash, calculated from the repository state. If you change the python code locally and run the behave tests against your new version, there will be new debs in the cache source with the new repo state hash. -To run the integration tests, use the `tox` command as shown below. +To run the integration tests, use the `tox` command as shown below. Please note that, as shown here without arguments, this command would execute all the integration tests sequentially and would take an inordinate amount of time to complete. Always pass arguments to this command to specify a subset of tests to run, as demonstrated next. ```shell diff --git a/dev-docs/howtoguides/unit_testing.md b/dev-docs/howtoguides/unit_testing.md new file mode 100644 index 0000000000..446fc9406d --- /dev/null +++ b/dev-docs/howtoguides/unit_testing.md @@ -0,0 +1,43 @@ +# Unit Testing + +Before proceeding with the unit tests, please ensure you have completed the setup instructions in the [Getting Started Tutorial](../tutorials/getting-started.md). This guide covers essential setup information required to run the tests. + +All unit and lint tests are run using `tox`, with different versions of Python with specific constraints. We also use `tox-setuptools-version` to specify the correct setuptools version based on what is present in each release, and `tox-pyenv` to recognize the different local [pyenv interpreters](https://github.com/pyenv/pyenv). + +First, run the script to install and configure `pyenv`, and the `tox` dependencies: + +```shell +./tools/setup_pyenv.sh +``` + +After that you need to [set up your shell environment](https://github.com/pyenv/pyenv#set-up-your-shell-environment-for-pyenv), according to the pyenv documentation. +The guide has quick snippets to configure `bash`, `zsh` and `fish` shells. + +Refresh your terminal to make sure pyenv is working. Then you can run the unit and lint tests: + +```shell +tox +``` + +If you want to just run unit tests, you can specify the test environment: + +```shell +tox -e test +``` + +Or if you want to run a specific test file, you can do so by specifying the test file: + +```shell +tox -e test -- uaclient/tests/test_actions.py +``` + +> **Note** +> There are a number of `autouse` mocks in our unit tests. These are intended to prevent accidental side effects on the host system from running the unit tests, as well as prevent leaks of the system environment into the unit tests. +> One such `autouse` mock tells the unit tests that they are run as root (unless the mock is overriden for a particular test). +> These `autouse` mocks have helped, but may not be preventing all side effects or environment leakage. + +The client also includes built-in dep8 tests. These are run as follows: + +```shell +autopkgtest -U --shell-fail . -- lxd ubuntu:xenial +```