# Flow tests, CI commands and deploying flows

Target: Spring '26 (API 66.0). Sources: [`sf flow run test`](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_flow_run_test.html), [`sf logic run test`](https://developer.salesforce.com/docs/platform/salesforce-cli-reference/guide/cli_reference_logic_run_test.html), [Deploy Processes and Flows as Active](https://help.salesforce.com/s/articleView?id=platform.flow_distribute_deploy_active.htm&type=5), [Code Analyzer Flow Scanner](https://developer.salesforce.com/docs/platform/salesforce-code-analyzer/guide/engine-flow.html).

## 1. What a Flow Test is and what it cannot do

A Flow Test is metadata (`FlowTest`) created **in Flow Builder** — *View Tests* on the flow, or *Convert to Test* from a debug run. Each test sets the triggering record's initial (and for update tests, prior) field values and asserts on element outcomes.

Scope and limits:

| | |
|---|---|
| Supported | Record-triggered flows (before-save and after-save), including their **scheduled paths**; Data Cloud–triggered flows |
| Not supported | **Delete-triggered flows**, **asynchronous paths**, screen flows, autolaunched flows invoked from Apex, flows with callouts or Wait elements |
| Cap | 200 tests per flow |
| Runs as | The user who runs the test — assertions about sharing need a different user, so they belong in Apex |

Everything in the "not supported" row is covered by Apex tests that insert/update/delete the object (see `apex-testing`). State this gap explicitly in the deliverable; a flow with green Flow Tests and an untested delete path is the common production surprise.

## 2. CI commands

```bash
# Flow tests only, one flow, synchronously, with JUnit output for the build report
sf flow run test --target-org ci --class-names Order_After_Update \
  --synchronous --code-coverage --result-format junit --output-dir test-results

# All local flow tests
sf flow run test --target-org ci --test-level RunLocalTests \
  --result-format junit --output-dir test-results

# Poll an async run started earlier
sf flow get test --target-org ci --test-run-id <id> --result-format junit --output-dir test-results

# Apex and Flow in one run (Beta)
sf logic run test --target-org ci --test-level RunLocalTests \
  --code-coverage --result-format junit --output-dir test-results
```

Notes that break builds if missed:

- The command is `sf flow run test`. `sf flow test run` does not exist.
- `--class-names` takes **flow API names**; `--tests` takes `Flow.TestName` pairs and needs `--test-level RunSpecifiedTests`.
- `--synchronous` runs the tests of **one** flow synchronously; for a whole-org run, go async and poll with `sf flow get test`.
- Both commands require the **View All Data** system permission on the running user — give the CI integration user a permission set that grants it, or the step fails with an authorisation error rather than a test failure.
- `--suite-names` and `--detailed-coverage` are accepted by the parser but are not available for flow tests.

## 3. Static analysis

```bash
sf code-analyzer run --workspace force-app --rule-selector flow \
  --severity-threshold 3 --output-file flow-findings.csv
```

`flow` is the Flow Scanner engine's short name in Code Analyzer v5 (`sf code-analyzer rules --rule-selector flow --view detail` lists its rules). It finds DML and Get elements inside loops, missing fault paths, hard-coded Ids, and flows running in system context without sharing. Run it on every pull request that touches `**/flows/*.flow-meta.xml`; `--severity-threshold 3` makes moderate findings fail the job.

## 4. Deploying flows

- **Active on deploy.** Setup → Process Automation Settings → *Deploy processes and flows as active*. With it on, the deployment's flow version becomes active in the target org; with it off, every deployed flow lands as a new inactive version that somebody must activate by hand.
- **Coverage gate.** With that setting on, the org enforces a **flow test coverage percentage** (75 % by default, configurable in the same Setup page) across active autolaunched flows and processes, measured by Apex tests that cause them to run. Screen flows are exempt. `FlowTestCoverage` in the Tooling API shows which flows are covered:

  ```sql
  SELECT FlowVersionId, ApexTestClassId FROM FlowTestCoverage
  ```

  A flow with no Apex test touching its object fails the production deployment even when its Flow Tests pass.
- **Version hygiene.** `sf project deploy start` deploys the flow definition; old versions accumulate in the org and do not come back down with a retrieve unless asked for. Delete obsolete versions from Flow Builder (or with a destructive change on `Flow` named `MyFlow-3`) before the count becomes unreadable in Flow Trigger Explorer.
- **Ordering with the rest of the release.** Flows that reference new fields, invocable Apex or permission sets must deploy in the same request as those components — a single `sf project deploy start` on the whole package, not a sequence of partial deploys.
- **Validate first.** `sf project deploy validate --test-level RunLocalTests` against production gives a quick-deploy job id; the release then promotes it with `sf project deploy quick --job-id <id>` in the window. See `salesforce-devops`.

## 5. What to hand back

For every flow in the change:

```
Flow: Order_After_Update (after save, update, order 20)
Flow Tests: 3 (approved path, already-approved no-op, missing config → Custom Error)
Apex cover: OrderFlowTest.bulk200_approve (also provides the deploy coverage)
Gaps: delete path — covered by OrderFlowTest.delete_cancelsShipments
CI: sf flow run test --class-names Order_After_Update --synchronous …
```
