Flow Testing

Use this skill when a Flow works in a demo but nobody can yet prove it is safe to change. Flow testing is not one tool — it is a test STRATEGY that combines declarative Flow Tests where they fit, focused debug runs for diagnosis, deliberate test data, and extra coverage at custom component or Apex boundaries when the Flow itself is not the whole system.

Unlike Apex, Flow does not have a forced test-coverage gate at deploy time. This makes flow testing strictly a discipline problem, not a tooling problem. Teams that rely on "I clicked through it once in sandbox" as their coverage story are one change away from a production incident with no regression safety net. This skill exists to make that discipline concrete.

FlowTest scope expansion (Spring '26, API 66.0+). Flow Tests are no longer record-triggered-only. The FlowTest metadata type documents testing record-triggered, autolaunched, and Data Cloud-triggered flows before activation. The testType field (FlowTestType, API 66.0+) supports WithAssertion — automated comparison of actual flow outcomes against user-defined expected outcomes. Wire CI with sf flow run test (see devops/github-actions-for-salesforce and apex/tooling-api-patterns).

Before Starting

Check for salesforce-context.md in the project root. If present, read it first.

Gather if not available:

• What business paths matter most: happy path, edge-case branches, validation failures, or external-action failures?
• Is the flow record-triggered, screen, scheduled, or auto-launched, and what test surface is appropriate for that type?
• Which parts of the behavior live outside the flow itself (Apex actions, custom LWC screen components, external integrations)?
• What test data does the org have? (Test Data Factory Apex class? Sample records in a scratch org?)
• Is the Flow deployed to sandbox or prod? (Flow Tests work differently in each.)

Core Concepts

Good Flow testing starts with path thinking, not with clicking Debug first. The goal is to prove that the flow behaves correctly when inputs, branching, and failures vary. A happy-path-only test tells you almost nothing about how safe the automation really is in production.

Flow Tests Need A Path Matrix

For any meaningful flow, start by listing the business outcomes that must be proven. That usually includes the main success path, one or more decision branches, and at least one failure or rejection path. The matrix drives your test data and tells you where declarative Flow Tests, Apex tests, or manual screen validation each belong.

Example path matrix for a record-triggered flow on Case:

Debug Runs Are Diagnostic, Not Coverage

Debug mode is useful to inspect runtime behavior and investigate failures, but it is NOT the same as having repeatable automated coverage. Use debug runs to understand why something failed, then turn that understanding into a repeatable test asset where possible.

Debug run is the right tool for:

• First-time exploration of a flow's behavior
• Investigating a specific failure from Flow Interview Log
• Verifying a quick change didn't break the happy path
• Demoing the flow to a stakeholder

Debug run is NOT sufficient for:

• Production deploy readiness
• Regression safety on subsequent changes
• Bulk-safety verification
• Branch-coverage proof

Custom Boundaries Need Their Own Tests

If the flow calls invocable Apex, depends on a custom LWC screen component, or hands off work to other automation, the Flow Test alone may not be enough. The flow should still be tested at the orchestration level, but the custom component or Apex boundary also needs focused tests at its own layer.

Fault Paths Must Be Intentional Test Cases

Testing only the success path leaves the most operationally important behavior unproven. Validation-rule errors, missing data, duplicate-rule failures, or external action failures should be part of the test plan when they are realistic outcomes.

A Flow Test's "expected fault" assertion:

• Configure inputs that WILL trigger a known failure (e.g. missing required field).
• Assert that the fault path fires (an assignment, a log creation, a notification).
• Verify the user-safe message doesn't contain raw $Flow.FaultMessage.
• Verify the error log captures the diagnostic detail.

Common Patterns

Pattern 1: Path Matrix Before Test Authoring

When to use: Any flow with more than one meaningful branch or outcome.

Structure: Build the matrix (as above) in a doc or spreadsheet. For each row:

1. Define the exact input shape (record field values, user context).
2. Define the expected path through the flow.
3. Define the expected outcome (assertions).
4. Tag the test type (Flow Test, Apex test, manual UI verify).

Authoring tests without the matrix usually produces one happy-path Flow Test and calls it done. The matrix forces coverage thinking first.

Pattern 2: Pair Flow Tests With Boundary Tests

When to use: The flow interacts with Apex, custom screen LWCs, or external systems.

Structure:

Flow Test (declarative):
  - Prove orchestration: flow runs, calls the boundary, receives expected return.

Apex @IsTest (for invocable Apex):
  - Prove boundary: given the same input the flow sends, produces the correct output.
  - Cover bulk signatures (List<T>, not single instances).

Jest test (for custom LWC):
  - Prove component: @api validate() returns correct isValid for sample inputs.
  - Prove dispatched events (FlowAttributeChangeEvent) fire with correct payload.

Neither layer alone is enough. Combined, they give confidence.

Pattern 3: Explicit Fault-Path Test Cases

When to use: The flow can fail because of business validation, duplicate detection, or integration issues.

Structure: For every fault-route in the flow (per flow/fault-handling Patterns A/B/C/D), have at least one Flow Test that triggers the fault and asserts the route fires.

Flow Test: "Fault path fires when DML validation blocks Update"
  Input: Case with field value that violates Validation Rule
  Expected assertions:
    - Flow reaches the fault branch
    - Application_Log__c record is created
    - User-safe message contains friendly copy
    - Raw $Flow.FaultMessage does NOT appear in user-visible output

Pattern 4: Test Data Factory For Repeatable Setup

When to use: Flows that depend on complex data setups (multi-object relationships, specific role hierarchies, picklist values).

Structure: An Apex @IsTest TestDataFactory class creates the needed records. Flow Tests use "Run Flow Debug" with the records fabricated via this factory (or via Connect Test Setup in sandbox).

Alternative: a scratch-org seed script (SFDX tree export/import) that loads a canonical test dataset. Repeatable + CI-friendly.

Decision Guidance

Review Checklist

• A path matrix exists for success, branch, and failure scenarios.
• Test data is explicit and not dependent on existing org state.
• Fault-path behavior is covered where realistic failures exist.
• Custom screen components or Apex actions have tests at their own boundary.
• Debug runs are used to learn, not mistaken for repeatable coverage.
• The chosen test assets align with the flow type and production risk.
• Bulk behavior tested via Apex @IsTest if the flow fires on high-volume objects.
• Test-data factory or scratch-org seed script exists for the org's common test setups.

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner activating this skill:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Common Patterns above; build the path matrix first
4. Validate — run the skill's checker script and verify against the Review Checklist above
5. Document — record any deviations from standard patterns and update the template if needed

Salesforce-Specific Gotchas

1. Debug success is not regression coverage — a one-time manual run does not protect future changes.
2. Custom LWC screen components widen the test surface — the Flow test and the component validation contract both matter.
3. Fault handling needs its own test data — failures rarely prove themselves unless data is arranged to trigger them intentionally.
4. A flow can be correct while its boundary dependency is wrong — orchestration coverage does not replace Apex or component tests.
5. Flow Tests do NOT enforce coverage at deploy time — unlike Apex. A flow can be deployed to production with zero tests. This is a discipline problem, not a tool problem.
6. Flow Tests run with the current user's permissions — tests may pass in a System Admin's context but fail for the actual users. Test with runAs() equivalents or multiple user contexts.
7. Screen flow tests can't fully automate custom LWC interaction — manual steps inevitable for some scenarios; Jest fills the LWC gap.
8. Record-triggered flow tests don't inherently cover bulk — a 200-record Bulk API insert triggers 200 interviews; Flow Tests run one interview. Use Apex for bulk coverage.
9. Mocking external callouts in Flow Tests is harder than in Apex — External Services callouts typically require Apex test setup.
10. Test failures in Flow are harder to debug than Apex — less tooling, less stack trace detail. Prefer clear test names and narrow scope per test.

Proactive Triggers

Surface these WITHOUT being asked:

• Flow deployed to production with zero Flow Tests → Flag as Critical. Must have at least happy-path + one fault-path test.
• Happy path covered, no fault tests → Flag as High. Failure behavior is where production incidents live.
• Boundary dependency (Apex/LWC/HTTP) not tested at its own layer → Flag as High. Orchestration coverage doesn't prove boundary correctness.
• Test data inherited from org state rather than fabricated → Flag as High. Tests break when the org changes.
• Debug run cited as "the tests" → Flag as Critical. Fundamental discipline gap.
• Flow on high-volume object without bulk test (Apex) → Flag as High. Bulk failure surfaces only in production.
• Fault paths exist but have no corresponding Flow Test → Flag as Medium. Specific, fixable gap.
• Custom LWC screen component with no Jest tests → Flag as Medium. Validation contract is unprovable.

Output Artifacts

Related Skills

• flow/fault-handling — alongside this skill when failure behavior needs redesign as well as test coverage.
• flow/screen-flows — when the test strategy depends on interactive runtime UX and custom screen components.
• flow/flow-bulkification — when bulk-test coverage is the gap.
• apex/trigger-framework — when the flow's boundary is Apex and trigger-framework tests cover that side.
• lwc/lwc-testing — companion skill for Jest tests on custom LWC screen components.