Debugging

Debugging behave tests is mostly a matter of narrowing the run down to one scenario and then inspecting state at the right moment. Because scenarios are plain Python code under the hood, the usual Python debugging tools work, plus a few behave-specific options that make the iteration loop faster.

Narrowing the Run

Run only the scenario you care about instead of the whole suite. Filter by exact name, by regex, or by tag:

behave -n "Withdraw money" features/          # exact scenario name
behave -i "withdraw" features/                # name regex
behave -t @debug features/                    # dedicated debug tag

A practical trick is to give the scenario under test a temporary @debug tag in the feature file, so you can iterate with a short command and remove the tag when done.

Showing Step Source

behave -s -n "Withdraw money" features/

The -s / --show option prints the Python source line of each step definition as the run proceeds. That removes the guesswork of "which function did this step actually match?", especially in modules with many similar patterns.

Dry Run for Step Matching

If a step reports "undefined" even though you believe a definition exists, use a dry run: behave loads all step definitions and reports which steps match, without executing anything. Compare the reported patterns with your feature text for typos, whitespace, or a stale import.

behave -D -n "Withdraw money" features/

pdb Inside a Step

For state inspection, drop into the debugger right where the scenario misbehaves:

import pdb

@then("the balance is {amount} USD")
def step_impl(context, amount):
    pdb.set_trace()
    assert context.balance == int(amount)

You can then inspect context (everything previous steps stored), the captured arguments, and the application objects. Remove the breakpoint before committing.

Printing Context

When a debugger is overkill, print the relevant state with a clear label and check the output with --no-capture so behave does not swallow print output outside of failures:

behave --no-capture -n "Withdraw money" features/

Summary

Shrink the run with name, regex, or tag filters, use -s to see which code each step executes, verify matching with -D, and step through state with pdb.set_trace() or --no-capture prints.