# 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)
- [Lobster compile test](development/compilers/lobster/test-can-run-hello-world.nix)
- [Spacy annotation test](development/python-modules/spacy/annotation-test/default.nix)
- [Libtorch test](development/libraries/science/math/libtorch/test/default.nix)
- [Multiple tests for nanopb](./by-name/na/nanopb/package.nix)

### Linking NixOS module tests to a package

Like [package tests][larger-package-tests] as shown above, [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests) can also be linked to a package, so that the tests can be easily run when changing the related package.

For example, assuming we're packaging `nginx`, we can link its module test via `passthru.tests`:

```nix
{ stdenv, lib, nixosTests }:

stdenv.mkDerivation {
  # ...

  passthru.tests = {
    nginx = nixosTests.nginx;
  };

  # ...
}
```

## Automatic package updates

Nixpkgs periodically tries to update all packages that have a `passthru.updateScript` attribute.

> [!Note]
> A common pattern is to use the [`nix-update-script`](../pkgs/by-name/ni/nix-update/nix-update-script.nix) attribute provided in Nixpkgs, which runs [`nix-update`](https://github.com/Mic92/nix-update):
>
> ```nix
> { stdenv, nix-update-script }:
> stdenv.mkDerivation {
>   # ...
>   passthru.updateScript = nix-update-script { };
> }
> ```
>
> For simple packages, this is often enough, and will ensure that the package is updated automatically by [`nixpkgs-update`](https://github.com/nix-community/nixpkgs-update) when a new version is released.
> The [update bot](https://nix-community.org/update-bot) runs periodically to attempt to automatically update packages, and will run `passthru.updateScript` if set.
> While not strictly necessary if the project is listed on [Repology](https://repology.org), using `nix-update-script` allows the package to update via many more sources (e.g. GitHub releases).

The `passthru.updateScript` attribute can contain one of the following:

- an executable file, either on the file system: