# How to write a test

Test are simple derivations, put into the `by-name` directory.  As you
often want to test configuration, the 'standard' nixos-vm-test function
starts a vm with the specified configuration and lets you run a python
test script.

But, I've noticed, that most of my tests in this nixos-configuration are
actually testing the home-manager config of a program. As such I've built
a test infrastructure on top of the pre-existing nixos-vm-tests. It is
further described in the `mkTest` section.

## `mkTest`

A standard application test would look somewhat like this:

```nix
{mkTest}:
mkTest {
  name = "my-tests";

  # The configuration to add.
  # In this case, the less config is being tested.
  configuration = {
    imports = [
      ../../../../modules/by-name/le/less/module.nix
    ];
    config.soispha.programs.less.enable = true;
  };

  # Files that are provided at the test directory.
  # In this case, the test dir would have a `./data/test.file`
  # path pre-populated with the
  # contents of the file at the lhs.
  testData = {
    "data/test.file" = ./data/test.file;
  };

  # The description of what to do in the test.
  description = ./test.desc;

  # A sha256 hashsum of the concatenated output of the program.
  # This can be `null` to disable the checksum mechanism.
  hash = "87901231393b51cdd45bbb4339a32db2894a3a5ab164cb5c7a8fa14721fdcba7";
}
```

### The test description file

All line starting with `#` or only containing white space are
ignored. Additionally, all leading and trailing white space is stripped
before evaluating.

The general syntax is:

```
COMMAND ARGS
```

where `COMMAND` is one of the commands listed in [Commands](#commands)

The `ARGS` are the verbatim content from the space after the `COMMAND`
to the end of line character.

You can run the description file, similarly as in the tests via the `run_test_description`
package exported by the flake.

#### Commands

##### `Type`

Send the `ARGS` to the application. This interprets `ARGS` as specified
by the TMUX (1) man page on `send-keys`.

#### `Sleep`

Sleep for `ARGS` seconds.

#### `Expect`

Grep the currently visible screen for the regex `ARGS`.  This regex
must match.

#### `ExpectNot`

Does the same thing as [Expect](#expect), but enforces, that the
regex does not match.

#### `SetGolden`

Set the golden file (the file used for the hash generation) to `ARGS`.
`ARGS` must be a valid file path.

#### `Exec`

Executes the command (`ARGS`) and waits until it finishes.
This will hang forever, when the command that does not exit.