@@ -134,7 +134,28 @@ Attribute Set `lib.platforms` defines [various common lists](https://github.com/
134134This attribute is special in that it is not actually under the `meta` attribute set but rather under the `passthru` attribute set. This is due to how `meta` attributes work, and the fact that they are supposed to contain only metadata, not derivations.
135135:::
136136
137−An attribute set with as values tests. A test is a derivation, which builds successfully when the test passes, and fails to build otherwise. A derivation that is a test needs to have `meta.timeout` defined.
137+An attribute set with tests as values. A test is a derivation that builds when the test passes and fails to build otherwise.
138+
139+You can run these tests with:
140+
141+```ShellSession
142+$ cd path/to/nixpkgs
143+$ nix-build -A your-package.tests
144+```
145+
146+#### Package tests
147+
148+Tests that are part of the source package are often executed in the `installCheckPhase`.
149+
150+Prefer `passthru.tests` for tests that are introduced in nixpkgs because:
151+
152+* `passthru.tests` tests the 'real' package, independently from the environment in which it was built
153+* we can run `passthru.tests` independently
154+* `installCheckPhase` adds overhead to each build
155+
156+For more on how to write and run package tests, see <xref linkend="sec-package-tests"/>.
157+
158+#### NixOS tests
138159
139160The NixOS tests are available as `nixosTests` in parameters of derivations. For instance, the OpenSMTPD derivation includes lines similar to:
140161
@@ -148,6 +169,8 @@ The NixOS tests are available as `nixosTests` in parameters of derivations. For
148169}
149170```
150171
172+NixOS tests run in a VM, so they are slower than regular package tests. For more information see [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
173+
151174### `timeout` {#var-meta-timeout}
152175
153176A timeout (in seconds) for building the derivation. If the derivation takes longer than this time to build, it can fail due to breaking the timeout. However, all computers do not have the same computing power, hence some builders may decide to apply a multiplicative factor to this value. When filling this value in, try to keep it approximately consistent with other values already present in `nixpkgs`.