From 116f905b6c1df01f7c2dddef4f662abd0fcb5d42 Mon Sep 17 00:00:00 2001
From: technofab <admin@technofab.de>
Date: Sat, 14 Jun 2025 15:16:25 +0200
Subject: [PATCH 1/2] chore(testHelpers): remove string context in toJsonFile

---
 lib/testHelpers.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/testHelpers.nix b/lib/testHelpers.nix
index 0edb595..c86a6a8 100644
--- a/lib/testHelpers.nix
+++ b/lib/testHelpers.nix
@@ -2,6 +2,6 @@
   path = pkgs: "export PATH=${lib.makeBinPath pkgs}";
   pathAdd = pkgs: "export PATH=$PATH:${lib.makeBinPath pkgs}";
   scriptHelpers = builtins.readFile ./scriptHelpers.sh;
-  toJsonFile = any: builtins.toFile "actual" (builtins.toJSON any);
+  toJsonFile = any: builtins.toFile "actual" (builtins.unsafeDiscardStringContext (builtins.toJSON any));
   toPrettyFile = any: builtins.toFile "actual" (lib.generators.toPretty {} any);
 }

From bc36c39b0929bdfaab0908d8bd852c2114e3383f Mon Sep 17 00:00:00 2001
From: technofab <admin@technofab.de>
Date: Sat, 14 Jun 2025 17:23:24 +0200
Subject: [PATCH 2/2] docs: document new lib functions & usage

---
 docs/examples.md  |  4 +++-
 docs/reference.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/usage.md     | 40 ++++++++++++++++++++++++++++++-----
 flake.nix         |  2 ++
 4 files changed, 93 insertions(+), 6 deletions(-)
 create mode 100644 docs/reference.md

diff --git a/docs/examples.md b/docs/examples.md
index 4e3ad41..c61c754 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -1,4 +1,6 @@
 # Example Configs
 
+- [nixtest itself](https://gitlab.com/TECHNOFAB/nixtest)
+    see `flake.nix` and `tests/`
 - [TECHNOFAB/nix-gitlab-ci](https://gitlab.com/TECHNOFAB/nix-gitlab-ci)
-    see tests/
+    see `tests/`
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 0000000..fe9d7cb
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,53 @@
+# Reference
+
+## `flakeModule`
+
+The `flakeModule` for [flake-parts](https://flake.parts).
+
+## `lib`
+
+### `module`
+
+The nix module for validation of inputs etc.
+Used internally by `mkNixtestConfig`.
+
+### `autodiscover`
+
+```nix
+autodiscover {
+  dir,
+  pattern ? ".*_test.nix",
+}
+```
+
+Finds all test files in `dir` matching `pattern`.
+Returns a list of modules (can be passed to `mkNixtest`'s `modules` arg).
+
+### `mkNixtestConfig`
+
+```nix
+mkNixtestConfig {
+  modules,
+  args ? {},
+}
+```
+
+Evaluates the test `modules`.
+`args` are passed to the modules using `_module.args = args`.
+
+**Noteworthy attributes**:
+
+- `app`: nixtest wrapper
+- `finalConfigJson`: derivation containing the tests json file
+
+### `mkNixtest`
+
+```nix
+mkNixtest {
+  modules,
+  args ? {},
+}
+```
+
+Creates the nixtest wrapper, using the tests in `modules`.
+Basically `(mkNixtestConfig <arguments>).app`.
diff --git a/docs/usage.md b/docs/usage.md
index fbcccb3..a329017 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -2,6 +2,9 @@
 
 ## Flake Module
 
+The easiest way to use Nixtest is probably using the flakeModule.
+Just import `nixtest.flakeModule`, then define suites and tests in `perSystem`:
+
 ```nix
 {
   inputs.nixtest.url = "gitlab:TECHNOFAB/nixtest?dir=lib";
@@ -34,10 +37,25 @@
 
 ## Library
 
-You can also integrate nixtest in your own workflow by using the lib functions directly.
-Check out `flakeModule.nix` to see how it's used there.
+You can also use the lib directly, like this for example:
 
-<!-- TODO: more detailed? -->
+```nix
+packages.tests = ntlib.mkNixtest {
+  modules = ntlib.autodiscover {dir = ./tests;};
+  args = {
+    inherit pkgs ntlib;
+  };
+};
+```
+
+This will auto-discover all test files ending with `_test.nix`.
+See [reference](reference.md) for all params to `autodiscover`.
+
+`ntlib` can be defined like this:
+
+```nix
+ntlib = inputs.nixtests.lib {inherit pkgs;};
+```
 
 ## Define Tests
 
@@ -84,9 +102,17 @@ Examples:
     # to make it more reproducible and cleaner, use --pure to switch to pure
     # mode which will unset all env variables before running the test. That 
     # requires you to set PATH yourself then:
+    # 
+    # ''
+    #  export PATH="${lib.makeBinPath [pkgs.gnugrep]}"
+    #  grep -q "test" ${builtins.toFile "test" "test"}
+    # '';
+    #
+    # you can also use the helpers to make it nicer to read:
     ''
-      export PATH="${lib.makeBinPath [pkgs.gnugrep]}"
-      grep -q "test" ${builtins.toFile "test" "test"}
+      ${ntlib.helpers.path [pkgs.gnugrep]}
+      ${ntlib.helpers.scriptHelpers}  # this adds helpers like assert etc.
+      assert_file_contains ${builtins.toFile "test" "test"} "test" "file should contain 'test'"
     '';
   }
   {
@@ -102,3 +128,7 @@ Examples:
   }
 ]
 ```
+
+!!! note
+
+    for more examples see [examples](./examples.md)
diff --git a/flake.nix b/flake.nix
index f0a2570..72f86bd 100644
--- a/flake.nix
+++ b/flake.nix
@@ -106,11 +106,13 @@
             nav = [
               {"Introduction" = "index.md";}
               {"Usage" = "usage.md";}
+              {"Reference" = "reference.md";}
               {"CLI" = "cli.md";}
               {"Example Configs" = "examples.md";}
             ];
             markdown_extensions = [
               "pymdownx.superfences"
+              "admonition"
             ];
             extra.analytics = {
               provider = "umami";