Commands
Specification Commands

Specification Commands

Commands for creating and managing Gherkin feature files.

Overview

Use specification commands when you need to:

  • Create new feature files with proper Gherkin structure
  • Add, edit, or delete scenarios and steps
  • Add background stories and architecture notes
  • Validate Gherkin syntax using official Cucumber parser
  • Format feature files for consistency
  • List and show features with filtering by tags
  • Bulk operations on features and scenarios
  • Link scenarios to tests and implementation (coverage tracking)

Features

Create Feature

Create a new feature file with proper Gherkin structure.

fspec create-feature <name>

Examples:

fspec create-feature "User Authentication"

List Features

List all feature files with optional tag filtering.

fspec list-features [--tag=<tag>]

Examples:

fspec list-features
fspec list-features --tag=@phase1

Show Feature

Show detailed information about a specific feature.

fspec show-feature <name> [options]

Options:

  • --format <format> - Output format: text or json
  • --output <file> - Write output to file

Examples:

fspec show-feature user-authentication
fspec show-feature login --format=json

Delete Features by Tag

Delete multiple features matching a specific tag (useful for cleanup).

fspec delete-features-by-tag --tag=<tag> [--dry-run]

Options:

  • --tag=<tag> - Tag to match (required)
  • --dry-run - Preview deletion without actually deleting

Examples:

fspec delete-features-by-tag --tag=@deprecated --dry-run
fspec delete-features-by-tag --tag=@wip

Scenarios

Add Scenario

Add a new scenario to an existing feature.

fspec add-scenario <feature> <title>

Examples:

fspec add-scenario login "Login with valid credentials"

Update Scenario

Update an existing scenario's name.

fspec update-scenario <feature> <old-title> <new-title>

Examples:

fspec update-scenario login "Old Name" "New Name"

Delete Scenario

Delete a scenario from a feature.

fspec delete-scenario <feature> <title>

Examples:

fspec delete-scenario login "Deprecated scenario"

Query Scenarios

Query scenarios across all features using tags.

fspec get-scenarios [--tag=<tag>] [--format=<format>]

Options:

  • --tag=<tag> - Filter by tag (can specify multiple times for AND logic)
  • --format=<format> - Output format: text or json

Examples:

fspec get-scenarios --tag=@phase1 --tag=@critical
fspec get-scenarios --format=json

Show Acceptance Criteria

Show acceptance criteria from scenarios with tag filtering.

fspec show-acceptance-criteria [options]

Options:

  • --tag=<tag> - Filter by tag
  • --format=<format> - Output format: text, markdown, or json
  • --output=<file> - Write output to file

Examples:

fspec show-acceptance-criteria --tag=@phase1 --format=markdown
fspec show-acceptance-criteria --output=criteria.md

Delete Scenarios by Tag

Delete multiple scenarios matching a specific tag.

fspec delete-scenarios-by-tag --tag=<tag> [--dry-run]

Options:

  • --tag=<tag> - Tag to match
  • --dry-run - Preview deletion without actually deleting

Steps

Add Step

Add a step to an existing scenario.

fspec add-step <feature> <scenario> <keyword> <text>

Keywords: given, when, then, and, but

Examples:

fspec add-step login "Valid login" given "I am on the login page"
fspec add-step login "Valid login" when "I enter valid credentials"
fspec add-step login "Valid login" then "I should be logged in"

Update Step

Update an existing step's text or keyword.

fspec update-step <feature> <scenario> <old-text> [options]

Options:

  • --text <new-text> - New step text
  • --keyword <keyword> - New keyword (Given/When/Then/And/But)

Examples:

fspec update-step login "Valid" "old step" --text "new step"
fspec update-step login "Valid" "a step" --keyword when

Delete Step

Delete a step from a scenario.

fspec delete-step <feature> <scenario> <text>

Examples:

fspec delete-step login "Valid login" "I am on the login page"

Content

Add Background

Add or update the background user story for a feature.

fspec add-background <feature> <text>

Examples:

fspec add-background login "As a user\nI want to log in\nSo that I can access my account"

Add Architecture Notes

Add architecture notes to a feature (using doc string syntax).

fspec add-architecture <feature> <text>

Examples:

fspec add-architecture login "Uses JWT tokens for session management. Integrates with Auth0 for OAuth."

Validation & Formatting

Validate

Validate Gherkin syntax using the official @cucumber/gherkin-parser.

fspec validate [file] [--verbose]

Options:

  • --verbose - Show detailed validation output

Examples:

fspec validate                              # Validate all .feature files
fspec validate spec/features/login.feature  # Validate specific file
fspec validate --verbose

