# Flow fixtures (Phase 3 integration tests)

This directory holds the live metadata of the 19 legacy flows identified by the
Phase 0 business audit (see the Phase 1 migration script's `keepFlows` list in
`scripts/migrate-workflow-flows/main.go`).

## Files

`<DeveloperName>.flow.json` — the `Flow.Metadata` column as stored in the
`new-prod-essential` test database. The column is a raw JSON blob.
`flow_e2e_integration_test.go` parses each file into `models.FlowMetadata` and
runs structural + (optionally) runtime assertions against it.

These fixtures cover every engine path touched by the Phase 2 lanes:

| Flow | Exercises |
|------|-----------|
| `Order_Start_Date_End_Date` | `__r` lazy-load (`$Record.Order__r.Overall_Start_Date__c`) |
| `Order_Expiration_Notice_90` | Scheduled trigger + Wait + `actionType="flow"` subflow fan-out + formulas |
| `Order_Expiration_Alert_7/15/30/60/90` | Invocable callees (no `start`, called via `actionType="flow"`) |
| `Invoice_Notice` | RecordAfterSave + `actionType="flow"` subflow dispatch |
| `Collections`, `Collections_Cash_Collected`, `Collection_Partner_Name`, `Collections_Account_ID`, `Collections_Region_PingCAP_Contracting_Entity_Marketplace`, `Collections_Invoice_Status_marketplace` | RecordAfterSave + field updates w/ nested `__r` lookups |
| `Order_Account_Name`, `Order_Partner_Name`, `Order_PingCAP_RevRec_Entity` | `IsNull` branches + field updates |
| `Contract_PingCAP_Contracting_Entity`, `Account_PingCAP_Contracting_Entity` | RecordAfterSave on Contract / Account |

## Refreshing the fixtures

The flows live in the `new-prod-essential` test TiDB Cloud cluster. To re-dump:

```bash
TIDB_TEST_HOST=gateway01.us-east-1.prod.aws.tidbcloud.com \
TIDB_TEST_PORT=4000 \
TIDB_TEST_USER=4Qbn3F3nyaU9DLk.root \
TIDB_TEST_PASS=<password> \
TIDB_TEST_DB=nexuscrm \
bash scripts/dump-flow-fixtures/run.sh
```

The script is idempotent: it overwrites each `*.flow.json` with the latest
`Flow.Metadata` row (ordered by `VersionNumber DESC LIMIT 1`). Empty or NULL
metadata rows are skipped with a warning rather than overwriting with garbage.

## Why not commit expected-output JSONs?

Per the task failure-strategy note ("expected unknown → SkipNow + TODO"), the
expected post-execution state of every combination (record × flow × condition
branch) is too large to curate by hand. The E2E test in
`../flow_e2e_integration_test.go` validates *structural correctness* instead:

- the engine parses every flow into `models.FlowMetadata`
- every connector `TargetReference` resolves to a declared element
- every condition operator is recognised by `executor_helpers.evaluateCondition`
- every declared formula passes `formula.Engine.Validate` *or* — if Validate
  returns an error because the expression references a Salesforce function
  the engine has not wired yet — the failure is logged via `t.Logf` rather
  than asserted. This is deliberate: today's live fixtures use
  `DATETIMEVALUE(...)` / `ADDMONTHS(...)` combinations that the engine does
  not yet compile, and failing the whole suite on that would mask the more
  serious shape regressions the test is designed to catch. When the
  formula engine grows to cover the missing functions, flip `t.Logf` to
  `require.NoErrorf` in `validateFlowStructure`.

For the four high-value scenarios (subflow dispatch, Wait resume, formula
refresh, `__r` lazy-load), deep runtime simulation lives in the unit tests
already shipped on each engine lane (`executor_wait_test.go`,
`executor_helpers_test.go`, `executor_isblank_test.go`). This file is the
integration seam that confirms those unit-tested pieces parse and link
correctly against production-shaped metadata.