kaloko 0.3.0

package/schemas/scenario.v1.json

@@ -0,0 +1,668 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/scenario.v1.json",
+  "title": "Kaloko scenario",
+  "type": "object",
+  "required": [
+    "schema",
+    "id",
+    "title",
+    "nodes",
+    "edges"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "qawalk.scenario.v1"
+    },
+    "id": {
+      "$ref": "#/$defs/slug"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "kind": {
+      "enum": [
+        "task",
+        "flow"
+      ],
+      "default": "task"
+    },
+    "archived": {
+      "type": "boolean",
+      "default": false,
+      "description": "A retired scenario (replaced or split): the service hides it from the scenario list; its runs stay reachable."
+    },
+    "source": {
+      "type": "string",
+      "description": "Path to the human acceptance plan (ACCEPTANCE.md)."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "locales": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1
+    },
+    "viewports": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "integer",
+          "minimum": 200
+        },
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "environments": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "readonly": {
+      "type": "boolean",
+      "default": false
+    },
+    "platform": {
+      "enum": ["web", "android", "ios", "electron", "desktop"],
+      "default": "web",
+      "description": "What the flow runs on. web: pages in Chrome. android/ios/electron/desktop: an app, driven by the environment's app block (adb, iOS Simulator, Playwright Electron, macOS window) or captured with kaloko capture --image. Node paths are deep links for apps."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/node"
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/edge"
+      }
+    },
+    "lanes": {
+      "type": "array",
+      "description": "Optional labels for layout lanes, index = lane number.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "issue": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Ticket the scenario verifies. `number` alone resolves against the repository's remote.",
+      "properties": {
+        "repo": {
+          "type": "string",
+          "description": "owner/name"
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "url": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        }
+      }
+    },
+    "sessions": {
+      "type": "object",
+      "description": "People in the flow. Every non-decision node names one; the runner keeps one browser context per session and locale.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "title"
+        ],
+        "properties": {
+          "title": {
+            "description": "Localized or plain title, e.g. Member of the club."
+          },
+          "mailbox": {
+            "type": "string",
+            "description": "Default recipient for e-mail nodes of this session; {run} is replaced by the short run id."
+          },
+          "account": {
+            "type": "string",
+            "description": "Opaque project key handed to step scripts (the project maps it to credentials)."
+          },
+          "blocked_on": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Environments where this session's nodes are skipped."
+          }
+        }
+      }
+    },
+    "project": {
+      "$ref": "#/$defs/slug",
+      "description": "Optional project this flow belongs to; overrides `project` from kaloko.config.yml and the repository name for its runs."
+    },
+    "capture": {
+      "$ref": "#/$defs/capture"
+    }
+  },
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+    },
+    "localized": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "minProperties": 1
+        }
+      ]
+    },
+    "node": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "title"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/slug"
+        },
+        "kind": {
+          "enum": [
+            "screen",
+            "email",
+            "external",
+            "decision",
+            "stack"
+          ]
+        },
+        "title": {
+          "$ref": "#/$defs/localized"
+        },
+        "path": {
+          "$ref": "#/$defs/localized"
+        },
+        "purpose": {
+          "type": "string"
+        },
+        "lane": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "readonly": {
+          "type": "boolean"
+        },
+        "execution": {
+          "$ref": "#/$defs/execution"
+        },
+        "mail": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "subject": {
+              "$ref": "#/$defs/localized"
+            },
+            "to": {
+              "type": "string"
+            }
+          }
+        },
+        "criteria": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/criterion"
+          }
+        },
+        "session": {
+          "type": "string",
+          "description": "Key from `sessions`; which person performs this step."
+        },
+        "packs": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "seo",
+              "usability",
+              "a11y",
+              "perf",
+              "console",
+              "errors",
+              "app",
+              "design"
+            ]
+          },
+          "description": "Check packs whose criteria are added to this node (ids AC1xx seo, AC2xx usability, AC3xx a11y, AC4xx perf, AC5xx console, AC6xx design: checks against the design reference)."
+        },
+        "capture": {
+          "$ref": "#/$defs/capture"
+        },
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Stack steps: which pages of one template the step covers. One source: urls, file, sitemap (with match/exclude), crawl or script.",
+          "properties": {
+            "urls": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Paths or absolute URLs"
+            },
+            "file": {
+              "type": "string",
+              "description": "Text (one path or URL per line), CSV (first column) or JSON array of paths/URLs or {path,title}; relative to the scenario"
+            },
+            "sitemap": {
+              "type": "string",
+              "description": "Sitemap path or URL (sitemap indexes are followed one level)"
+            },
+            "match": {
+              "type": "string",
+              "description": "Regex on the path: keep matching pages"
+            },
+            "exclude": {
+              "type": "string",
+              "description": "Regex on the path: drop matching pages"
+            },
+            "crawl": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "from",
+                "links"
+              ],
+              "properties": {
+                "from": {
+                  "type": "string",
+                  "description": "Listing page path"
+                },
+                "links": {
+                  "type": "string",
+                  "description": "CSS selector of the links to the pages"
+                },
+                "next": {
+                  "type": "string",
+                  "description": "CSS selector of the next-page link"
+                },
+                "pages": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 200,
+                  "description": "Listing pages to follow (default 1)"
+                }
+              }
+            },
+            "script": {
+              "type": "string",
+              "description": "Module relative to the scenario: default export async ({ page, env, locale, url }) => [{ path | url, title?, key? }]"
+            },
+            "limit": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "description": "At most this many pages (default 500)"
+            },
+            "semantic_sample": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 10000,
+              "description": "Semantic criteria are evaluated on the first N pages only (default 20); deterministic ones on every page"
+            },
+            "viewports": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Viewports for the pages (default: the first of the run)"
+            }
+          }
+        },
+        "fields": {
+          "type": "array",
+          "maxItems": 12,
+          "description": "Stack steps: columns of the stack index, read from every page",
+          "items": {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]{0,30}$"
+              },
+              "label": {
+                "type": "string"
+              },
+              "from": {
+                "type": "string",
+                "description": "title | h1 | description | canonical | lang | words | http | url | path | a CSS selector (text), selector@attribute, or count:selector"
+              }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "decision"
+              }
+            }
+          },
+          "then": {
+            "not": {
+              "required": [
+                "criteria"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "execution": {
+      "type": "object",
+      "required": [
+        "strategy",
+        "instructions"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "strategy": {
+          "enum": [
+            "playwright",
+            "script",
+            "agent",
+            "manual"
+          ],
+          "description": "playwright/script: an automated step script (web: Playwright page; apps: the app driver); agent: an agent drives and captures; manual: a person does."
+        },
+        "script": {
+          "type": "string"
+        },
+        "instructions": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requires": {
+          "type": "array",
+          "description": "Agent capabilities the step needs, e.g. browser, computer_use.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "criterion": {
+      "type": "object",
+      "required": [
+        "id",
+        "text",
+        "check"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^AC[0-9]+[a-z]?$"
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "highlight": {
+          "type": "string",
+          "description": "CSS selector to outline in the screenshot."
+        },
+        "check": {
+          "oneOf": [
+            {
+              "$ref": "#/$defs/deterministic"
+            },
+            {
+              "$ref": "#/$defs/semantic"
+            },
+            {
+              "$ref": "#/$defs/manualCheck"
+            }
+          ]
+        },
+        "pack": {
+          "type": "string",
+          "description": "Set by the CLI on criteria that came from a pack."
+        }
+      }
+    },
+    "deterministic": {
+      "type": "object",
+      "required": [
+        "type",
+        "assert"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "deterministic"
+        },
+        "assert": {
+          "enum": [
+            "exists",
+            "absent",
+            "count",
+            "text_matches",
+            "text_absent",
+            "attr_equals",
+            "no_overflow",
+            "no_console_errors",
+            "title_matches",
+            "meta_matches",
+            "link_matches",
+            "http_status",
+            "link_home",
+            "app_touch_targets",
+            "app_no_truncation",
+            "app_no_crash",
+            "app_labels",
+            "a11y_images_alt",
+            "a11y_names",
+            "a11y_labels",
+            "a11y_headings",
+            "a11y_contrast",
+            "a11y_main",
+            "a11y_unique_ids",
+            "perf_lcp",
+            "perf_cls",
+            "perf_ttfb",
+            "perf_weight",
+            "uses_tokens",
+            "design_pixels",
+            "design_structure"
+          ]
+        },
+        "selector": {
+          "type": "string"
+        },
+        "pattern": {
+          "type": "string"
+        },
+        "attr": {
+          "type": "string"
+        },
+        "value": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ],
+          "description": "attr_equals: the attribute value; http_status: the exact status (e.g. 404). Without value, http_status accepts min..max (default 200..299)."
+        },
+        "min": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "max": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "ratio": {
+          "type": "number",
+          "minimum": 0,
+          "description": "design_pixels: maximum share of differing pixels (default 0.03)."
+        },
+        "flags": {
+          "type": "string",
+          "pattern": "^[imsu]{0,4}$",
+          "description": "Regex flags for pattern: i (ignore case), m, s. Page text is innerText, so CSS text-transform (uppercase buttons) applies."
+        }
+      }
+    },
+    "semantic": {
+      "type": "object",
+      "required": [
+        "type",
+        "question"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "semantic"
+        },
+        "question": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Yes/no question in English; yes means the criterion is met."
+        },
+        "true": {
+          "type": "string",
+          "description": "What counts as yes (edge cases)."
+        },
+        "false": {
+          "type": "string",
+          "description": "What counts as no (edge cases)."
+        },
+        "scope": {
+          "type": "string",
+          "description": "CSS selector limiting the state sent to the evaluator."
+        },
+        "about": {
+          "enum": [
+            "page",
+            "console"
+          ],
+          "description": "console: the evaluator reads the captured console errors with the step purpose (triage) instead of the page"
+        }
+      }
+    },
+    "manualCheck": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "manual"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "required": [
+        "from",
+        "to"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "from": {
+          "$ref": "#/$defs/slug"
+        },
+        "to": {
+          "$ref": "#/$defs/slug"
+        },
+        "label": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "main",
+            "alt"
+          ],
+          "default": "main"
+        }
+      }
+    },
+    "capture": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Capture quality. Default WebP at 1× for the canvas; documentation runs use { format: png, scale: 2, mask: [...], annotate: true }.",
+      "properties": {
+        "format": {
+          "enum": [
+            "webp",
+            "png"
+          ],
+          "description": "png is lossless (print, manuals)"
+        },
+        "scale": {
+          "enum": [
+            1,
+            2
+          ],
+          "description": "device pixel ratio of the screenshot"
+        },
+        "quality": {
+          "type": "number",
+          "minimum": 0.3,
+          "maximum": 1,
+          "description": "WebP quality"
+        },
+        "mask": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "CSS selectors covered by a solid box on the image (personal data)"
+        },
+        "annotate": {
+          "type": "boolean",
+          "description": "numbered marks on the elements of criteria with highlight"
+        },
+        "full_page": {
+          "type": "boolean",
+          "description": "Screenshot of the whole page (default true; false for stack pages: the first screen only)"
+        }
+      }
+    }
+  }
+}