2 API Reference

9.0

2 API Reference🔗ℹ

2.1 The feature Language🔗ℹ

Feature files use #lang feature and follow a subset of the Gherkin specification. The reader parses the file and provides a single binding:

features — a (listof gherkin-feature?) containing the parsed feature structures. Require the ".feature" file from a Racket module to access this binding.

2.2 Core API🔗ℹ

The rackunit/feature module provides the two primary entry points for defining and running BDD tests.

syntax
(define-steps name clause ...)

clause = (given pattern handler)
| (when pattern handler)
| (then pattern handler)

pattern = string?

handler = (-> hash? any/c ... hash?)

Defines name as a list of step-def structures.

Each clause pairs a step keyword with a pattern and handler function. The keywords given, when, and then are matched by datum — they do not shadow racket/base’s when.

The pattern is a string that may contain {placeholder} markers. Each placeholder becomes a capture group. Captured values are passed to the handler as strings after the context argument.

(define-steps my-steps
  (given "a user named {name}"
    (lambda (ctx name)
      (hash-set ctx 'user name)))
  (when "the user logs in"
    (lambda (ctx)
      (hash-set ctx 'logged-in? #t)))
  (then "the welcome message is {msg}"
    (lambda (ctx msg)
      (check-equal? (hash-ref ctx 'welcome) msg)
      ctx)))

procedure
(run-features features
[ #:steps steps
#:before-all before-all
#:after-all after-all
#:before-feature before-feature
#:after-feature after-feature
#:before-scenario before-scenario
#:after-scenario after-scenario
#:before-step before-step
#:after-step after-step]) → void?
  features : (listof gherkin-feature?)
  steps : (listof step-def?) = '()
  before-all : (-> hash? hash?) = (lambda (ctx) ctx)
  after-all : (-> hash? hash?) = (lambda (ctx) ctx)
   before-feature : (-> hash? gherkin-feature? hash?)
= (lambda (ctx f) ctx)
   after-feature : (-> hash? gherkin-feature? hash?)
= (lambda (ctx f) ctx)
   before-scenario : (-> hash? gherkin-scenario? hash?)
= (lambda (ctx sc) ctx)
   after-scenario : (-> hash? gherkin-scenario? hash?)
= (lambda (ctx sc) ctx)
   before-step : (-> hash? gherkin-step? hash?)
= (lambda (ctx st) ctx)
   after-step : (-> hash? gherkin-step? hash?)
= (lambda (ctx st) ctx)

Builds rackunit test suites from features and runs them.

An empty hash table is created, passed through before-all, then threaded through features, scenarios, and steps. Each scenario receives a fresh copy of the context from before-feature, isolating scenarios from one another. Background steps (if any) run before each scenario’s own steps.

See the Lifecycle Hooks section of the guide for the full execution order.

2.3 AST Types🔗ℹ

These prefab structures represent parsed Gherkin documents. They are produced by the #lang feature reader and consumed by run-features.

struct
(struct gherkin-document (srcloc features)
    #:prefab)
  srcloc : any/c
  features : (listof gherkin-feature?)

The top-level container returned by the parser. Contains the list of gherkin-feature structures found in the source file. Most users interact with features directly (as provided by #lang feature) rather than the document wrapper.

struct
(struct gherkin-feature (srcloc name tags background scenarios)
    #:prefab)
  srcloc : any/c
  name : string?
  tags : (listof string?)
  background : (listof gherkin-step?)
  scenarios : (listof gherkin-scenario?)

A single Feature: block. The tags field contains tag strings (e.g., "@smoke"). The background is a (possibly empty) list of steps that run before every scenario.

struct
(struct gherkin-scenario (srcloc name tags steps)
    #:prefab)
  srcloc : any/c
  name : string?
  tags : (listof string?)
  steps : (listof gherkin-step?)

A Scenario: or expanded Scenario Outline: instance. When expanded from an outline, the name includes parameter values (e.g., "Addition (a=1, b=2, result=3)").

struct
(struct gherkin-step (srcloc type text argument)
    #:prefab)
  srcloc : any/c
  type : symbol?
  text : string?
  argument : any/c

A single step. The type is one of 'given, 'when, 'then, 'and, or 'but. The argument is #f when absent, a (listof (listof string?)) for a data table, or a string? for a doc string.

2.4 Runtime🔗ℹ

Lower-level utilities for step definition matching and execution.

struct
(struct step-def (type pattern handler)
    #:transparent)
  type : symbol?
  pattern : string?
  handler : procedure?

A step definition binding a type ('given, 'when, or 'then), a pattern string (possibly containing {placeholder} markers), and a handler procedure.

procedure
(compile-step-pattern pattern) → regexp?
pattern : string?

Converts a step pattern to a compiled regular expression. Each {placeholder} becomes a (.+?) non-greedy capture group, and the result is anchored with ^ and $.

(compile-step-pattern "I add {a} and {b}")
; => #px"^I add (.+?) and (.+?)$"

procedure
(run-step step-defs
type
text
ctx
[ #:argument argument]) → hash?
  step-defs : (listof step-def?)
  type : symbol?
  text : string?
  ctx : hash?
  argument : any/c = #f

Finds the first step-def in step-defs whose type matches and whose pattern matches text, then calls its handler with ctx, captured values, and (when non-#f) the argument.

Raises exn:fail? if no matching step definition is found.