saffron-ai 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saffron-ai",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Gherkin-native AI-fallback test runner: zero-token cached replay, runtime AI healing, honest reports",
   "scripts": {
     "test": "vitest run",

package/skills/saffron/SKILL.md

@@ -68,6 +68,7 @@ strict under every policy. Use `Given`/`When` for actions.
 ## 3. Never bake volatile or secret values into files
 
 - Secrets: `{env:VAR}`, as in `When I enter "{env:ADMIN_PASSWORD}" in the password field`.
+- Shared test data (accounts, names, enum values): put it in `data/*.json` and write `{data:users.admin.email}` (file, then dotted path; one value, not a list). The recording stores the token, so editing the file changes the next replay at zero tokens. Never for secrets: data files are committed. To check a whole list (an enum), point a Then step at it: `Then the status filter should list every {data:enums.OrderStatus}`; replay iterates the file's list, so adding a value needs no re-record. `Examples: {data:roles}` reads outline rows from `data/roles.csv` or a JSON list (`.saffron` only). A value that must be new on every run (an email for a sign-up) is `{unique:name}`: fresh per run, the same within it.
 - Dates: write intent, not literals: "1 day from today" records as `{date+1}`.
 - Dynamic display values: capture and compare, e.g. `I record the total as "first"` … `"first" should differ from the displayed total`.
 

package/skills/saffron/references/config.md

@@ -20,6 +20,7 @@ your-project/
 {
   "baseURL": "https://stage.your-app.com",
   "features": "features",
+  "dataDir": "data",
   "actionTimeoutMs": 5000,
   "pollIntervalMs": 100,
   "retries": 1,
@@ -40,6 +41,7 @@ your-project/
 
 | Key | Meaning |
 |---|---|
+| `dataDir` | Folder of JSON files read by `{data:file.key}` tokens (default `data`). Committed; not for secrets |
 | `baseURL` | App under test; steps say "the login page", not full URLs |
 | `storageState` | Playwright storage-state JSON so replays and the agent start authenticated (`npx playwright open --save-storage=.auth/state.json <url>`) |
 | `actionTimeoutMs` | Budget for one action: Playwright's actionability wait and the deadline for a polled assertion (default 5000) |

package/skills/saffron/references/syntax.md

@@ -84,6 +84,60 @@ a missing variable fails fast by name. Honest note: during the *first*
 recording the agent types the real value once: use rotatable staging
 credentials.
 
+## Test data: `{data:...}`
+
+Values that several scenarios share (accounts, names, enum values) live in
+JSON files under `data/`, not in the feature file. Committed, so never
+secrets.
+
+```json
+// data/users.json
+{ "admin": { "email": "admin@test.com" }, "roles": ["Admin", "Editor", "Viewer"] }
+```
+
+```gherkin
+When I sign in as {data:users.admin.email}
+Then the role filter should list every {data:users.roles}
+```
+
+- A reference is the file name without `.json`, then a dotted path; a number
+  picks a list entry (`{data:users.roles.0}`).
+- The recording stores the token and replay reads the file: editing a value
+  changes the next replay at zero tokens. A recording that still spells out
+  the OLD value goes stale and records again.
+- `every {data:list}` in a `Then` step records ONE assertion that names the
+  list; replay checks each value, so adding one to the file needs no
+  re-record. Every listed value must be present; extras like "All" are fine.
+- A missing file or key stops the run before a browser opens, by name.
+- Per environment: `data/users.staging.json` is laid over `data/users.json`
+  with `--env staging` (or `SAFFRON_ENV`, or `"env"` in the config).
+
+### Examples from a file (`.saffron` only)
+
+```gherkin
+Scenario Outline: Role sees its menu
+  Given I sign in as <role>
+  Then I should see the <menu> menu
+
+  Examples: {data:roles}
+```
+
+Reads `data/roles.csv` (header row = placeholder names) or a JSON list of
+records. One recording, one zero-token replay per row; adding a row records
+nothing. A placeholder with no column is a parse error naming both.
+
+### Unique per run: `{unique:name}`
+
+```gherkin
+When I register as user-{unique:id}@test.com
+Then the welcome banner should greet user-{unique:id}@test.com
+```
+
+New on every run, the same within one run, so a later step can find what an
+earlier step created and reruns do not collide with leftovers.
+`{unique:name}` is 10 lowercase letters and digits; `{unique:name:digits}`
+is 9 digits.
+
 ## Dates and dynamic values
 
 - Say the intent: "select a check-in date 1 day from today" → recorded

package/templates/saucedemo/data/catalog.json

@@ -0,0 +1,11 @@
+{
+  "products": [
+    "Sauce Labs Backpack",
+    "Sauce Labs Bike Light",
+    "Sauce Labs Bolt T-Shirt",
+    "Sauce Labs Fleece Jacket",
+    "Sauce Labs Onesie",
+    "Test.allTheThings() T-Shirt (Red)"
+  ],
+  "featured": "Sauce Labs Backpack"
+}

package/templates/saucedemo/features/shopping.saffron

@@ -18,3 +18,12 @@ Feature: Shopping
     Then the overview should list "Sauce Labs Bike Light"
     When I click the "Finish" button
     Then I should see "Thank you for your order!"
+
+  # Test data lives in data/catalog.json, not in this file. {data:...} is
+  # read again on every replay: add a product to the JSON and the next run
+  # checks for it, with nothing recorded again.
+  @catalog
+  Scenario: The catalog lists every product in the data folder
+    StepSet Log in as the standard user
+    Then the product list should show every {data:catalog.products}
+    And the product list should show "{data:catalog.featured}"

package/textmate/saffron/syntaxes/saffron.tmLanguage.json

@@ -61,7 +61,12 @@
           "name": "punctuation.separator.saffron"
         },
         "3": {
-          "name": "entity.name.section.saffron"
+          "name": "entity.name.section.saffron",
+          "patterns": [
+            {
+              "include": "#token"
+            }
+          ]
         }
       }
     },
@@ -139,7 +144,7 @@
       "name": "variable.parameter.placeholder.saffron"
     },
     "token": {
-      "match": "\\{(env:[A-Za-z_][A-Za-z0-9_]*|date(?:[+-]\\d+)?(?::[^}]+)?)\\}",
+      "match": "\\{(env:[A-Za-z_][A-Za-z0-9_]*|data:[A-Za-z0-9_.-]+|unique:[A-Za-z0-9_-]+(?::digits)?|date(?:[+-]\\d+)?(?::[^}]+)?)\\}",
       "name": "constant.other.token.saffron"
     }
   },