Home / flow / flow-testing

flow-testing

Use when defining or reviewing test strategy for Salesforce Flow, including Flow Tests, debug runs, path coverage, test data, and explicit validation of fault paths and custom component behavior. Triggers: 'flow test tool', 'how do i test a flow', 'flow fault path testing', 'flow debug interview'. NOT for Apex unit testing or manual QA planning that is unrelated to Flow behavior — use flow/flow-debugging. Also covers: FlowTest metadata, flowtest-meta.xml, testPoints, Flow.Interview, sf flow run test, flow coverage.

• v2.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• Operational Excellence

• flow-testing
• flow-tests
• path-coverage
• debug-interview
• test-data

Open the skill folder on GitHub

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.

What FlowTest reaches, in the guide's own words. "Before you activate a record-triggered, autolaunched, or Data Cloud-triggered flow, you can test it to verify its expected results and identify flow run-time failures" (api_meta.txt L73961–73962). Screen, scheduled-only and platform-event-triggered flows are absent from that list, and there is no other declarative flow-test surface — see Gotcha 7. Components carry the .flowtest suffix, live in the flowtests folder, and exist from API version 55.0 (L73976–73980). The testType field (FlowTestType) is required from API version 66.0 and has one value, WithAssertion — "the automated comparison of the actual flow outcome with the user-defined expected outcome that assertions define" (L74042–74051). Run them with sf flow run test, the command the flowtesting namespace page names (apexrefguide.txt L158183–158187); see devops/github-actions-for-salesforce. UNVERIFIED (2026-09-05): the mapping from API version 66.0 to a named seasonal release, and the claim that FlowTest was record-triggered-only before it, are not stated in any corpus file — the guides give API version gates per field and nothing else.

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 Draft or Active, and in which org? FlowTest is positioned as a pre-activation check (api_meta.txt L73961), so a flow already Active in production is being tested after the fact, not before.

Questions to Ask Before Configuring

What a proper configuration adds over just doing it: a test suite shaped by these answers proves the branch a change touched, in the version that actually runs, for the user who actually runs it — where a suite written without them proves that one happy path once worked for an admin.

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 — start from templates/apex/tests/TestDataFactory.cls, do not fork it. A FlowTest points at that class through flowTestDataSources, whose dataSourceType has one value, ApexClass, from API version 66.0 (api_meta.txt L74070–74090). Pair it with isolatedObjectExternalKeys, which names the fields that identify unique records in the isolated test data and explicitly excludes lookup fields (L74092–74128).

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

1. Inventory the gap before designing anything. Run

   python3 skills/flow/flow-testing/scripts/check_flow_testing.py --manifest-dir force-app/main/default. It reports Active flows with no FlowTest naming them, tests whose flowApiName resolves to no flow in the tree, tests with a Start point and no Finish assertions, test points with zero assertions, update-triggered tests missing the initial record image, and Apex classes touching Flow.Interview with no assertion. That output is the worklist; the path matrix below fills the gaps it names.

2. Classify by flow type, then build the path matrix. Answer the first question in the

   table above. Record-triggered, autolaunched and Data Cloud-triggered flows get FlowTest components; autolaunched flows may also get an Apex driver; everything else gets Jest plus a scripted manual pass. Then list the outcomes each branch must produce and the variable or field that proves it.

3. Author the FlowTest pair from references/metadata-examples.md. §2 is the

   happy-path shape — two test points, assertions on both Start and Finish, both record images for an update trigger, a HasError assertion proving the fault route stayed quiet. §3 is the negative path at the boundary value. One condition per assertion, each with an errorMessage naming the suspect element.

4. Cover what FlowTest structurally cannot reach, in Apex. §5 of the same file drives

   an autolaunched flow through Flow.Interview with input variables, asserts getVariableValue and then queries the record. Use it for bulk behaviour, user context via System.runAs, mocked callouts, and any flow type FlowTest does not list.

5. Deploy in the order in references/metadata-examples.md and run both suites. Objects,

   then flows as Draft, then flowtests, then Apex — Flow.Interview.<FlowApiName> will not compile before the flow exists. Then sf flow run test and sf apex run test --class-names <YourFlowTestClass>.

6. Read elementsNotCovered from the deploy result, not a percentage. Walk the list

   per element and classify each as a real gap or a structurally unreachable route, as in references/examples.md Example 3. Record the accepted ones with their reason.

7. Re-run the checker and record what remains. Fill in

   templates/flow-testing-template.md with the residual gaps and why each is accepted.

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. Admin-context testing hides user-context failures — System.runAs plus a with sharing launching class on API version 62.0 or later is what makes an Apex-driven flow honour the running user's sharing (apexrefguide.txt L157958–157963). UNVERIFIED (2026-09-05): the corpus states nothing about which user context a FlowTest component executes in.
7. There is no FlowTest for a screen flow at all — the type covers record-triggered, autolaunched and Data Cloud-triggered flows only (api_meta.txt L73961–73962). Jest plus a scripted manual pass is the whole story there.
8. A FlowTest exercises one interview — the Start point takes a single $Record image per parameter type (api_meta.txt L74296–74320), so nothing about bulk behaviour is proven. Use an Apex test that inserts a realistic batch. UNVERIFIED (2026-09-05): the often-quoted "200 interviews per 200-record DML" ratio is not stated in api_meta.txt or apexdev.txt.
9. Nothing inside a flow test is mocked — isUseMockOuput is documented as "Reserved for future use" (api_meta.txt L74152), so an Apex action, External Services callout or email alert fires for real when the test runs.
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

Reference Files

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.
• flow/flow-governance — owns the release rule ("FlowTest present before Active") and Flow.settings; this skill only produces the tests that rule asks for.
• flow/record-triggered-flow-patterns — owns triggerType / recordTriggerType selection and the guide's narrower availability wording; read it before arguing about which trigger type a test should target.
• flow/flow-interview-debugging — owns the debug-log side: which Workflow-category events exist and at which level they appear.
• apex/test-data-factory-patterns — how to extend templates/apex/tests/TestDataFactory.cls for custom objects without forking it.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/flow-testing-template.md
• scripts/check_flow_testing.py