behave-lint

A fast, opinionated, extensible linter for Gherkin .feature files and Behave test suites.

behave-lint statically analyzes your Gherkin feature files for correctness, consistency, complexity, and style — without executing a single test. It ships with 50 built-in rules across 9 categories, supports auto-fix for 14 rules, and outputs in 5 formats including SARIF for GitHub Code Scanning. Includes watch mode for real-time feedback during development.

Why behave-lint?

Installation

pip install behave-lint

Or with uv:

uv add behave-lint

For watch mode, install the optional dependency:

pip install behave-lint[watch]

For LSP support (VS Code, Neovim, Emacs):

pip install behave-lint[lsp]

Quick start

# Lint all feature files
behave-lint features/

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

# Watch for changes and re-lint automatically
behave-lint features/ --watch

# JSON output for CI integration
behave-lint features/ --output json --output-file report.json

# SARIF for GitHub Code Scanning
behave-lint features/ --output sarif --output-file results.sarif

# List all available rules
behave-lint --list-rules

# Explain a specific rule
behave-lint --explain BC001

Features

• 50 built-in rules across 9 categories: correctness, step definitions, consistency, complexity, style, pedantic, security, i18n, and accessibility.
• Auto-fix — 14 rules with safe and unsafe fixes (--fix, --unsafe-fixes).
• Watch mode — re-lint on file changes with --watch (requires pip install behave-lint[watch]).
• LSP server — real-time diagnostics in VS Code, Neovim, Emacs (requires pip install behave-lint[lsp]).
• 5 output formats — console (colored), JSON, SARIF, Markdown, and GitHub Actions inline annotations.
• Zero-config — sensible defaults work out of the box. Override anything via [tool.behave-lint] in pyproject.toml.
• Plugin system — write custom rules and reporters as Python packages. Register via entry points.
• CI/CD ready — deterministic output, clear exit codes, SARIF integration with GitHub Code Scanning.
• Fast — sub-second on typical projects through caching and parallel execution.

Rules

Auto-fixable rules

See the Auto-Fix guide for the full list.

Configuration

Configure behave-lint in your pyproject.toml:

[tool.behave-lint]
select = ["BC001", "BC002", "BS001"]
ignore = ["BP001", "BP002"]
fail-on = "warning"
exclude = ["features/wip/"]

[tool.behave-lint.severity]
BK001 = "info"

[tool.behave-lint.rules]
BX001 = { max-steps = 8 }
BP003 = { min-length = 5 }

Precedence (lowest → highest):

1. Built-in defaults
2. pyproject.toml [tool.behave-lint]
3. Environment variables (BEHAVE_LINT_*)
4. CLI flags

See the Configuration guide for all options.

CI/CD integration

GitHub Actions with SARIF

- run: pip install behave-lint
- run: behave-lint features/ --sarif --output-file behave-lint.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: behave-lint.sarif

Inline annotations

- run: behave-lint features/ --output github

See the CI/CD guide for full workflows.

Output formats

See the Output Formats reference for schema details.

Examples

Runnable example projects in the examples/ directory:

Documentation

Full documentation is hosted at mathiaspaulenko.github.io/behave-lint.

User guide

• Installation
• Quick Start
• CLI Reference
• Configuration
• Output Formats
• Auto-Fix
• Watch Mode
• LSP Server

Rules

• Rules Overview
• Correctness (BC)
• Step Definitions (BD)
• Consistency (BK)
• Complexity (BX)
• Style (BS)
• Pedantic (BP)
• Security (BSEC)
• I18N (BI18N)
• Accessibility (BACC)

Guides

• CI/CD Integration
• Pre-commit Hook
• Custom Rules
• Plugin Development

Design documents

• Vision — project vision and mission
• Specification — full feature specification
• Architecture — internal architecture
• API — public API specification
• Rule Engine Design — rule lifecycle and execution
• Rule Taxonomy — rule categories and metadata
• Configuration System — configuration schema
• Implementation Roadmap — milestone plan

Development

git clone https://github.com/MathiasPaulenko/behave-lint.git
cd behave-lint
uv sync
uv run pre-commit install

# Run tests
uv run pytest

# Lint
uv run ruff check behave_lint/ tests/

# Type check
uv run mypy behave_lint/

# Build docs
uv run mkdocs build --strict

See CONTRIBUTING.md for detailed contribution guidelines, coding standards, and PR workflow.

License

MIT