Speclj
A TDD/BDD framework for Clojure and ClojureScript, inspired by RSpec.
What is Speclj?
Speclj is a testing framework for Clojure and ClojureScript designed for test-driven and behavior-driven development. It provides a familiar RSpec-like syntax with `describe` and `it` blocks to structure tests, along with assertions like `should` and `should-not`. It solves the problem of writing clear, expressive, and maintainable specifications for Clojure projects across multiple platforms.
Clojure and ClojureScript developers who practice TDD/BDD and want a structured, RSpec-inspired testing framework. It's also suitable for teams working on multi-platform Clojure projects (including CLR and Babashka).
Developers choose Speclj for its clean, readable syntax that reduces boilerplate, its broad platform support beyond just JVM Clojure, and its integrated tooling like the autotest runner and Cloverage integration for a comprehensive testing workflow.
Overview
pronounced "speckle": a TDD/BDD framework for Clojure.
Use Cases
Best For
- Writing behavior-driven specifications for Clojure libraries
- Testing ClojureScript applications with a familiar RSpec-like workflow
- Multi-platform Clojure projects that target JVM, CLR, or Babashka
- Teams adopting test-driven development practices in Clojure
- Generating code coverage reports integrated with Cloverage
- Automatically re-running tests on file changes with the autotest runner
Not Ideal For
- Projects relying on property-based or generative testing, as Speclj is focused on BDD-style specifications without built-in support for tools like test.check.
- Environments where PhantomJS is deprecated or unavailable for ClojureScript testing, due to Speclj's manual setup requiring it.
- Teams using build systems other than Leiningen or deps.edn, since Speclj's tooling and examples are tightly coupled with these.
- Developers who prefer the minimalist, standard-library approach of clojure.test for simpler unit testing without BDD syntax.
Pros & Cons
Pros
Based on RSpec, it uses describe, it, should, and should-not for readable test structures, as shown in the sample spec files, making tests clear and maintainable.
Runs on Clojure, ClojureScript, Clojure CLR, and Babashka, providing a consistent testing framework across multiple Clojure ecosystems.
The -a flag enables a vigilant auto-runner that re-executes specs on code changes, improving development workflow without third-party tools.
Works seamlessly with Cloverage to generate coverage reports, as detailed in the Code Coverage section, offering built-in metrics for test suites.
Cons
Requires manual configuration with PhantomJS and specific project.clj settings, which is error-prone and relies on outdated JavaScript runtimes.
Compared to clojure.test, it has fewer community plugins and integrations, and the API documentation is hosted on a personal site, not always updated.
Tight integration with Leiningen and deps.edn may not suit projects using alternative build systems, and the eval-in option for Leiningen carries risks.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.