Tags and filtering

Label behaviour nodes and filter scenarios with Pest groups.

Add tags to a feature, rule, or scenario with the fluent tags() method:

feature('Checkout', function (): void {
    rule('Payment', function (): void {
        scenario('charges a customer', function (): void {
            given('a saved payment method', function (): void {
                $this->payment = ['status' => 'ready'];
            });

            when('the charge is submitted', function (): void {
                $this->payment['status'] = 'charged';
            });

            then('the charge succeeds', function (): void {
                expect($this->payment['status'])->toBe('charged');
            });
        })->tags('payments', 'critical');
    })->tags('billing');
})->tags('checkout');

Tags are trimmed, kept in declaration order, and deduplicated on each node. Empty tags and commas are rejected. A feature’s or rule’s tags are inherited by its scenarios for filtering. Tags declared on a scenario apply only to that scenario.

Filter with Pest

Pest Flow maps tags to Pest groups. Use Pest’s normal group filter:

vendor/bin/pest --group=payments
vendor/bin/pest --group=billing
vendor/bin/pest --group=checkout

Each command selects scenarios with that tag, including tags inherited from their feature or rule. Pest’s --exclude-group option can exclude a tag in the same way.

Inspect tags in JSON

The versioned JSON report includes the tags declared directly on each feature, rule, and scenario:

{
  "features": [
    {
      "tags": ["checkout"],
      "rules": [
        {
          "tags": ["billing"],
          "scenarios": [
            { "tags": ["payments", "critical"] }
          ]
        }
      ]
    }
  ]
}

Parent tags are not copied into scenario tag arrays. See the JSON export reference for the full schema and DSL reference for declaration rules.