Auto-Fix

July 3, 2026 · View on GitHub

behave-lint can automatically fix certain rule violations in your .feature files.

Usage

# Apply safe fixes only
behave-lint features/ --fix

# Apply safe and unsafe fixes
behave-lint features/ --fix --unsafe-fixes

Safe vs. unsafe fixes

Category	Description
Safe	Deterministic transformations that cannot change test semantics. Applied with `--fix`.
Unsafe	Transformations that may change behavior or require human review. Only applied with `--unsafe-fixes`.

Rules with auto-fix support

Safe fixes

Rule	Fix
BC004 (invalid-tag-syntax)	Replace invalid characters in tags with `_`.
BD004 (step-parameter-convention)	Convert `{param}` to `<param>` when both conventions are mixed.
BD005 (step-trailing-punctuation)	Remove trailing punctuation from step text.
BS001 (tag-casing)	Convert tags to lowercase `snake_case`.
BS006 (step-keyword-casing)	Capitalize step keywords (e.g., `given` → `Given`).
BS007 (trailing-whitespace)	Remove trailing whitespace from lines.
BS008 (tab-indentation)	Replace tab indentation with spaces (2 per level).

Unsafe fixes

Rule	Fix
BS002 (keyword-ordering)	Reorder steps to Given → When → Then.
BS003 (step-phrasing)	Rewrite first-person steps to third-person.
BS004 (background-name)	Insert `Background: Common setup` as a placeholder name.
BS005 (feature-description)	Insert a template As a / I want / So that description.
BP001 (missing-scenario-tags)	Insert `@smoke` tag before scenarios without tags.
BP005 (missing-examples-name)	Append `Valid values` name to unnamed Examples sections.
BP006 (missing-feature-description)	Insert a template As a / I want / So that description after the Feature line.

Conflict resolution

When multiple fixes target overlapping lines in the same file, behave-lint applies only the first fix and skips conflicting ones. A warning is printed for each skipped fix.

Examples

Fix tag casing (BS001)

Before:

@SmokeTest
Feature: Login

After --fix:

@smoke_test
Feature: Login

Fix invalid tag syntax (BC004)

Before:

@smoke-test
Feature: Login

After --fix:

@smoke_test
Feature: Login

Fix trailing punctuation (BD005)

Before:

  Scenario: Login
    Given a user.
    When I click submit.

After --fix:

  Scenario: Login
    Given a user
    When I click submit

Fix mixed parameter convention (BD004)

Before:

  Scenario Outline: Test <value>
    Given a <value> with {count} items

After --fix:

  Scenario Outline: Test <value>
    Given a <value> with <count> items

Fix step keyword casing (BS006)

Before:

  Scenario: Login
    given a user
    when I click submit
    then I see the dashboard

After --fix:

  Scenario: Login
    Given a user
    When I click submit
    Then I see the dashboard

Fix trailing whitespace (BS007)

Before:

Feature: Login   
  Scenario: Test  
    Given a step

After --fix:

Feature: Login
  Scenario: Test
    Given a step

Fix tab indentation (BS008)

Before:

Feature: Login
	Scenario: Test
		Given a step

After --fix:

Feature: Login
  Scenario: Test
    Given a step

Fix missing scenario tags (BP001)

Before:

  Scenario: Login
    Given a user

After --fix --unsafe-fixes:

  @smoke
  Scenario: Login
    Given a user

Fix missing examples name (BP005)

Before:

    Examples:
      | role |
      | admin |

After --fix --unsafe-fixes:

    Examples: Valid values
      | role |
      | admin |

Fix missing feature description (BP006)

Before:

Feature: User Authentication

  Scenario: Login
    Given a user

After --fix --unsafe-fixes:

Feature: User Authentication
  As a [role]
  I want to [action]
  So that [benefit]

  Scenario: Login
    Given a user