cl-weave

cl-weave is a modern Common Lisp testing framework inspired by Vitest and designed around Lisp's strengths: macros, conditions, dynamic bindings, and reproducible Nix workflows. It is intentionally dependency-free at the core, and easy to run in CI, embed in ASDF projects, and extend from the REPL. It is the test framework used by every package in the nerima-lisp org.

Full documentation, including the DSL guide, matcher reference, and AI discovery contract, is published at https://nerima-lisp.github.io/cl-weave/. The source for that site lives in docs/src/.

Quick Start

(defpackage #:example/test
  (:use #:cl)
  (:shadowing-import-from #:cl-weave #:describe)
  (:import-from #:cl-weave #:expect #:it))

(in-package #:example/test)

(describe "math"
  (it "adds numbers"
    (expect (+ 1 1) :to-be 2))

  (it "compares structures"
    (expect (list :ok 42) :to-equal (list :ok 42))))

nix run . -- run cl-weave/test

See Quick Start for more CLI examples and Installation for every install path.

Install

nix run github:nerima-lisp/cl-weave -- --help    # run without installing
nix profile install github:nerima-lisp/cl-weave  # install via Nix
nix develop -c nix profile install .           # from a local checkout

As a flake input, pin a release tag rather than following the default branch:

# flake.nix
inputs.cl-weave = {
  url = "github:nerima-lisp/cl-weave/v1.0.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

Documentation

• Installation
• Quick Start
• DSL Guide
• API Reference

Development

nix develop          # SBCL, coreutils, jq, libxml2, paredit-cli
nix run .#test       # the self-test suite
nix flake check      # tests + formatting + docs, the same gate CI uses
nix build .#docs     # the documentation site, with mkdocs --strict
nix fmt              # format Nix sources (treefmt)

Tests live in t/ under the cl-weave/test system, and run-tests.lisp at the repository root is the Lisp-level entry point. See Development for the full workflow.

Contributing

See the org-wide CONTRIBUTING guide, the package standard, and this project's Development page.

Support

See SUPPORT and this project's Support Policy for the canonical support boundaries.

Report vulnerabilities through private GitHub security advisories. Do not put exploit details in a public issue.

Community conduct is defined by the org-wide Code of Conduct, and release history is in CHANGELOG.md and GitHub Releases.

License

MIT. See LICENSE.