Getting Started

From an empty project to a first green scenario.

1. Add the dependency

;; deps.edn
io.github.hiram-madelaine/clornichon {:mvn/version "0.1.3"}
;; or project.clj
[io.github.hiram-madelaine/clornichon "0.1.3"]

The namespaces keep their scenari.* names:

(:require [scenari.v2.core :refer [defgiven defwhen defthen deffeature]])

2. Write a feature file

A feature is plain Gherkin. Every .feature starts with Feature: (or a tag or a comment); a bare Scenario: is a parse error.

# test/features/cart.feature
Feature: shopping cart

  Scenario: adding items
    Given a cart with 2 items
    When I add 3 items
    Then the cart holds 5 items

3. Write the glue

Each step sentence is bound to a Clojure function by a cucumber expression. The first argument is the scenario state -- what the previous step returned -- then one argument per token of the expression.

(ns cart-test
  (:require [clojure.test :refer [is]]
            [scenari.v2.core :refer [defgiven defwhen defthen deffeature]]))

(defgiven "a cart with {int} items" [_ n]
  {:cart n})

(defwhen "I add {int} items" [state n]
  (update state :cart + n))

(defthen "the cart holds {int} items" [state n]
  (is (= n (:cart state))))

A defthen ending on an assertion keeps the state it received: no trailing state needed.

4. Declare the feature

(deffeature shopping-cart "test/features/cart.feature")

deffeature defines a deftest named shopping-cart. It takes a path on the filesystem or on the classpath, a directory of features, or the Gherkin text itself. Each step's glue is resolved right there, so the glues must be loaded before the deffeature -- in the same namespace above it, or in a namespace it requires.

5. Run it

(clojure.test/run-tests 'cart-test)
;; ________________________
;; Feature : shopping cart
;;
;; Testing scenario : adding items
;;   Given a cart with 2 items         (from cart-test/"a cart with {int} items")
;;   When I add 3 items         (from cart-test/"I add {int} items")
;;   Then the cart holds 5 items         (from cart-test/"the cart holds {int} items")
;; adding items succeed !

A step without glue prints the skeleton to paste:

Missing step for : When I remove 1 item
(defwhen "I remove {int} item"  [state arg0]  (do "something"))

Next

• Running features: clojure.test, Kaocha, tags, --dry-run, HTML documentation
• Step expressions: tokens, regexes, datatables and doc strings
• State and hooks: initial state, chaining, before/after
• Development workflow: the full cycle, in depth