Skip to content

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.

The project is intentionally dependency-free at the core. It should be easy to run in CI, embed in ASDF projects, and extend from the REPL.

New to cl-weave?

Install it in one command, then write your first suite in under a minute:

nix run github:nerima-lisp/cl-weave -- --help   # run without installing

Continue with Installation → Quick Start → DSL Guide.

Explore the docs

Status

Stable (1.0). The capability list below is the committed public surface, and it is validated by the CI entrypoints documented in Reporters and CI on Linux. Within the 1.x series, changes stay backward-compatible under Semantic Versioning; breaking changes ship only in a new major version:

  • describe / it hierarchical test DSL
  • expect matcher assertions with readable failure reports
  • smart S-expression assertions that capture operand values
  • with-soft-assertions blocks that run every expectation and report all failures together
  • it-each and describe-each compile-time table tests
  • canonical hyphenated variants such as it-only, describe-concurrent, expect-not, expect-resolves, and expect-assertions
  • it-property deterministic property tests with shrinking
  • form-level mutation testing with macro-defined operators
  • it-isolated subprocess tests for FFI and crash boundaries
  • before-all / after-all, before-each / after-each, and CPS around-each dynamic fixtures
  • describe-skip / it-skip skipped suites and cases
  • describe-skip-if / it-skip-if and run-if conditional registration
  • describe-only / it-only focused runs
  • describe-todo / it-todo todo suites and cases
  • Vitest-style test name filtering for focused local and CI runs
  • Vitest-style test discovery list mode for AI agents and CI tooling
  • declarative logic-query engine (logic-program, logic-run, test-plan-where, journal-where) for querying the test plan and time-travel journal as Prolog-style facts
  • AI-friendly CLI metadata for typed/enumerated options, artifact schemas with field maps, capability matrix, package exports, policy documents, matchers, mutations, and MOP architecture assertions
  • source file metadata in structured reporters and test plans
  • Vitest-style deterministic sequence ordering for flaky-test reproduction
  • time-travel execution journal recording an assertion/mock-call/hook/shrink-step/note timeline per attempt, surfaced in the spec and JSON reporters
  • deterministic per-test random replay with recorded seeds and single-test replay-test
  • interactive time-travel breakpoints: *journal-breakpoint* signals journal-breakpoint-hit at a chosen frame, dropping into a live debugger or a programmatic handler-bind hook
  • CLOS-extensible journal frame kinds: record-journal-frame records your own frame kind, journal-frame-line-for-kind is an eql-specialized generic function for rendering it
  • reloadable timelines: journal-frame-from-plist rebuilds journal-frame objects from a saved sexp results artifact, so a CI-captured timeline can be read back and analyzed offline with explain-journal / journal-diff / journal-where
  • Vitest-style :bail execution control for fast-fail CI runs
  • Vitest-style per-test :retry and :timeout-ms controls
  • Vitest-style it-concurrent / describe-concurrent parallel execution modes
  • Vitest-style it-fails expected-failure cases
  • Vitest-style length, instance, inline snapshot, and external snapshot matchers
  • CI-friendly thunk runtime and allocation assertions
  • SBCL sb-cover reset/save integration for CI coverage artifacts
  • Vitest-style mock functions with call history assertions
  • ASDF system definitions
  • ASDF-aware system runner and watch mode
  • spec, S-expression, JSON, JSONL, TAP, GitHub Actions, and JUnit XML reporters
  • non-zero process exit on failure for CI
  • safe dynamic global function mocking with with-mocked-functions

Guide Map

  • DSL Guide — suites, cases, fixtures, skipping, focus/todo, retry/timeout, concurrency, and table tests.
  • Assertions and Matchers — expect, built-in and custom matchers, performance, and numeric assertions.
  • Property Testing — it-property and the built-in generator library.
  • Mutation Testing — mutation operators and CI score gates.
  • Mocking — mock functions, spies, and call-history matchers.
  • Benchmarking — the benchmark / measure micro-benchmark helper and its timing statistics.
  • Time-Travel Debugging — the execution journal, deterministic replay, single-test replay, and interactive breakpoints.
  • Test Execution — filtering, sharding, sequencing, listing, declarative plan queries, bail, subprocess isolation, and watch mode.
  • Logic Programming — the unification/backtracking query engine behind declarative test-plan queries.
  • Reporters and CI — reporter formats, coverage, and the GitHub Actions pipeline.
  • AI Discovery — the machine-readable metadata contract for agents and generators.

Reference Map

Nix Workflow

The flake.nix at the repository root packages cl-weave as a Nix flake:

  • nix develop — a devShell with SBCL and GNU coreutils, and paredit-cli for structural S-expression edits.
  • nix run . -- <command> — the packaged CLI (run, list, watch, doctor, metadata, version, help).
  • nix run .#test — the self-test suite through run-tests.lisp.
  • nix flake check — every CI entrypoint (test suite, reporters, coverage gate, AI metadata, CLI smoke tests, paredit-lint structural parse check, the treefmt formatting gate, and the docs build) as reproducible derivations.
  • nix build .#docs — builds this documentation site with MkDocs (Material) in --strict mode, so broken links fail the build.
  • nix fmt — formats Nix sources with treefmt (nixfmt).

Running direnv allow loads the devShell automatically.

Support

Use Support Policy for the canonical support boundaries.

Use Issue Reporting Guide for reproducible bugs and behavior questions.

Use private GitHub security advisories for vulnerability reporting. Do not put exploit details in a public issue.

Project Operations

Runtime metadata mirrors these operations surfaces through policyDocuments, referenceDocuments, supportChannels, communityHealth, securityContacts, lifecycle, runtimeSupport, and releaseProcess for agent-side OSS operations discovery.

License

MIT. See LICENSE.