saffron-ai 1.0.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +273 -0
- package/README.md +20 -8
- package/dist-pkg/cli.js +533 -343
- package/package.json +9 -14
- package/skills/saffron/SKILL.md +42 -4
- package/skills/saffron/references/api.md +149 -0
- package/skills/saffron/references/config.md +7 -2
- package/skills/saffron/references/syntax.md +27 -3
- package/templates/playwright/saffron-helpers.ts +1264 -0
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,279 @@ the VS Code extension (`ChathurangaJayasinghe.saffron-vscode`) and the
|
|
|
5
5
|
JetBrains plugin (`ai.saffron.jetbrains`). Dates are publish dates. Each
|
|
6
6
|
release heading names its main feature: `## <version>: <title>`.
|
|
7
7
|
|
|
8
|
+
## 1.2.0: API test automation
|
|
9
|
+
|
|
10
|
+
Released 2026-10-26.
|
|
11
|
+
|
|
12
|
+
The same plain-language scenarios now test an HTTP API, with no browser and
|
|
13
|
+
the workflow you know: the agent records each scenario once, every later run
|
|
14
|
+
replays it at zero tokens, a `Then` is never healed, and every proposal is
|
|
15
|
+
proved by a zero-AI replay before you review it. API test automation and
|
|
16
|
+
`saffron eject` are both **beta**: they work and are covered by tests, and
|
|
17
|
+
they are still being shaped by use, so their recordings and output may
|
|
18
|
+
change between releases. See "API tests" in the guide.
|
|
19
|
+
|
|
20
|
+
**Upgrading from 1.1.0.** Nothing to change in a browser project. What can
|
|
21
|
+
be different after `npm update`:
|
|
22
|
+
|
|
23
|
+
- A recording that holds a request is at schema version 6 or 7. saffron-ai
|
|
24
|
+
1.1.0 and earlier ask to be updated for it rather than calling it
|
|
25
|
+
malformed.
|
|
26
|
+
- `@cursor/sdk` and `@openai/codex-sdk` are no longer peer dependencies.
|
|
27
|
+
npm never installed them, so a Codex or Cursor project installs its SDK
|
|
28
|
+
itself as before, and Saffron now checks its version: one missing, too old
|
|
29
|
+
or of another major stops the provider before it starts, naming the
|
|
30
|
+
command that installs a supported one
|
|
31
|
+
(`npm install --save-dev "@cursor/sdk@^1.0.32"`).
|
|
32
|
+
- A few selector forms an Outline row could pass on another row's data with
|
|
33
|
+
are now refused, so they run red and record again once (see "Outline
|
|
34
|
+
rows" below).
|
|
35
|
+
- A failing check now reads `Check "..." failed: <why>`, and a stale
|
|
36
|
+
recording says what changed, so a script that matched the old wording
|
|
37
|
+
needs the new one.
|
|
38
|
+
|
|
39
|
+
Runner
|
|
40
|
+
|
|
41
|
+
- **API tests (beta).** Tag a feature `@api` and its scenarios test an HTTP
|
|
42
|
+
API. The recording keeps each request as sent (method, path, headers, a
|
|
43
|
+
JSON body typed as the API expects, a form or a multipart body with a file
|
|
44
|
+
of the project) and the response fields later steps need, written as
|
|
45
|
+
`{captured:name}`. A `Then` checks the latest response: its status, its
|
|
46
|
+
JSON fields, a header, how long it took, or its body against the pinned
|
|
47
|
+
OpenAPI contract, and each check is verified before it is recorded. A
|
|
48
|
+
write (`POST`, `PUT`, `PATCH`, `DELETE`) is never retried, a proof replay
|
|
49
|
+
makes records of its own through `{unique:...}` values, and a run of
|
|
50
|
+
`@api` scenarios alone needs no browser installed.
|
|
51
|
+
|
|
52
|
+
- **A pinned contract, and several APIs.** `saffron api pin <url or file>`
|
|
53
|
+
pins an OpenAPI 3 contract (from a document URL, a Swagger UI page or a
|
|
54
|
+
file, JSON or YAML, following up to five redirects, each checked as the
|
|
55
|
+
first, a page's links read against where it landed) as
|
|
56
|
+
`api/openapi.json`, and a recording checked against
|
|
57
|
+
it goes stale when it changes. `api.services` names more APIs beside the
|
|
58
|
+
default one, each with its own base URL and contract; a step names the API
|
|
59
|
+
it calls and the recording keeps the name, never the host, so
|
|
60
|
+
`--api-url` points a run elsewhere. While recording, a write goes only to
|
|
61
|
+
a path the contract lists or the step names, and the agent hears when a
|
|
62
|
+
body does not match the contract's request schema.
|
|
63
|
+
|
|
64
|
+
- **Steps that wait, follow and check more.** A request polls with `until`
|
|
65
|
+
for a step that waits for a state (a read only, every 100 ms at the
|
|
66
|
+
fastest, 10 minutes at the longest), keeps a header such as `Location`, and
|
|
67
|
+
takes its own timeout. Field checks find an entry of a list wherever it
|
|
68
|
+
stands (`item`), hold for every entry (`every`), and check `count`,
|
|
69
|
+
`differs`, `pattern`, `min` and `max`. Every duration may be a text with a
|
|
70
|
+
unit and the step's tokens (`"<seconds> s"`), so each Outline row keeps
|
|
71
|
+
its own. The same checks work on the browser's response checks.
|
|
72
|
+
|
|
73
|
+
- **Fixtures and named operations (beta).** A `.saffron` feature tagged
|
|
74
|
+
`@api` may open with one `Fixture:` block, steps run once per run before
|
|
75
|
+
the feature's scenarios (a login, a seeded customer), recorded, proved and
|
|
76
|
+
accepted like a scenario. The values it keeps reach every scenario of the
|
|
77
|
+
feature as read-only `{captured:name}` seeds. A step set that sends a
|
|
78
|
+
request and keeps a value is a reusable named operation.
|
|
79
|
+
|
|
80
|
+
- **The API from a browser scenario.** A browser step can call the API
|
|
81
|
+
through its session's cookies, and later browser steps can type or check
|
|
82
|
+
what it kept.
|
|
83
|
+
|
|
84
|
+
- **Credentials the API hands out stay out of everything.** A login's token,
|
|
85
|
+
a session id or an API key, read from the words of the capture's name or
|
|
86
|
+
field, is masked as `{captured:name}` in the transcript, the report, the
|
|
87
|
+
trace, every error, a failed step's page URL and the agent's own view, in every spelling JSON or a
|
|
88
|
+
URL gives it, and is sent only to an API under test. A browser step uses
|
|
89
|
+
one only on the app's own origin: never in a page or frame of another
|
|
90
|
+
origin or a sandboxed one, never in a new tab elsewhere, a dialog's answer
|
|
91
|
+
or a key press with no target. While recording, the agent sends requests
|
|
92
|
+
only to the APIs under test, and one it sends again is written as its
|
|
93
|
+
token in a header, a JSON body, a form field or a multipart part; a
|
|
94
|
+
request never goes to a link-local address; and a multipart file is never
|
|
95
|
+
a hidden file such as `.env`, nor a link or hard link to one, and goes
|
|
96
|
+
only to an API under test. `{env:...}` secrets keep every rule they had.
|
|
97
|
+
|
|
98
|
+
- **Transcripts, reports and traces.** An API scenario leaves the requests it
|
|
99
|
+
sent, and the checks each step made beside them, as `requests.json`. The
|
|
100
|
+
report lists them per step and opens each onto its headers and bodies;
|
|
101
|
+
`saffron trace` replays them, the selected request and response shown
|
|
102
|
+
where a browser replay shows the page; nothing is drawn while a scenario
|
|
103
|
+
runs. Each step of a trace is titled with its own keyword (`Given`,
|
|
104
|
+
`And`), and the report names an Outline row by its values beside its
|
|
105
|
+
number. `api.transcript` (`"on-failure"`, `"on"` or `"off"`) sets how much
|
|
106
|
+
is kept.
|
|
107
|
+
|
|
108
|
+
- **Reviewing a recording.** `saffron diff` and proposals show what a
|
|
109
|
+
request sends, what it keeps and from where, and what each check expects,
|
|
110
|
+
so a recording can be reviewed from them. A stale recording says what
|
|
111
|
+
changed ("step 2 reads ... now", "the API contract ... changed"), in the
|
|
112
|
+
run's error and in `saffron status`. A status counts as expected only
|
|
113
|
+
where the step names it ("should answer 404", "returns 201 with the new
|
|
114
|
+
customer", "is not found"), never a quantity ("a crate with 500 units", "a product with 500 in stock",
|
|
115
|
+
"with 500, then").
|
|
116
|
+
|
|
117
|
+
- **Outline rows stay on their own data.** A row value in a JSON or header
|
|
118
|
+
`pattern` is escaped and kept whole, so `^Order <id>` for 1 never passes on
|
|
119
|
+
"Order 12". In selectors, a row value inside `:has(...)` or a nested XPath
|
|
120
|
+
predicate is checked on the element that predicate selects, text under two
|
|
121
|
+
negations counts as present, and a row value checked before a sibling
|
|
122
|
+
combinator (`+`, `~`) is refused, since the check would land on the
|
|
123
|
+
sibling. An untyped `differs` reads the number 5 as the text "5".
|
|
124
|
+
|
|
125
|
+
- **Export to Playwright Test (beta) covers API steps.** `saffron eject`
|
|
126
|
+
writes requests and their checks as calls on the exported helper, every
|
|
127
|
+
kind of JSON field check included (the helper carries Saffron's own
|
|
128
|
+
checker), with extracted values, typed bodies, forms, uploads, polling and
|
|
129
|
+
`api.services`. A schema check is exported with the contract's schemas
|
|
130
|
+
resolved into the spec and validated with ajv, as replay validates it; a
|
|
131
|
+
project with one installs `ajv@^8 ajv-formats@^3`, as eject says. It
|
|
132
|
+
guards and masks credentials as replay does, and writes as `test.fixme`,
|
|
133
|
+
with the reason, a scenario that reads a fixture and a browser step that
|
|
134
|
+
carries a captured credential.
|
|
135
|
+
|
|
136
|
+
- **Step reuse with the API.** A value the agent kept while recording reaches
|
|
137
|
+
the reused steps after it, so a new scenario built mostly from known steps
|
|
138
|
+
records without going back to the agent. A reused step whose recording no
|
|
139
|
+
longer matched is reported as re-recorded only when the agent did record
|
|
140
|
+
it again.
|
|
141
|
+
|
|
142
|
+
- **No agent session that could not help.** When the app or API under test
|
|
143
|
+
does not answer at all, a scenario that would record or heal is red with
|
|
144
|
+
"no agent session was started" and why, instead of spending tokens on a
|
|
145
|
+
server that is not there (browser scenarios too). Only the APIs a scenario
|
|
146
|
+
names are checked, so an unrelated one being down blocks nothing; any port
|
|
147
|
+
is checked; behind a proxy no check is made. An API `Then` that fails
|
|
148
|
+
after every request answered as recorded is red at once, since a `Then` is
|
|
149
|
+
never healed. A changed contract is checked again by a zero-AI replay of
|
|
150
|
+
the same recording and filed for review, instead of being recorded again.
|
|
151
|
+
A run with `--no-agent` says so where it needed the agent.
|
|
152
|
+
|
|
153
|
+
- **Reviewing and reading results.** `saffron diff` takes a feature file
|
|
154
|
+
for its pending proposals, and the run's hint says to review with it. A
|
|
155
|
+
failure and a transcript check name an Outline row's values instead of its
|
|
156
|
+
`<column>`, and a null check reads "equal to null". Chronic advice counts
|
|
157
|
+
only reds that cost a session, for scenarios the run ran, and the "vs
|
|
158
|
+
previous run" line names scenarios that turned green. The agent counts
|
|
159
|
+
steps from 1 in what a person reads, as the runner does.
|
|
160
|
+
|
|
161
|
+
- **`saffron init` ignores `.env`.** The `.gitignore` entries it writes
|
|
162
|
+
include `.env`, where `{env:...}` secrets are kept.
|
|
163
|
+
|
|
164
|
+
- **Agents know about API tests.** `saffron mcp` has an `api_contract` tool
|
|
165
|
+
that lists every API's operations, the Saffron skill covers `@api`
|
|
166
|
+
scenarios (`references/api.md`), and the instructions `saffron init`
|
|
167
|
+
writes and the Claude Code and Codex plugins describe them.
|
|
168
|
+
|
|
169
|
+
- **Internal.** The runner is split along the line a second kind of test
|
|
170
|
+
crosses: the orchestrator owns what every medium shares (freshness,
|
|
171
|
+
proposals, proofs, heals and the verdict) and drives the browser and the
|
|
172
|
+
HTTP medium through one contract. Nothing changes for a project.
|
|
173
|
+
|
|
174
|
+
## 1.1.0: Secrets the AI agent never sees
|
|
175
|
+
|
|
176
|
+
Released 2026-10-22.
|
|
177
|
+
|
|
178
|
+
**Upgrading from 1.0.1.** Nothing to change in a project. What can be
|
|
179
|
+
different after `npm update`:
|
|
180
|
+
|
|
181
|
+
- Row value boundaries are stricter: a regex atom that may match nothing
|
|
182
|
+
or anything (`\W*`, `.+`, `[^,]+`), a lookaround, or a group edge or
|
|
183
|
+
alternation next to a row value (`Order <id>(?:st|)`) no longer drops
|
|
184
|
+
the value's boundary, and row values are matched in every selector-chain
|
|
185
|
+
container. A row value at the edge of a role's name, a label, a
|
|
186
|
+
placeholder, an attribute (`alt`, `title`, `[aria-label*=...]`, XPath
|
|
187
|
+
`contains(@href, ...)`), `:text(...)`, `:text-matches(...)`, an inner
|
|
188
|
+
`has` locator or a frame's selector is whole too, as in text: row `1`
|
|
189
|
+
never finds `Order 12`. Beside a digit, a decimal or thousands part
|
|
190
|
+
counts as part of the number (`1` is not in `1.5` or `1,000`) unless the
|
|
191
|
+
pattern writes it (`<n>\.\d{2}`), and a pattern with a quantifier right
|
|
192
|
+
after a row value (`<id>+`) is refused. Text a selector says must be
|
|
193
|
+
absent (`:not(...)`, XPath `not(...)`, `has-not-text`) is no longer
|
|
194
|
+
looked for as present.
|
|
195
|
+
A recording that passed in 1.0.1 because of that can turn red after
|
|
196
|
+
`npm update`; it never turns a failing check green. Re-record what fails
|
|
197
|
+
(`saffron run --rerecord <file>:<line>`).
|
|
198
|
+
- Recordings that use JSON response field checks, or single-quoted row
|
|
199
|
+
values in any part of a selector chain (an XPath part first too), are
|
|
200
|
+
format version 5. Saffron 1.0.1 refuses them by name, so a team updates
|
|
201
|
+
together.
|
|
202
|
+
- An Outline with `As "<who>"` steps recorded before 1.0.1, where a step
|
|
203
|
+
types a value of that person's own, records again once on another
|
|
204
|
+
person's row (red under `--no-agent`, saying why). The new recording
|
|
205
|
+
then refuses the other rows by name, as 1.0.1 recordings of that shape
|
|
206
|
+
do: give each person's values a column, or each person a Scenario.
|
|
207
|
+
- `saffron run` exits 2 when the files it is given hold no scenario (only
|
|
208
|
+
step sets, or nothing yet), where it said "0 passed" and exited 0.
|
|
209
|
+
- Amount checks read a minus spaced off at the start (`- €5.00`) or after
|
|
210
|
+
a currency (`CHF-5.00`) as negative, and a hyphen after another word
|
|
211
|
+
(`ID-123`) as no sign.
|
|
212
|
+
|
|
213
|
+
- Agent-blind secrets: the recording agent no longer sees `{env:...}`
|
|
214
|
+
values. It is given the token and types the token; Saffron's browser
|
|
215
|
+
tools put the value into the page, and every tool result (snapshots,
|
|
216
|
+
echoed code, console, network, `browser_evaluate`) and every Saffron
|
|
217
|
+
reply comes back with the value as its token, as do the prompt's base
|
|
218
|
+
URL and a heal prompt's replay failure and page address. That covers a
|
|
219
|
+
snapshot line Playwright single-quotes, a value Playwright's call log
|
|
220
|
+
cuts with "…", and a downloaded file quoted in a reply. A token counts
|
|
221
|
+
only where the browser types, picks, opens or uploads it (`{env:...}` in
|
|
222
|
+
`browser_evaluate` code is refused), and a word the scenario or a data
|
|
223
|
+
value it uses writes with a short value glued in (`qa{env:PIN}`) is
|
|
224
|
+
shown back as written. The
|
|
225
|
+
recording reads the browser's own results, so a value quoted in
|
|
226
|
+
Playwright's echoed code is masked to its token there too. This holds
|
|
227
|
+
for Claude, Codex, Antigravity and Cursor alike. The guide has a diagram
|
|
228
|
+
of the flow and lists what remains: values under three characters, a
|
|
229
|
+
page that shows the value transformed or only part of it, code that
|
|
230
|
+
reads a field the value was typed into, same-text matches masked along
|
|
231
|
+
with the value, and a check on the value shown in another case.
|
|
232
|
+
|
|
233
|
+
- `saffron eject` writes the committed recordings as Playwright Test specs
|
|
234
|
+
you own from then on: one spec per feature file, each Gherkin step a
|
|
235
|
+
`test.step`, a helper file beside them, and `playwright.config.ts` when
|
|
236
|
+
there is none. An exported test is never looser than replay: it may fail
|
|
237
|
+
where replay would pass, never the other way, and what has no faithful
|
|
238
|
+
form yet (amount checks, patterns or selectors holding a row value, JSON
|
|
239
|
+
response checks) is written as `test.fixme` with the reason. `{env:...}`
|
|
240
|
+
values are read when the test runs and never written into a file. The
|
|
241
|
+
exported checks read an element's text exactly as replay does, so CSS
|
|
242
|
+
`text-transform` or text split over blocks cannot pass there and fail in
|
|
243
|
+
replay. Two feature files that would share a spec file stop the command
|
|
244
|
+
before anything is written.
|
|
245
|
+
|
|
246
|
+
- UI tests can check JSON response fields by path, including nested fields
|
|
247
|
+
and array entries. Equality checks preserve string, number, boolean and
|
|
248
|
+
null types; presence checks distinguish a missing field from null.
|
|
249
|
+
Failures name the field and expected and actual values, with secrets
|
|
250
|
+
masked. These checks replay without AI and Then assertions stay strict.
|
|
251
|
+
Recordings using them require format version 5, so older runners refuse
|
|
252
|
+
them with update guidance instead of skipping the JSON checks. A field's
|
|
253
|
+
path is kept as recorded: a row value that sits in it by chance
|
|
254
|
+
(`/errors/0`) never makes another row check another field.
|
|
255
|
+
|
|
256
|
+
- Match row values in every selector-chain container, including single-quoted
|
|
257
|
+
text. Such a recording is format version 5, since 1.0.1 would fill a
|
|
258
|
+
single-quoted value in without a row boundary.
|
|
259
|
+
- A row value keeps its boundary in a pattern next to an atom that may
|
|
260
|
+
match nothing or anything (`\W*`, `\d*`, `.+`, `\S+`, `[^,]+`, `\P{L}+`),
|
|
261
|
+
a lookaround (`(?!-)`, `(?<!-)`), or a group edge or alternation
|
|
262
|
+
(`(x|<id>)`): `Order <id>.+` fails row "1" on "Order 12 shipped".
|
|
263
|
+
- An XPath selector (`xpath=//button`) replays: it was read as a regex
|
|
264
|
+
with the flags "button" and threw.
|
|
265
|
+
- An Outline with `As "<who>"` steps recorded before 1.0.1 records again
|
|
266
|
+
once on a row of another person, instead of replaying the first person's
|
|
267
|
+
values; the new recording refuses the other rows by name.
|
|
268
|
+
- Amounts: a minus spaced off at the start (`- €5.00`, `- 5,00 €`) or
|
|
269
|
+
glued after a currency (`CHF-5.00`, as Swiss formats write it) is
|
|
270
|
+
negative, and a hyphen after another word (`ID-123`) is no sign.
|
|
271
|
+
- A run of feature files with no scenario in them exits 2 and says so,
|
|
272
|
+
instead of "0 passed". A step set file that does not parse is named in
|
|
273
|
+
the error. Feature edits apply to files written with CRLF and keep their
|
|
274
|
+
line endings. A recording is written beside and renamed over, so a
|
|
275
|
+
stopped run never leaves half of one.
|
|
276
|
+
- Mask case-changed encoded secrets in capture names, reports and traces.
|
|
277
|
+
- Read labelled counts such as `Guests (2 pax)` as positive, also where
|
|
278
|
+
the label is a currency code in lower case (`Pens (2 pen)`). Accounting
|
|
279
|
+
parentheses still denote negative amounts with currency notation.
|
|
280
|
+
|
|
8
281
|
## 1.0.1: Amounts, downloads and dates as the app shows them
|
|
9
282
|
|
|
10
283
|
Released 2026-10-21.
|
package/README.md
CHANGED
|
@@ -29,6 +29,19 @@ Like a maturing Cucumber suite, most of a new feature file is steps you already
|
|
|
29
29
|
|
|
30
30
|
Data tables and doc strings are first-class: 2-column key/value tables parameterize the recording (`<table:username>`), multi-row record tables parameterize per cell (`<table:1:firstName>`), and `"""` doc strings record as `<docstring>`, so editing *values* or *content* replays at zero tokens, while structural changes (keys, headers, row counts) honestly re-record. Unambiguous params are scenario-wide, so a later assertion on a note's text follows content edits too. **Secrets** stay out of everything: `{env:VAR}` resolves from the environment (or a git-ignored `.env`) at replay, recordings and reports are masked back to the token, and missing variables fail fast by name.
|
|
31
31
|
|
|
32
|
+
## API tests (beta)
|
|
33
|
+
|
|
34
|
+
The same plain-language scenarios test a REST/JSON API with no browser: tag a
|
|
35
|
+
feature `@api` and the agent records each step as requests with typed bodies
|
|
36
|
+
and kept values, and checks of status, fields, headers, timing and the
|
|
37
|
+
schema of a pinned OpenAPI contract (`saffron api pin`). Replay sends the
|
|
38
|
+
requests again at zero tokens, a write never twice, and a changed contract
|
|
39
|
+
makes the recordings that checked it stale. `Fixture:` blocks set up once per
|
|
40
|
+
feature, browser scenarios can call the API too, and secrets and the
|
|
41
|
+
credentials an API hands out stay out of recordings, reports and traces.
|
|
42
|
+
See "API tests" in the [guide](https://saffron-ai.io/docs). API test
|
|
43
|
+
automation is in beta: it works, and it is still being shaped by use.
|
|
44
|
+
|
|
32
45
|
## Install
|
|
33
46
|
|
|
34
47
|
```bash
|
|
@@ -73,13 +86,14 @@ node dist/cli/index.js -p examples accept --all
|
|
|
73
86
|
|
|
74
87
|
| Command | What it does |
|
|
75
88
|
|---|---|
|
|
76
|
-
| `saffron run [paths] [--headed] [--filter expr] [--rerecord] [--no-agent] [--strict] [--browser b[,b...]] [--device name] [--viewport WxH] [--no-hooks] [--workers n] [--agent-workers n] [--heal-model m] [--no-verify] [--no-reuse] [--model m] [--storage-state f] [--trace mode]` | Run features. Cached replays are deterministic; misses/failures escalate to the agent (unless `--no-agent`). A path with a line or a name, `features/login.saffron:12` or `"features/login.saffron:Successful login"`, runs that one scenario. Replay cross-browser with `--browser firefox\|webkit`, parallelize with `--workers N`, heal on a cheaper model with `--heal-model`, keep an execution trace with `--trace retain-on-failure`. Exit 1 on red (and on yellow with `--strict`). |
|
|
89
|
+
| `saffron run [paths] [--headed] [--filter expr] [--rerecord] [--no-agent] [--strict] [--browser b[,b...]] [--device name] [--viewport WxH] [--no-hooks] [--workers n] [--agent-workers n] [--heal-model m] [--no-verify] [--no-reuse] [--model m] [--storage-state f] [--trace mode] [--api-url u \| name=u]` | Run features. Cached replays are deterministic; misses/failures escalate to the agent (unless `--no-agent`). A path with a line or a name, `features/login.saffron:12` or `"features/login.saffron:Successful login"`, runs that one scenario. Replay cross-browser with `--browser firefox\|webkit`, parallelize with `--workers N`, heal on a cheaper model with `--heal-model`, keep an execution trace with `--trace retain-on-failure`, point the APIs at another environment with `--api-url`. Exit 1 on red (and on yellow with `--strict`). |
|
|
77
90
|
| `saffron accept [files... \| --all] [--include-unverified] [--include-imported] [--with-feature-edit] [--propagate]` | Promote cache proposals to committed caches (`--all` skips UNVERIFIED ones unless `--include-unverified`, and ones imported from a CI run unless `--include-imported`); `--with-feature-edit` also rewrites the adapted steps in the `.feature` file (and keeps the cache in sync); `--propagate` applies the heal's locator fixes to every other cache using the same locator. One heal repairs N scenarios before they ever fail. No args: list pending proposals. |
|
|
78
91
|
| `saffron reject [files... \| --all]` | Discard proposals; the agent will try again next run. |
|
|
79
92
|
| `saffron export [-o file] [--branch name]` / `saffron runs` / `saffron import <bundles...> \| --run <id>` | Carry a CI heal to your machine: export packs the run's proposals, report, screenshots and traces into one bundle for CI to upload; `runs` lists the branch's CI runs (GitHub Actions or Azure Pipelines); import (of a file, or of a run with `--run`) checks the bundle against your checkout (repository, each proposal's binding) and files it there, ready for `saffron diff` and `saffron accept`. `--branch` also has CI commit the proposals to a new branch and open a draft pull request with their diffs. |
|
|
80
93
|
| `saffron status [--json]` | Project overview for people, IDE panels and dashboards: feature files and scenarios with cache state, tags, pending proposals, last run, history, vocabulary health (divergent steps, duplicate wordings proven by identical recordings), effective config, and suite quality from the run history (failing, flaky, never run, slowest, trends, per tag). |
|
|
81
94
|
| `saffron steps [search] [--json] [--snippets]` | List/search the step vocabulary (files + caches) with recorded/divergent/unrecorded badges and usage; `--snippets` writes `.vscode/saffron.code-snippets` for native VS Code completion. |
|
|
82
|
-
| `saffron mcp` | Serve the vocabulary
|
|
95
|
+
| `saffron mcp` | Serve the vocabulary, the project overview and the pinned API contract to AI assistants over stdio MCP (`search_steps`, `list_step_sets`, `project_status`, `api_contract`), e.g. `claude mcp add saffron -- npx saffron mcp`. |
|
|
96
|
+
| `saffron api pin <url or file> [--out file] [--service name]` | Pin an API's OpenAPI 3 document in the project (`api/openapi.json` by default) for `@api` scenarios' schema checks: from a Swagger UI page, the document's URL, or a file. Then set `"api": { "contract": "api/openapi.json" }` in `saffron.config.json`. `--service orders` pins a second API's contract, named under `api.services`. |
|
|
83
97
|
| `saffron author <prose-file> [-o out]` | Draft a `.saffron` feature file from plain-paragraph requirements, reusing the project's step vocabulary (AI; reports how many lines are seedable). |
|
|
84
98
|
| `saffron lsp` | Run the Saffron language server over stdio for JetBrains (LSP4IJ/Ultimate), Neovim, any LSP editor: badge completion, StepSet go-to-definition, hover, diagnostics. Highlighting for JetBrains comes from the bundled TextMate grammar (`textmate/saffron` in the package); run `npx saffron lsp` in a terminal for setup steps. |
|
|
85
99
|
| `saffron init [--agents list] [--examples]` | Make the project agent-ready (`--examples` installs the Saucedemo example suite): installs the bundled **Saffron agent skill** into `.claude/skills` and `.agents/skills` (Copilot/Cursor via `--agents`), registers the `saffron mcp` server in `.mcp.json` / `.cursor/mcp.json` / `.vscode/mcp.json`, adds a managed block to `AGENTS.md`/`CLAUDE.md`, scaffolds config. |
|
|
@@ -114,10 +128,10 @@ Configuration lives in `saffron.config.json` at your project root:
|
|
|
114
128
|
```
|
|
115
129
|
|
|
116
130
|
`provider` (also `--provider`) picks whose agent records and heals:
|
|
117
|
-
`claude` (default), `codex` (ChatGPT plan; `npm i -D @openai/codex-sdk`),
|
|
131
|
+
`claude` (default), `codex` (ChatGPT plan; `npm i -D "@openai/codex-sdk@>=0.158.0"`),
|
|
118
132
|
`antigravity` (Google AI Pro/Ultra through Google's `agy` CLI,
|
|
119
133
|
experimental; `npx saffron login antigravity` once) or `cursor`
|
|
120
|
-
(`npm i -D @cursor/sdk`, then `npx saffron login cursor`). `model` takes
|
|
134
|
+
(`npm i -D "@cursor/sdk@^1.0.32"`, then `npx saffron login cursor`). `model` takes
|
|
121
135
|
that provider's model names. `npx saffron login` says what a provider
|
|
122
136
|
still needs on this machine. Every sign-in flow is in
|
|
123
137
|
[AI providers and sign-in](https://saffron-ai.io/docs/ai-providers).
|
|
@@ -153,10 +167,8 @@ features/ your .saffron and .feature files
|
|
|
153
167
|
The roadmap is at **[saffron-ai.io/docs/roadmap](https://saffron-ai.io/docs/roadmap)**:
|
|
154
168
|
milestones, statuses and decision gates, and everything shipped so far in
|
|
155
169
|
its "Where we are" table.
|
|
156
|
-
Headlines ahead:
|
|
157
|
-
|
|
158
|
-
agent-blind secrets, LLM-less MCP replay, the Level-2 shared step library
|
|
159
|
-
(gated on Level-1 divergence data), and the long-term open-core SaaS layer.
|
|
170
|
+
Headlines ahead: failure video, LLM-less MCP replay, the Level-2 shared step
|
|
171
|
+
library (gated on Level-1 divergence data), and the long-term open-core SaaS layer.
|
|
160
172
|
|
|
161
173
|
## Documentation
|
|
162
174
|
|