Setup Table

A setup table is a Gherkin table that a step uses to initialize state in bulk. Instead of writing one step per record, the scenario lists the data in rows and the step definition iterates over context.table to create all of it at once. This keeps feature files compact and mirrors how testers think: "given this dataset...".

The Feature File

Scenario: Seeding the demo database
  Given the users are:
    | name  | role     | balance |
    | alice | admin    | 100     |
    | bob   | customer | 25      |
    | carol | customer | 60      |
  When alice pays 10 to bob
  Then the balances are correct

Consuming the Table

Each row is accessible as a dictionary keyed by the header names. That is the cleanest way to consume a table:

from behave import given, when, then

@given("the users are:")
def step_impl(context):
    context.users = {
        row["name"]: {
            "role": row["role"],
            "balance": int(row["balance"]),
        }
        for row in context.table
    }

@when("alice pays {amount} to {target}")
def step_impl(context, amount, target):
    amount = int(amount)
    context.users["alice"]["balance"] -= amount
    context.users[target]["balance"] += amount

@then("the balances are correct")
def step_impl(context):
    assert context.users["alice"]["balance"] == 90
    assert context.users["bob"]["balance"] == 35

Other Access Patterns

If you need the raw structure, context.table also exposes headings (the first row), rows (lists of cells), and cells (lists of columns). All cells are strings, so convert numeric or boolean columns while building your state, as in the example above.

When to Use Setup Tables

Use setup tables for reference data and fixtures: user lists, product catalogs, rate tables, permission matrices. If the data drives the scenario logic itself, a scenario outline with Examples tables is the better fit, because each row then becomes its own executable case.

Summary

Setup tables let one step seed many records from a Gherkin table. Read rows as dictionaries via the header names, convert cell types explicitly, and store the resulting objects on the context for later steps.