From 7c75f1d52b3078608be29cbe0b009875829cc03f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?= Date: Tue, 10 May 2022 11:56:47 +0200 Subject: Expand the testing section of the hacking docs - Make it clear what the different kind of tests are, where they live and how they can be ran - Ask people to primarily write unit tests --- doc/manual/src/contributing/hacking.md | 41 ++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 12 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 90a8f1f94..7ce8d8de6 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -71,18 +71,6 @@ To install it in `$(pwd)/outputs` and test it: nix (Nix) 3.0 ``` -To run a functional test: - -```console -make tests/test-name-should-auto-complete.sh.test -``` - -To run the unit-tests for C++ code: - -``` -make check -``` - If you have a flakes-enabled Nix you can replace: ```console @@ -94,3 +82,32 @@ by: ```console $ nix develop ``` + +## Testing + +Nix comes with three different flavors of tests: unit, functional and integration. + +Most tests are currently written as functional tests. +**However**, it is preferable (as much as it makes sense) to primarily test new code with unit tests. + +### Unit-tests + +The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined +under `src/{library_name}/tests` using the +[googletest](https://google.github.io/googletest/) framework. + +You can run the whole testsuite with `make check`, or the tests for a specific component with `make libfoo-tests_RUN`. Finer-grained filtering is also possible using the [--gtest_filter](https://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) command-line option. + +### Functional tests + +The functional tests reside under the `tests` directory and are listed in `tests/local.mk`. +The whole testsuite can be run with `make install && make installcheck`. +Individual tests can be run with `make tests/{testName}.sh.test`. + +### Integration tests + +The integration tests are defined in the Nix flake under the `hydraJobs.tests` attribute. +These tests include everything that needs to interact with external services or run Nix in a non-trivial distributed setup. +Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on ). + +You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}` -- cgit v1.2.3 From 65a913d29be7305b2c743fb92c93f0e6bb12d610 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9ophane=20Hufschmitt?= Date: Thu, 12 May 2022 12:02:31 +0200 Subject: =?UTF-8?q?Don=E2=80=99t=20recommend=20writing=20unit=20tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As asked in --- doc/manual/src/contributing/hacking.md | 3 --- 1 file changed, 3 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 7ce8d8de6..59ce5cac7 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -87,9 +87,6 @@ $ nix develop Nix comes with three different flavors of tests: unit, functional and integration. -Most tests are currently written as functional tests. -**However**, it is preferable (as much as it makes sense) to primarily test new code with unit tests. - ### Unit-tests The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined -- cgit v1.2.3 From edfcc8256ee232736e335d6cc315f98f6f40d1f3 Mon Sep 17 00:00:00 2001 From: "Travis A. Everett" Date: Sat, 11 Jun 2022 13:30:51 -0500 Subject: doc: add install test info to hacking.md --- doc/manual/src/contributing/hacking.md | 64 +++++++++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 59ce5cac7..9a371afa7 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -83,7 +83,7 @@ by: $ nix develop ``` -## Testing +## Testing Nix Nix comes with three different flavors of tests: unit, functional and integration. @@ -108,3 +108,65 @@ These tests include everything that needs to interact with external services or Because these tests are expensive and require more than what the standard github-actions setup provides, they only run on the master branch (on ). You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}` + +## Testing the install scripts + +Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports). + +If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped "installer" and "installer_test" jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs. +- The `installer` job will generate installers for these platforms: x86_64-linux, armv6l-linux, armv7l-linux, x86_64-darwin. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. +- the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. + +### One-time setup +1. Have a GitHub account with a fork of the Nix repo. +2. At cachix.org: + - Create or log in to an account. + - Create a Cachix cache using the format `-nix-install-tests`. + - Navigate to the new cache > Settings > Auth Tokens. + - Generate a new cachix auth token and copy the generated value. +4. At github.com: + - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret. + - Name the secret `CACHIX_AUTH_TOKEN` + - Paste the copied value of the Cachix cache auth token. + +### Using the CI-generated installer for manual testing + +After the CI run completes, you can check the output to extract the installer url: +1. Click into the detailed view of the CI run. +2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them). +3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`) +4. Copy the install_url +5. To generate an install command, plug this install_url and your github username into this template: + + ```console + sh <(curl -L ) --tarball-url-prefix https://-nix-install-tests.cachix.org/serve + ``` + + -- cgit v1.2.3 From b5d85f0922e0f4a9585a281f6d938ec67cd07349 Mon Sep 17 00:00:00 2001 From: "Travis A. Everett" Date: Fri, 5 Aug 2022 13:49:18 -0500 Subject: Apply suggestions from code review Co-authored-by: Valentin Gagarin --- doc/manual/src/contributing/hacking.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 9a371afa7..86c6522f2 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -113,11 +113,12 @@ You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix- Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports). -If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped "installer" and "installer_test" jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs. -- The `installer` job will generate installers for these platforms: x86_64-linux, armv6l-linux, armv7l-linux, x86_64-darwin. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. +If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs. +- The `installer` job will generate installers for these platforms: `x86_64-linux`, `armv6l-linux`, `armv7l-linux`, `x86_64-darwin`. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. - the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. ### One-time setup + 1. Have a GitHub account with a fork of the Nix repo. 2. At cachix.org: - Create or log in to an account. -- cgit v1.2.3 From 9b7bd2dd1fc83f6df449fce3967a95cb098ca4b2 Mon Sep 17 00:00:00 2001 From: "Travis A. Everett" Date: Mon, 8 Aug 2022 10:04:27 -0500 Subject: Apply suggestions from code review Co-authored-by: Valentin Gagarin --- doc/manual/src/contributing/hacking.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 86c6522f2..d8a8c8591 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -114,7 +114,13 @@ You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix- Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports). If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs. -- The `installer` job will generate installers for these platforms: `x86_64-linux`, `armv6l-linux`, `armv7l-linux`, `x86_64-darwin`. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. +- The `installer` job will generate installers for these platforms: + - `x86_64-linux` + - `armv6l-linux` + - `armv7l-linux` + - `x86_64-darwin`. + + While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. - the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. ### One-time setup -- cgit v1.2.3 From 47fa1087c8864654f6cfae84e25ac6db318ed1d4 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 16 Sep 2022 09:36:20 +0200 Subject: Update doc/manual/src/contributing/hacking.md --- doc/manual/src/contributing/hacking.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index d8a8c8591..628744bf2 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -142,8 +142,8 @@ After the CI run completes, you can check the output to extract the installer ur 1. Click into the detailed view of the CI run. 2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them). 3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`) -4. Copy the install_url -5. To generate an install command, plug this install_url and your github username into this template: +4. Copy the value of `install_url` +5. To generate an install command, plug this `install_url` and your GitHub username into this template: ```console sh <(curl -L ) --tarball-url-prefix https://-nix-install-tests.cachix.org/serve -- cgit v1.2.3 From 0a4bd9fe88807cbae51b8b8b51c4897a76991d20 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 16 Sep 2022 09:36:30 +0200 Subject: Update doc/manual/src/contributing/hacking.md --- doc/manual/src/contributing/hacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 628744bf2..9e4e679e6 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -138,7 +138,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed ### Using the CI-generated installer for manual testing -After the CI run completes, you can check the output to extract the installer url: +After the CI run completes, you can check the output to extract the installer URL: 1. Click into the detailed view of the CI run. 2. Click into any `installer_test` run (the URL you're here to extract will be the same in all of them). 3. Click into the `Run cachix/install-nix-action@v...` step and click the detail triangle next to the first log line (it will also be `Run cachix/install-nix-action@v...`) -- cgit v1.2.3 From 1ae974120a24f70eba12e073dbba4b7bac73eedf Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 16 Sep 2022 09:36:37 +0200 Subject: Update doc/manual/src/contributing/hacking.md --- doc/manual/src/contributing/hacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 9e4e679e6..7f3905d38 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -121,7 +121,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed - `x86_64-darwin`. While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. -- the `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. +- The `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. ### One-time setup -- cgit v1.2.3 From dc8c0b173c2cc5bd0fe4273f741fda5591ba4133 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Fri, 16 Sep 2022 09:36:55 +0200 Subject: Update doc/manual/src/contributing/hacking.md --- doc/manual/src/contributing/hacking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 7f3905d38..f4aeda871 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -130,7 +130,7 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed - Create or log in to an account. - Create a Cachix cache using the format `-nix-install-tests`. - Navigate to the new cache > Settings > Auth Tokens. - - Generate a new cachix auth token and copy the generated value. + - Generate a new Cachix auth token and copy the generated value. 4. At github.com: - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret. - Name the secret `CACHIX_AUTH_TOKEN` -- cgit v1.2.3 From 4bd52bf6c4c88e2f8a9b703d75c3db5ad062353c Mon Sep 17 00:00:00 2001 From: "Travis A. Everett" Date: Sat, 17 Sep 2022 13:20:11 -0500 Subject: Apply suggestions from code review Co-authored-by: Valentin Gagarin --- doc/manual/src/contributing/hacking.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index f4aeda871..5fad34763 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -85,8 +85,6 @@ $ nix develop ## Testing Nix -Nix comes with three different flavors of tests: unit, functional and integration. - ### Unit-tests The unit-tests for each Nix library (`libexpr`, `libstore`, etc..) are defined -- cgit v1.2.3 From 84bdb0e3ade70be722087b95beb7f460e0d3da8d Mon Sep 17 00:00:00 2001 From: "Travis A. Everett" Date: Sun, 18 Sep 2022 12:58:28 -0500 Subject: address review feedback Mainly: - Try to triangulate between narrative that framed this as a new/easy process and the need for a reference that will not quickly grow stale. - Fix a ~continuity issue where the text was talking about "your Cachix cache" before saying that you'd need to make a Cachix cache to enable the installer tests. - Adopt suggestion on titling, and nest subtitles in the installer test section. --- doc/manual/src/contributing/hacking.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'doc/manual/src/contributing') diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 5fad34763..f67660ab2 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -83,7 +83,7 @@ by: $ nix develop ``` -## Testing Nix +## Running tests ### Unit-tests @@ -107,21 +107,21 @@ Because these tests are expensive and require more than what the standard github You can run them manually with `nix build .#hydraJobs.tests.{testName}` or `nix-build -A hydraJobs.tests.{testName}` -## Testing the install scripts +### Installer tests -Testing the install scripts has traditionally been tedious, but you can now do this much more easily via the GitHub Actions CI runs (at least for platforms that Github Actions supports). +With just a little one-time setup, the Nix repository's GitHub Actions continuous integration (CI) workflow can easily test the installer each time you push to a branch. -If you've already pushed to a fork of Nix on GitHub before, you may have noticed that the CI workflows in your fork list skipped `installer` and `installer_test` jobs. Once your Nix fork is set up correctly, pushing to it will also run these jobs. -- The `installer` job will generate installers for these platforms: +Creating a Cachix cache for your installer tests and adding its authorization token to GitHub enables [two installer-specific jobs in the CI workflow](https://github.com/NixOS/nix/blob/88a45d6149c0e304f6eb2efcc2d7a4d0d569f8af/.github/workflows/ci.yml#L50-L91): + +- The `installer` job generates installers for the platforms below and uploads them to your Cachix cache: - `x86_64-linux` - `armv6l-linux` - `armv7l-linux` - - `x86_64-darwin`. - - While this installer is in your Cachix cache, you can use it for manual testing on any of these platforms. -- The `installer_test` job will try to use this installer and run a trivial Nix command on `ubuntu-latest` and `macos-latest`. + - `x86_64-darwin` + +- The `installer_test` job (which runs on `ubuntu-latest` and `macos-latest`) will try to install Nix with the cached installer and run a trivial Nix command. -### One-time setup +#### One-time setup 1. Have a GitHub account with a fork of the Nix repo. 2. At cachix.org: @@ -129,12 +129,12 @@ If you've already pushed to a fork of Nix on GitHub before, you may have noticed - Create a Cachix cache using the format `-nix-install-tests`. - Navigate to the new cache > Settings > Auth Tokens. - Generate a new Cachix auth token and copy the generated value. -4. At github.com: +3. At github.com: - Navigate to your Nix fork > Settings > Secrets > Actions > New repository secret. - - Name the secret `CACHIX_AUTH_TOKEN` + - Name the secret `CACHIX_AUTH_TOKEN`. - Paste the copied value of the Cachix cache auth token. -### Using the CI-generated installer for manual testing +#### Using the CI-generated installer for manual testing After the CI run completes, you can check the output to extract the installer URL: 1. Click into the detailed view of the CI run. @@ -147,7 +147,7 @@ After the CI run completes, you can check the output to extract the installer UR sh <(curl -L ) --tarball-url-prefix https://-nix-install-tests.cachix.org/serve ``` -