ars9
90be5a5490
- replace (page, context, helpers) signature with async (context) => {}
- add ScriptContext interface exposing page, browser, env, getEnv,
getCredential, getStepOutput, runSnippet, dumpDom, log/warn/error
- rename getEnvUrl to getEnv throughout service and docs
- fix step ordering: normalizeStepOrder and run step rows are now 1-based
- migrate existing DB rows (scenario_steps, scenario_run_steps) +1
- update all tests and stored snippet/step code in DB to new API
83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# Scenario execution
|
|
|
|
When a scenario run is created, the server creates one `ScenarioRunStep` per scenario step.
|
|
|
|
- Step runs are ordered by `step.order`.
|
|
- First step run starts as `pending`; the rest start as `waiting`.
|
|
- Scheduler tick (`@Interval(1000)`) picks pending runs and processes steps in order.
|
|
- Steps in the same run share one Playwright browser/context/page.
|
|
|
|
## Execution model
|
|
|
|
Current scheduler behavior is exec-centric:
|
|
|
|
- `execCode` is required for a step to pass.
|
|
- `validateCode` is optional and runs after `execCode`.
|
|
- Legacy step type metadata may still appear in MCP payloads, but run execution is not branched by step type.
|
|
|
|
## Script runtime
|
|
|
|
`execCode` and `validateCode` execute as async JavaScript with:
|
|
|
|
- `page`: Playwright `Page`
|
|
- `context`: Playwright `BrowserContext`
|
|
- `helpers`: utility object
|
|
- `console`: proxied to run logs (`log`, `warn`, `error`, etc.)
|
|
|
|
`validateCode` additionally receives `result`, which is the value returned by `execCode`.
|
|
|
|
## Available helpers
|
|
|
|
- `helpers.dumpDom(selector?)`: simplified DOM snapshot
|
|
- `helpers.log(...args)`, `helpers.warn(...args)`, `helpers.error(...args)`: structured step logs
|
|
- `helpers.getStepOutput(order)`: prior step output by absolute order (`0`, `1`, ...) or relative (`-1` previous step)
|
|
- `helpers.getCredential(alias)`: credential payload assigned to the scenario alias
|
|
- `helpers.env`: shallow copy of environment URL map
|
|
- `helpers.getEnv(key)`: required environment value lookup (throws if missing)
|
|
- `helpers.runSnippet(name, ...args)`: execute stored snippet code in the same page/context/helpers scope
|
|
|
|
## Validation contract
|
|
|
|
`validateCode` may return:
|
|
|
|
```js
|
|
return { success: true, description: 'ok' };
|
|
// or
|
|
return false;
|
|
```
|
|
|
|
Interpretation:
|
|
|
|
- Boolean: `true` = pass, `false` = fail
|
|
- Object: `success` controls pass/fail; `description` is persisted as step description
|
|
|
|
On validation failure, the step fails and the run is marked `fail`.
|
|
|
|
## Statuses
|
|
|
|
Run status:
|
|
|
|
- `pending`
|
|
- `in_progress`
|
|
- `pass`
|
|
- `fail`
|
|
|
|
Run-step status:
|
|
|
|
- `waiting`
|
|
- `pending`
|
|
- `in_progress`
|
|
- `pass`
|
|
- `fail`
|
|
- `cancelled`
|
|
|
|
## Example workflow
|
|
|
|
1. Create environment
|
|
2. Create credentials and snippets (optional but common)
|
|
3. Create scenario
|
|
4. Add ordered steps (`execCode`, optional `validateCode`)
|
|
5. Assign credentials to scenario aliases when needed
|
|
6. Run scenario
|
|
7. Wait for run completion and inspect run logs/outputs
|