add describe function

flake.nix

@@ -9,10 +9,12 @@
     pkgs = import nixpkgs {inherit system;};
     tix = import ./tix/. {inherit pkgs;};
   in
-    tix // {
+    tix
+    // {
       packages.x86_64-linux.test = tix.run [
         ./test/it.test.nix
         ./test/test.test.nix
+        ./test/describe.test.nix
       ];
       packages.x86_64-linux.example = tix.run [
         ./mytest.nix

test/describe.test.nix

@@ -0,0 +1,21 @@
+{
+  describe,
+  it,
+  ...
+}:
+describe "the describe function" [
+  (it "returns an array with the message changed" {
+    expected = [
+      {
+        success = true;
+        msg = "the describe function: works";
+      }
+    ];
+    actual = describe "the describe function" [
+      {
+        success = true;
+        msg = "works";
+      }
+    ];
+  })
+]

test/it.test.nix

@@ -1,11 +1,17 @@
-{ it, ... }:
-[
+{
+  it,
+  describe,
+  ...
+}:
+describe "it" [
   (it "test's itself???" rec {
-    expected = {success = true; msg = "test's itself???";};
-    actual = 
-      (it "test's itself???" {
+    expected = {
+      success = true;
+      msg = "test's itself???";
+    };
+    actual = it "test's itself???" {
       expected = expected;
       actual = expected;
-      });
+    };
   })
 ]

test/run.test.nix

@@ -1,10 +1,8 @@
-{ it, ... }:
-let
+{it, ...}: let
   pkgs = import <nixpkgs> {}; # impure ¯\_(ツ)_/¯
   run = import ../tix/run.nix pkgs;
-  output = run [ ./it.test.nix ];
-in
-[
+  output = run [./it.test.nix];
+in [
   (it "makes a derivation called test" {
     expected = "test";
     actual = output.name;

test/test.test.nix

@@ -1,18 +1,26 @@
-{ it, ... }:
-let
+{
+  describe,
+  it,
+  ...
+}: let
   test = import ../tix/test.nix;
 in
-[
+  describe "the test function" [
     (it "get's test results" {
-    expected = [{"msg" = "test's itself???"; "success"= true;}];
-    actual = ( test ./it.test.nix ).results;
+      expected = [
+        {
+          "msg" = "it: test's itself???";
+          "success" = true;
+        }
+      ];
+      actual = (test ./it.test.nix).results;
     })
     (it "has a path" {
-    actual = builtins.typeOf ( test ./it.test.nix ).path;
+      actual = builtins.typeOf (test ./it.test.nix).path;
       expected = "path";
     })
     (it "fails to build non test" {
-    actual = ( test ./bad/string.nix );
+      actual = test ./bad/string.nix;
       throws = true;
     })
-]
+  ]

tix/describe.nix

@@ -0,0 +1,8 @@
+name:
+map ({
+    msg,
+    success,
+    actual ? null,
+    expected ? null,
+  } @ result:
+    result // {msg = "${name}: ${msg}";})

tix/test.nix

@@ -1,14 +1,14 @@
 path: let
   it = import ./it.nix;
+  describe = import ./describe.nix;
   suite = import path;
 in
   builtins.trace ("testing " + builtins.baseNameOf path)
   (
     if !builtins.isFunction suite
     then throw "A test suite should be in the form { it }: [ <tests> ]."
-   else
-   {
+    else {
       inherit path;
-   results = suite {inherit it;};
+      results = suite {inherit it describe;};
     }
   )