Format

Format feature files using fspec's custom AST-based formatter.

fspec format [file]

Examples:

fspec format                                # Format all .feature files
fspec format spec/features/login.feature    # Format specific file

Check

Run all validation checks (syntax + tags + formatting).

fspec check [--verbose]

Options:

  • --verbose - Show detailed output

Examples:

fspec check
fspec check --verbose

Validate Tags

Validate that all tags in feature files are registered in the tag registry.

fspec validate-tags

Examples:

fspec validate-tags

Coverage Tracking

Link scenarios to test files and implementation code for traceability.

Link Coverage

Link test files and implementation to scenarios.

fspec link-coverage <feature> --scenario <name> [options]

Options:

  • --test-file <path> - Test file path (e.g., src/tests/auth.test.ts)
  • --test-lines <range> - Test line range (e.g., "45-62")
  • --impl-file <path> - Implementation file path
  • --impl-lines <lines> - Implementation lines (e.g., "10,11,12,23")
  • --skip-validation - Skip file validation (useful for reverse ACDD)

Examples:

# Link test to scenario
fspec link-coverage user-auth --scenario "Login" \
  --test-file src/__tests__/auth.test.ts --test-lines 45-62
 
# Link implementation to test
fspec link-coverage user-auth --scenario "Login" \
  --test-file src/__tests__/auth.test.ts \
  --impl-file src/auth/login.ts --impl-lines 10,11,12,23
 
# Link both at once
fspec link-coverage user-auth --scenario "Login" \
  --test-file src/__tests__/auth.test.ts --test-lines 45-62 \
  --impl-file src/auth/login.ts --impl-lines 10-24

Show Coverage

Show coverage report for a feature or entire project.

fspec show-coverage [feature] [options]

Options:

  • --format <format> - Output format: text or json
  • --output <file> - Write output to file

Examples:

fspec show-coverage user-authentication    # Feature-specific
fspec show-coverage                        # Project-wide
fspec show-coverage --format=json

Audit Coverage

Verify that all file paths in coverage mappings actually exist.

fspec audit-coverage <feature> [--fix]

Options:

  • --fix - Remove broken mappings automatically

Examples:

fspec audit-coverage user-authentication
fspec audit-coverage user-authentication --fix

Unlink Coverage

Remove coverage mappings from a scenario.

fspec unlink-coverage <feature> [options]

Options:

  • --scenario <name> - Scenario to unlink
  • --test-file <path> - Test file to remove
  • --impl-file <path> - Implementation file to remove
  • --all - Remove all mappings

Examples:

# Remove all mappings for a scenario
fspec unlink-coverage user-auth --scenario "Login" --all
 
# Remove specific test mapping
fspec unlink-coverage user-auth --scenario "Login" --test-file src/__tests__/auth.test.ts
 
# Remove specific implementation mapping
fspec unlink-coverage user-auth --scenario "Login" \
  --test-file src/__tests__/auth.test.ts \
  --impl-file src/auth/login.ts

Generate Coverage

Generate .coverage files for existing features (useful for setup or recovery).

fspec generate-coverage [--dry-run]

Options:

  • --dry-run - Preview what would be created without actually creating files

Examples:

fspec generate-coverage --dry-run
fspec generate-coverage

Tag Management

Manage tags at feature and scenario levels.

Add Tag to Feature

Add a tag to a feature file.

fspec add-tag-to-feature <file> <tag> [--validate-registry]

Options:

  • --validate-registry - Check that tag exists in registry

Examples:

fspec add-tag-to-feature spec/features/login.feature @critical
fspec add-tag-to-feature login.feature @phase2 --validate-registry

Remove Tag from Feature

Remove a tag from a feature file.

fspec remove-tag-from-feature <file> <tag>

Examples:

fspec remove-tag-from-feature spec/features/login.feature @wip

List Feature Tags

List all tags for a feature file.

fspec list-feature-tags <file> [--show-categories]

Options:

  • --show-categories - Show tag categories from registry

Examples:

fspec list-feature-tags login.feature
fspec list-feature-tags login.feature --show-categories

Add Tag to Scenario

Add a tag to a specific scenario.

fspec add-tag-to-scenario <file> <scenario> <tag>

Examples:

fspec add-tag-to-scenario login.feature "Valid login" @smoke

Remove Tag from Scenario

Remove a tag from a specific scenario.

fspec remove-tag-from-scenario <file> <scenario> <tag>

List Scenario Tags

List all tags for a specific scenario.

fspec list-scenario-tags <file> <scenario>

See Also

Example MappingWork Management