Provides hooks for setup and teardown in Cucumber tests.

Four levels of hooks are supported, mirroring reference Cucumber implementations:

• before_all/after_all — run once per test run (see below)
• before_scenario/after_scenario — run around each scenario
• before_step/after_step — run around each step (including background steps)

Scenario and step hooks can be filtered by tag. Hooks of the same kind run in the order they are defined (module order, then definition order), with after-hooks running in reverse. Any hook can be given a name:, which appears in failure output (and in Cucumber Messages, eventually).

Examples

defmodule DatabaseSupport do
  use Cucumber.Hooks

  # Runs once before the first scenario of the run
  before_all context do
    {:ok, Map.put(context, :api_started, true)}
  end

  # Runs once after the whole run, in reverse definition order
  after_all _context do
    :ok
  end

  # Global before hook - runs for all scenarios
  before_scenario context, name: "prepare database" do
    {:ok, Map.put(context, :setup, true)}
  end

  # Tagged before hook - only runs for @database scenarios
  before_scenario "@database", context do
    :ok = Ecto.Adapters.SQL.Sandbox.checkout(MyApp.Repo)

    if context.async do
      Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, {:shared, self()})
    end

    {:ok, context}
  end

  # After hooks run in reverse order
  after_scenario _context do
    # Cleanup code
    :ok
  end

  # Step hooks bracket every step; after_step sees the step's status
  after_step context do
    log_step(context.step, context.step_status)
    :ok
  end
end

Run-level hooks

before_all hooks run lazily, exactly once per run, before the first scenario that executes (serialized through Cucumber.RunCoordinator, so this is safe with @async features). Their accumulated context map is merged into every scenario's context. If a before_all hook fails, the remaining before_all hooks still run (to set up as much as possible for cleanup), but every scenario in the run fails with the original error.

after_all hooks run once after the whole suite via ExUnit.after_suite/1, in reverse definition order, receiving the before_all context plus the ExUnit suite summary under :suite_result. A failing after_all hook fails the run; the remaining after_all hooks still run.

Run-level hooks cannot be tagged (they don't belong to any scenario).

One hook per kind — unless named

A module may define only one global and one per-tag hook of each kind; giving hooks a name: lifts that restriction, so a module can define any number of distinctly-named hooks of the same kind.