Learning Tactus

Built-in Step Definitions

BDD only works if the assertions are easy to write.

Tactus ships with a library of built-in step definitions so your specs can focus on intent (policy and invariants) rather than “glue code”.

This chapter is a quick field guide to the steps you’ll use most often.

Tool Assertions

Tools are a natural audit surface for agent workflows. Common steps:

In practice, “should not be called” is one of your most valuable invariants.

Example:

Then the send_email tool should not be called
And the finalize_recap tool should be called

State and Stage Assertions

State is how you encode “what happened” in a durable workflow. Stages are how you make progress legible.

Useful steps include:

Example:

Then the state message_id should exist
And the stage should be complete

Output Assertions

Outputs are your contract with callers. Steps include:

Pattern matching is especially useful for “human-ish” text where exact matches are brittle.

Running the Procedure (When Steps)

Most specs follow the same shape:

Given the procedure has started
When the procedure runs
Then the procedure should complete successfully

If your workflow is agent-driven (multi-turn), you’ll also see:

When the {agent} agent takes turns

In both cases, Tactus executes the procedure as written; your spec is asserting what happened.

Setting Inputs in Scenarios

You can set procedure inputs in Gherkin:

Given the input recipient_name is "Sam"
And the input target_count is 3
When the procedure runs
Then the state counter should be 3

This is how you test different branches without creating separate files.

When to Write Custom Steps

Built-in steps cover a lot. Add custom steps only when:

Custom steps can be defined in Lua using step("...", function(...) ... end) inside your .tac file. Keep them deterministic and small—custom steps are test code, not workflow code.

How It Connects to the Running Example

In Part II, we already used built-in steps to assert things like:

In this part, we’ll use the same step library to make our safety and reliability policies executable.