feat: add new assertions test type

docs/reference.md

@@ -51,3 +51,24 @@ mkNixtest {
 
 Creates the nixtest wrapper, using the tests in `modules`.
 Basically `(mkNixtestConfig <arguments>).app`.
+
+### `asserts` / `expect`
+
+Assertion matchers for `type = "assertions"` tests (also available as `ntlib.helpers.expect` and `ntlib.helpers.asserts`):
+
+- `eq expected actual` / `equal`: checks `actual == expected`.
+- `ne expected actual` / `notEqual`: checks `actual != expected`.
+- `gt actual min` / `greaterThan`: checks `actual > min`.
+- `gte actual min` / `greaterThanOrEqual`: checks `actual >= min`.
+- `lt actual max` / `lessThan`: checks `actual < max`.
+- `lte actual max` / `lessThanOrEqual`: checks `actual <= max`.
+- `contains container item`: checks if a list contains an element, or a string contains a substring.
+- `notContains container item`: checks a list does not contain an element, or a string does not contain a substring.
+- `hasAttr attr set`: checks if an attrset has the given attribute.
+- `missingAttr attr set`: checks if an attrset lacks the given attribute.
+- `hasAttrs attrs set`: checks if an attrset has all attributes in the given list.
+- `matches regex str`: checks if a string matches the given regex pattern.
+- `isNull val` / `isNotNull`: null checks.
+- `isEmpty val` / `isNotEmpty`: checks if list, string, or attrset is empty / not empty.
+- `throws expr` / `fails`: asserts that evaluating `expr` throws or aborts.
+- `custom cond message` / `that`: custom condition with failure explanation message.

docs/usage.md

@@ -144,6 +144,25 @@ Examples:
         '';
     };
   }
+{
+    name = "assertions-test";
+    type = "assertions";
+    assertions = {
+      # Use rich matchers with automatic failure details (available as ntlib.asserts.* or ntlib.expect.*):
+      "equality" = ntlib.asserts.eq 200 response.status;
+      "greater than" = ntlib.asserts.gt config.port 1024;
+      "list contains" = ntlib.asserts.contains config.users "admin";
+      "has attribute" = ntlib.asserts.hasAttr "nginx" config.services;
+      "matches regex" = ntlib.asserts.matches "^v[0-9]+" pkg.version;
+      "throws error" = ntlib.asserts.throws (throw "invalid config");
+
+      # Or simple booleans:
+      "is enabled" = config.enable == true;
+
+      # Or custom failure messages:
+      "memory limit" = if mem > 512 then true else "memory was ${toString mem}MB (expected > 512MB)";
+    };
+  }
 ]
 ```