Tag Filtering

Tags help you organize and selectively run your BDD tests. Mark features and scenarios with tags, then filter by them during execution.

Tag Syntax

Adding Tags

Use @ prefix to add tags in Gherkin:

@authentication @smoke
Feature: User Login

  @critical @fast
  Scenario: Valid credentials
    Given a user exists
    When I login with valid credentials
    Then I should be logged in

  @slow @integration
  Scenario: Remember me
    Given a user exists
    When I login with remember me checked
    Then I should stay logged in for 30 days

Tag Inheritance

Feature-level tags apply to all scenarios:

@api
Feature: User API

  @create
  Scenario: Create user     # Has @api and @create

  @read
  Scenario: Get user        # Has @api and @read

  @delete
  Scenario: Delete user     # Has @api and @delete

Running with Tags

Basic Tag Filtering

# Run only @smoke scenarios
pest --bdd --tags="@smoke"

# Run @critical scenarios
pest --bdd --tags="@critical"

Tag Expressions

Use logical operators for complex filtering:

# AND: Must have both tags
pest --bdd --tags="@smoke and @fast"

# OR: Must have either tag
pest --bdd --tags="@smoke or @regression"

# NOT: Exclude tag
pest --bdd --tags="not @slow"

# Complex expressions
pest --bdd --tags="(@smoke or @critical) and not @wip"

Operator Precedence

1. Parentheses ()
2. not
3. and
4. or

# These are different:
pest --bdd --tags="@a or @b and @c"      # @a or (@b and @c)
pest --bdd --tags="(@a or @b) and @c"    # (@a or @b) and @c

Programmatic Filtering

In PestFeatureLoader

use TestFlowLabs\PestBdd\PestFeatureLoader;

$loader = PestFeatureLoader::create();

// Include only specific tags
$loader->includeTags(['smoke', 'critical']);

// Exclude specific tags
$loader->excludeTags(['wip', 'skip']);

// Or use tag expression
$loader->setTagExpression('@smoke and not @slow');

$loader->load(__DIR__.'/features/');

Precedence

Tag expression takes precedence over include/exclude:

$loader->includeTags(['smoke']);           // Ignored
$loader->excludeTags(['slow']);            // Ignored
$loader->setTagExpression('@critical');    // This is used

Common Tag Patterns

By Test Speed

@fast
Scenario: Quick validation
  ...

@slow
Scenario: Full integration test
  ...

# Fast feedback during development
pest --bdd --tags="@fast"

# Full suite in CI
pest --bdd --tags="not @slow"

By Priority

@critical
Scenario: User can purchase
  ...

@high
Scenario: User can add to cart
  ...

@low
Scenario: User can change theme
  ...

# Run critical tests first
pest --bdd --tags="@critical"

# Run critical and high priority
pest --bdd --tags="@critical or @high"

By Test Type

@smoke
Scenario: Basic functionality works
  ...

@regression
Scenario: Bug fix verification
  ...

@e2e
Scenario: Complete user journey
  ...

# Smoke tests for quick verification
pest --bdd --tags="@smoke"

# Full regression suite
pest --bdd --tags="@regression"

By Work Status

@wip
Scenario: Work in progress
  ...

@skip
Scenario: Temporarily disabled
  ...

@flaky
Scenario: Sometimes fails
  ...

# Exclude incomplete work
pest --bdd --tags="not @wip and not @skip"

# Run only stable tests
pest --bdd --tags="not @flaky"

By Feature Area

@authentication
Feature: Login
  ...

@payments
Feature: Checkout
  ...

@notifications
Feature: Email Alerts
  ...

# Test specific area
pest --bdd --tags="@authentication"

# Test multiple areas
pest --bdd --tags="@payments or @notifications"

Tags on Scenario Outlines

Tag the Entire Outline

@smoke
Scenario Outline: Basic math
  Given I have <a>
  When I add <b>
  Then I get <result>

  Examples:
    | a | b | result |
    | 1 | 2 | 3      |
    | 2 | 3 | 5      |

All examples inherit @smoke.

Tag Specific Examples

Scenario Outline: Payment processing
  Given I pay with <method>
  When I checkout
  Then payment should <status>

  @fast @unit
  Examples: Quick payments
    | method      | status  |
    | credit_card | succeed |
    | debit_card  | succeed |

  @slow @integration
  Examples: External providers
    | method | status  |
    | paypal | succeed |
    | stripe | succeed |

# Run only fast payment tests
pest --bdd --tags="@fast"

Best Practices

Use Descriptive Tags

# Good: Clear purpose
@authentication @smoke @P1
Scenario: User login

# Avoid: Unclear abbreviations
@auth @s @1
Scenario: User login

Consistent Tag Naming

Create a team convention:

Category	Tags
Priority	@P1, @P2, @P3 or @critical, @high, @low
Speed	@fast, @slow
Type	@smoke, @regression, @e2e
Status	@wip, @skip, @flaky
Area	@authentication, @payments, @api

Don't Over-Tag

# Good: Relevant tags
@authentication @smoke
Scenario: Login works

# Avoid: Too many tags
@authentication @user @login @smoke @fast @P1 @sprint-42 @JIRA-123
Scenario: Login works

Document Your Tags

Create a reference for your team:

# Tag Reference

## Priority Tags
- `@P1` - Critical path, must pass before release
- `@P2` - Important, should pass before release
- `@P3` - Nice to have, can be fixed later

## Speed Tags
- `@fast` - Under 1 second
- `@slow` - Over 5 seconds

## Status Tags
- `@wip` - Work in progress, expected to fail
- `@skip` - Temporarily disabled

Complete Example

@e-commerce @api
Feature: Shopping Cart API
  As an API consumer
  I want to manage shopping carts
  So that I can build e-commerce integrations

  Background:
    Given I am authenticated with API key

  @smoke @fast @P1
  Scenario: Create empty cart
    When I POST to "/api/carts"
    Then I should receive status 201
    And I should receive a cart ID

  @smoke @fast @P1
  Scenario: Add item to cart
    Given I have a cart
    When I POST to "/api/carts/{id}/items" with:
      | product_id | 123 |
      | quantity   | 2   |
    Then I should receive status 200
    And the cart should have 2 items

  @regression @slow
  Scenario: Cart persists across sessions
    Given I have a cart with items
    When I wait 30 minutes
    And I request the cart
    Then the items should still be there

  @wip
  Scenario: Apply discount code
    Given I have a cart with items
    When I apply discount code "SAVE10"
    Then the total should be reduced

  @P2 @validation
  Scenario Outline: Quantity validation
    Given I have a cart
    When I add <quantity> of product 123
    Then I should receive status <status>

    @fast
    Examples: Valid quantities
      | quantity | status |
      | 1        | 200    |
      | 99       | 200    |

    @fast
    Examples: Invalid quantities
      | quantity | status |
      | 0        | 400    |
      | -1       | 400    |
      | 100      | 400    |

Run commands:

# Smoke tests
pest --bdd --tags="@smoke"

# All P1 tests
pest --bdd --tags="@P1"

# Fast tests only, exclude WIP
pest --bdd --tags="@fast and not @wip"

# Full e-commerce suite
pest --bdd --tags="@e-commerce and not @wip"