diff options
author | Luke Granger-Brown <git@lukegb.com> | 2021-05-01 22:31:02 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-05-01 22:31:02 +0100 |
commit | 147c7015836f5d6a4d635ec429ba6b6a512c87b5 (patch) | |
tree | f850b7c5c5b7f123ac497fa39ccc39ee2891876e /doc/contributing | |
parent | 4397711c75f675f9f41cd18256362240c7ba2774 (diff) | |
parent | c357fbeb5176c233aa0b36426800ab632eddf217 (diff) | |
download | nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar.gz nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar.bz2 nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar.lz nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar.xz nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.tar.zst nixpkgs-147c7015836f5d6a4d635ec429ba6b6a512c87b5.zip |
Merge pull request #120534 from davidak/package-tests
doc: add instructions for creating package tests
Diffstat (limited to 'doc/contributing')
-rw-r--r-- | doc/contributing/coding-conventions.chapter.md | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index a95b600a420..e12db53ee33 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -513,3 +513,73 @@ If you do need to do create this sort of patch file, one way to do so is with gi ```ShellSession $ git diff > nixpkgs/pkgs/the/package/0001-changes.patch ``` + +## Package tests {#sec-package-tests} + +Tests are important to ensure quality and make reviews and automatic updates easy. + +Nix package tests are a lightweight alternative to [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests). They can be used to create simple integration tests for packages while the module tests are used to test services or programs with a graphical user interface on a NixOS VM. Unittests that are included in the source code of a package should be executed in the `checkPhase`. + +### Writing package tests {#ssec-package-tests-writing} + +This is an example using the `phoronix-test-suite` package with the current best practices. + +Add the tests in `passthru.tests` to the package definition like this: + +```nix +{ stdenv, lib, fetchurl, callPackage }: + +stdenv.mkDerivation { + … + + passthru.tests = { + simple-execution = callPackage ./tests.nix { }; + }; + + meta = { … }; +} +``` + +Create `tests.nix` in the package directory: + +```nix +{ runCommand, phoronix-test-suite }: + +let + inherit (phoronix-test-suite) pname version; +in + +runCommand "${pname}-tests" { meta.timeout = 3; } + '' + # automatic initial setup to prevent interactive questions + ${phoronix-test-suite}/bin/phoronix-test-suite enterprise-setup >/dev/null + # get version of installed program and compare with package version + if [[ `${phoronix-test-suite}/bin/phoronix-test-suite version` != *"${version}"* ]]; then + echo "Error: program version does not match package version" + exit 1 + fi + # run dummy command + ${phoronix-test-suite}/bin/phoronix-test-suite dummy_module.dummy-command >/dev/null + # needed for Nix to register the command as successful + touch $out + '' +``` + +### Running package tests {#ssec-package-tests-running} + +You can run these tests with: + +```ShellSession +$ cd path/to/nixpkgs +$ nix-build -A phoronix-test-suite.tests +``` + +### Examples of package tests {#ssec-package-tests-examples} + +Here are examples of package tests: + +- [Jasmin compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/jasmin/test-assemble-hello-world/default.nix) +- [Lobster compile test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/compilers/lobster/test-can-run-hello-world.nix) +- [Spacy annotation test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/spacy/annotation-test/default.nix) +- [Libtorch test](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/science/math/libtorch/test/default.nix) +- [Multiple tests for nanopb](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/nanopb/default.nix) |