---
title: Introduction
description: Write readable Pest tests as executable behaviour specifications.
---

Pest Flow adds a small behaviour-driven vocabulary to ordinary Pest tests. Use it to group a capability into business rules, describe each rule with executable scenarios, and organize setup, actions, and expectations into steps.

~~~text
Feature
└── Rule
    └── Scenario
        ├── Given
        ├── When
        └── Then
~~~

Pest still discovers and runs each scenario as a normal test. You keep Pest's assertions, lifecycle hooks, test runner, and failure output. Pest Flow records features, rules, scenarios, steps, identifiers, source locations, execution statuses, durations, and captured exceptions for PHP code to inspect.

:::note[Current capabilities]
Pest Flow provides the DSL, an in-memory behaviour registry, an optional terminal report enabled with `pest --flow`, versioned JSON export with `pest --flow-json`, static living documentation with `pest --flow-report`, and feature, rule, and scenario tags that work with Pest's `--group` filter.
:::

## Choose a starting point

**[Quickstart](/pest-flow/quickstart)**

Install Pest Flow and get your first scenario running.

**[Walkthroughs](/pest-flow/walkthroughs)**

Build a complete feature test and inspect its registry data.

**[DSL reference](/pest-flow/api)**

Look up every DSL function, placement rule, and runtime behavior.

**[Registry reference](/pest-flow/registry)**

Explore the node types, identifiers, source locations, and timing.

## How a scenario reads

~~~php
feature('Checkout', function (): void {
    rule('Discounts reduce the order total', function (): void {
        scenario('Applies a fixed discount', function (): void {
            given('an order worth 120 dollars', function (): void {
                $this->subtotal = 120;
            });

            when('a discount of 12 dollars is applied', function (): void {
                $this->total = $this->subtotal - 12;
            });

            then('the total is 108 dollars', function (): void {
                expect($this->total)->toBe(108);
            });
        });
    });
});
~~~

Each step runs in order on the same Pest test context. The values set in `Given` are available in `When` and `Then`, and an ordinary Pest expectation determines whether the scenario passes.

## Learn in order

1. **Install and run a scenario**

    Follow the [quickstart](/pest-flow/quickstart) to add the package and run a Pest test.

2. **Walk through a complete example**

    The [first scenario walkthrough](/pest-flow/walkthroughs/first-scenario) explains the feature, rule, scenario, and step callbacks line by line.

3. **Look up the API**

    Use the [DSL reference](/pest-flow/api) for function behavior and [core concepts](/pest-flow/concepts) for how Pest Flow fits into Pest.

4. **Inspect discovered behavior**

    Follow the [registry walkthrough](/pest-flow/walkthroughs/inspect-registry) and the [registry reference](/pest-flow/registry).