- See `lib/tests/NAME.nix` for instructions on running specific library tests

Tests are important to ensure quality and make reviews and automatic updates easy.

The following types of tests exists:

* [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs.
  They exercise both NixOS modules and the packaged programs used within them.
  For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content.
* Nix **package tests** are a lightweight alternative to NixOS module tests.
  They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them.
* The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.

Here in the nixpkgs manual we describe mostly _package tests_; for _module tests_ head over to the corresponding [section in the NixOS manual](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).

### Writing inline package tests

For very simple tests, they can be written inline:

```nix
# ... ,
{ yq-go }:

buildGoModule rec {
  # …

  passthru.tests = {
    simple = runCommand "${pname}-test" { } ''
      echo "test: 1" | ${yq-go}/bin/yq eval -j > $out
      [ "$(cat $out | tr -d $'\n ')" = '{"test":1}' ]
    '';
  };
}
```

Any derivation can be specified as a test, even if it's in a different file.
Such a derivation that implements a test can depend on the package under test, even in the presence of `overrideAttrs`.

In the following example, `(my-package.overrideAttrs f).passthru.tests` will work as expected, as long as the definition of `tests` does not rely on the original `my-package` or overrides all occurrences of `my-package`:

```nix
# my-package/default.nix
{ stdenv, callPackage }:
stdenv.mkDerivation (finalAttrs: {
  # ...
  passthru.tests.example = callPackage ./example.nix { my-package = finalAttrs.finalPackage; };
})
```

```nix
# my-package/example.nix
{
  runCommand,
  lib,
  my-package,
  ...
}:
runCommand "my-package-test"
  {
    nativeBuildInputs = [ my-package ];
    src = lib.sources.sourcesByRegex ./. [
      ".*.in"
      ".*.expected"
    ];
  }
  ''
    my-package --help
    my-package <example.in >example.actual
    diff -U3 --color=auto example.expected example.actual
    mkdir $out
  ''
```

### Writing larger package tests

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 = 60; } ''
  # 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

You can run these tests with:

```ShellSession
$ cd path/to/nixpkgs
$ nix-build -A phoronix-test-suite.tests
```

### Examples of package tests

Here are examples of package tests:

- [Jasmin compile test](by-name/ja/jasmin/test-assemble-hello-world/default.nix)