DOCSEARCHbyAlgolia
Submit Docs

Midje Documentation

repository·master·Indexed 23 days ago

https://github.com/marick/midje

A Clojure testing framework designed for readability and ease of use, making tests resemble executable code examples. Midje supports top-down and bottom-up testing, provides a migration path from clojure.test, and is optimized for REPL-driven development. The framework utilizes a three-step parsing pipeline—converting implicit syntax to explicit forms, generating lexical maps for scope handling, and final evaluation—and includes specialized macros such as tabular and formula.

Tokens
816
Snippets
3
Records
6
Agent score
33%

What's inside Midje

  1. What is Midje?

    master
    Midje is a test framework for Clojure designed to provide readable, machine-checkable tests that resemble Clojure code examples. It supports both top-down and bottom-up testing approaches and provides a smooth migration path for users coming from clojure.test. It is designed to be used idiomatically within a REPL, allowing for rapid development cycles where tests are automatically re-run upon file changes while maintaining an interactive prompt.

  2. Convert implicit facts to explicit forms

    master

    Midje uses an implicit syntax for defining facts, where examples and prerequisites are identified by their structure rather than explicit function names like (example ...) or (prerequisite ...).

    Implicit Syntax Example:

    (facts "about my-fun"
  (myfun 3) => 4
  (myfun -1) => 4
  (provided
    (helper 1) => 2
    (helper 2) => 2))

    During the first step of parsing, this is converted into an explicit internal representation:

    Explicit Form Equivalent:

    (expect (myfun 3) => 4)
(expect (myfun -1) => 4 
        (fake (helper 1) => 2)
        (fake (helper 2) => 2))

  3. Understand the Midje parsing process

    master

    Midje's parsing engine transforms implicit fact syntax into evaluated results through a three-step pipeline. While users typically interact with the implicit syntax, understanding this pipeline helps in debugging how facts are expanded and evaluated.

    1. Implicit to Explicit Conversion: Converts non-Lispy, implicit syntax (where examples and prerequisites are inferred) into explicit expect and fake forms.
    2. Lexical Map Generation: Converts explicit forms into "lexical maps". These maps capture the code forms (like a function call or an expected result) without evaluating them immediately, ensuring they can be evaluated later within the correct lexical scope (e.g., inside a let block).
    3. Evaluation: Executes the lexical maps to transform them into fully evaluated maps, using Midje-specific functions to resolve values and matchers.

  4. How lexical maps handle scoping

    master

    To ensure that facts can correctly access variables from their surrounding lexical context (like a let block), Midje converts explicit forms into "lexical maps".

    If you write:

    (let [a 1]
  (fact (* a 1) => a))

    Midje does not evaluate (* a 1) immediately. Instead, it creates a lexical map that stores the un-evaluated forms. This allows the engine to evaluate the forms later in the correct context where a is defined.

    A representative lexical map looks like this:

    {:function-under-test (fn [] (* a 1))
 :expected-result a
 :expected-result-form 'a}

  5. Install Midje via Clojars

    master

    Midje is available as a dependency via Clojars. You can add it to your Clojure project using your preferred dependency management tool (such as Leiningen or Deps.edn) by referencing the midje artifact on Clojars.

    https://clojars.org/midje

  6. Identify Midje fact-wrapping macros

    master

    Midje provides two primary macros that wrap facts to provide specialized syntax or behavior:

    • tabular: Used for defining facts in a tabular format.
    • formula: Used for defining facts using formula-based syntax.

    These macros expand into the standard fact-processing pipeline.