tests(tests): Initialize infrastructure and documentation for it

1 files changed, 75 insertions, 0 deletions

diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 00000000..fe93dc96
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,75 @@
+# 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.
+
+#### 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.
+