about summary refs log tree commit diff
path: root/nix/buildLisp/README.md
diff options
context:
space:
mode:
authorGriffin Smith <grfn@gws.fyi>2020-07-27T01·11-0400
committerglittershark <grfn@gws.fyi>2020-07-27T14·18+0000
commit3089f6b6ce84833f669bb523718b20b6ad194105 (patch)
treecfa8b5c0f93c3adaf82b30595718167b5efe0565 /nix/buildLisp/README.md
parentd98f2ea68fa9c73f1cc4acfdfb9a427ae3e47f63 (diff)
feat(nix/buildLisp): Add abstraction for test suites r/1492
Add support for explicitly specifying tests as part of a buildLisp
program or library.

Change-Id: I733213c1618f0fa60f645465560bce0522641efd
Reviewed-on: https://cl.tvl.fyi/c/depot/+/1481
Tested-by: BuildkiteCI
Reviewed-by: tazjin <mail@tazj.in>
Diffstat (limited to 'nix/buildLisp/README.md')
-rw-r--r--nix/buildLisp/README.md25
1 files changed, 23 insertions, 2 deletions
diff --git a/nix/buildLisp/README.md b/nix/buildLisp/README.md
index 8e45f3479c06..452f495debd4 100644
--- a/nix/buildLisp/README.md
+++ b/nix/buildLisp/README.md
@@ -16,8 +16,6 @@ Nix-based ecosystem. This offers several advantages over ASDF:
 The project is still in its early stages and some important
 restrictions should be highlighted:
 
-* There is no separate abstraction for tests at the moment (i.e. they
-  are built and run as programs)
 * Only SBCL is supported (though the plan is to add support for at
   least ABCL and Clozure CL, and maybe make it extensible)
 
@@ -33,6 +31,7 @@ restrictions should be highlighted:
   | `srcs`    | `list<path>` | List of paths to source files | yes       |
   | `deps`    | `list<drv>`  | List of dependencies          | no        |
   | `native`  | `list<drv>`  | List of native dependencies   | no        |
+  | `test`    | see "Tests"  | Specification for test suite  | no        |
 
   The output of invoking this is a directory containing a FASL file
   that is the concatenated result of all compiled sources.
@@ -46,6 +45,7 @@ restrictions should be highlighted:
   | `deps`    | `list<drv>`  | List of dependencies          | no        |
   | `native`  | `list<drv>`  | List of native dependencies   | no        |
   | `main`    | `string`     | Entrypoint function           | no        |
+  | `test`    | see "Tests"  | Specification for test suite  | no        |
 
   The `main` parameter should be the name of a function and defaults
   to `${name}:main` (i.e. the *exported* `main` function of the
@@ -71,6 +71,22 @@ restrictions should be highlighted:
   pre-loaded with all of that Lisp code and can be used as the host
   for e.g. Sly or SLIME.
 
+## Tests
+
+Both `buildLisp.library` and `buildLisp.program` take an optional argument
+`tests`, which has the following supported fields:
+
+  | parameter    | type         | use                           | required? |
+  |--------------|--------------|-------------------------------|-----------|
+  | `name`       | `string`     | Name of the test suite        | no        |
+  | `expression` | `string`     | Lisp expression to run tests  | yes       |
+  | `srcs`       | `list<path>` | List of paths to source files | no        |
+  | `native`     | `list<drv>`  | List of native dependencies   | no        |
+
+the `expression` parameter should be a Lisp expression and will be evaluated
+after loading all sources and dependencies (including library/program
+dependencies). It must return a non-`NIL` value if the test suite has passed.
+
 ## Example
 
 Using buildLisp could look like this:
@@ -92,5 +108,10 @@ in buildLisp.program {
     name = "example";
     deps = [ libExample ];
     srcs = [ ./main.lisp ];
+    tests = {
+      deps = [ lispPkgs.fiveam ];
+      srcs = [ ./tests.lisp ];
+      expression = "(fiveam:run!)";
+    };
 }
 ```