slicetest 0.1.0

package/dist/yaml.js

@@ -0,0 +1,151 @@
+import { isMap, isSeq, LineCounter, parseDocument } from "yaml";
+const KINDS = {
+    stub: ["on", "when", "reply", "sequence", "networkError", "times", "delay"],
+    request: ["headers", "query", "json", "form", "body", "follow", "expect", "capture"],
+    insert: ["rows", "capture"],
+    sql: ["params", "expect", "capture"],
+    db: ["where", "orderBy", "expect", "capture"],
+    received: ["call", "when", "times"],
+};
+const EXPECT_KEYS = {
+    request: ["status", "headers", "json", "text"],
+    sql: ["rows", "count"],
+    db: ["rows", "count"],
+};
+const CONDITION_KEYS = ["query", "headers", "json", "body"];
+const RESPONSE_KEYS = ["status", "headers", "body"];
+const SCENARIO_KEYS = ["name", "steps", "each", "skip", "only", "timeout"];
+const CALL = /^([A-Za-z]+|\*)\s+(\/\S*)$/;
+export class YamlScenarioError extends Error {
+}
+export function parseScenarioFile(text, file) {
+    const lines = new LineCounter();
+    const doc = parseDocument(text, { lineCounter: lines, prettyErrors: true });
+    const [syntax] = doc.errors;
+    if (syntax)
+        throw new YamlScenarioError(`${file}:${syntax.linePos?.[0]?.line ?? "?"}: ${syntax.message}`);
+    const lineOf = (node) => (node && typeof node === "object" && "range" in node && node.range ? lines.linePos(node.range[0]).line : 0);
+    const fail = (node, msg) => {
+        throw new YamlScenarioError(`${file}:${lineOf(node)}: ${msg}`);
+    };
+    const root = doc.contents;
+    if (!isMap(root))
+        return fail(root, "expected a mapping with a `scenarios:` list");
+    const top = doc.toJS();
+    for (const key of Object.keys(top))
+        if (key !== "scenarios" && key !== "setup")
+            fail(root, `unknown top-level key "${key}" (expected scenarios, setup)`);
+    const stepsOf = (seqNode, what) => {
+        if (!isSeq(seqNode))
+            return fail(seqNode, `${what} must be a list of steps`);
+        return seqNode.items.map((item) => parseStep(item, fail, lineOf));
+    };
+    const scenariosNode = root.get("scenarios", true);
+    if (!isSeq(scenariosNode) || scenariosNode.items.length === 0)
+        return fail(scenariosNode ?? root, "`scenarios:` must be a non-empty list");
+    const setupNode = root.get("setup", true);
+    return {
+        file,
+        setup: setupNode ? stepsOf(setupNode, "setup") : [],
+        scenarios: scenariosNode.items.map((node) => {
+            if (!isMap(node))
+                return fail(node, "each scenario must be a mapping with `name` and `steps`");
+            const raw = node.toJSON();
+            for (const key of Object.keys(raw))
+                if (!SCENARIO_KEYS.includes(key))
+                    fail(node, `unknown scenario key "${key}" (expected ${SCENARIO_KEYS.join(", ")})`);
+            if (typeof raw.name !== "string" || !raw.name)
+                fail(node, "scenario needs a `name`");
+            if (raw.each !== undefined && (!Array.isArray(raw.each) || raw.each.some((r) => !r || typeof r !== "object"))) {
+                fail(node.get("each", true), "`each` must be a list of mappings");
+            }
+            if (raw.timeout !== undefined && typeof raw.timeout !== "number")
+                fail(node, "`timeout` must be a number of milliseconds");
+            return {
+                name: raw.name,
+                line: lineOf(node),
+                each: raw.each,
+                skip: raw.skip === true,
+                only: raw.only === true,
+                timeout: raw.timeout,
+                steps: stepsOf(node.get("steps", true), `scenario "${raw.name}": steps`),
+            };
+        }),
+    };
+}
+function parseStep(node, fail, lineOf) {
+    if (!isMap(node))
+        return fail(node, "a step must be a mapping, e.g. `- request: GET /health`");
+    const raw = node.toJSON();
+    const kinds = Object.keys(KINDS).filter((k) => k in raw);
+    if (kinds.length !== 1) {
+        fail(node, kinds.length === 0 ? `a step needs one of: ${Object.keys(KINDS).join(", ")}` : `a step can only be one of ${kinds.join(" / ")}`);
+    }
+    const kind = kinds[0];
+    const at = (key) => node.get(key, true) ?? node;
+    const allowed = new Set([kind, "name", ...KINDS[kind]]);
+    for (const key of Object.keys(raw)) {
+        if (!allowed.has(key))
+            fail(at(key), `unknown key "${key}" in a ${kind} step (allowed: ${[...allowed].join(", ")})`);
+    }
+    if (typeof raw[kind] !== "string" || !raw[kind])
+        fail(at(kind), `\`${kind}:\` must be a non-empty string`);
+    const keysOf = (key, allowedKeys) => {
+        const v = raw[key];
+        if (v === undefined)
+            return;
+        if (!v || typeof v !== "object" || Array.isArray(v))
+            fail(at(key), `\`${key}\` must be a mapping`);
+        for (const k of Object.keys(v)) {
+            if (!allowedKeys.includes(k))
+                fail(at(key), `unknown key "${k}" in ${key} (allowed: ${allowedKeys.join(", ")})`);
+        }
+    };
+    const call = (key) => {
+        if (raw[key] !== undefined && !CALL.test(String(raw[key])))
+            fail(at(key), `\`${key}\` must look like "POST /path", got "${raw[key]}"`);
+    };
+    const number = (key) => {
+        if (raw[key] !== undefined && (typeof raw[key] !== "number" || raw[key] < 0))
+            fail(at(key), `\`${key}\` must be a non-negative number`);
+    };
+    if (raw.capture !== undefined) {
+        keysOf("capture", Object.keys(raw.capture));
+        for (const [k, v] of Object.entries(raw.capture))
+            if (typeof v !== "string")
+                fail(at("capture"), `capture "${k}" must be a path such as json.id`);
+    }
+    if (kind in EXPECT_KEYS)
+        keysOf("expect", EXPECT_KEYS[kind]);
+    keysOf("when", CONDITION_KEYS);
+    switch (kind) {
+        case "stub": {
+            if (raw.on === undefined)
+                fail(node, "a stub step needs `on`, e.g. `on: POST /hook`");
+            call("on");
+            const answers = ["reply", "sequence", "networkError"].filter((k) => raw[k] !== undefined);
+            if (answers.length !== 1)
+                fail(node, "a stub step needs exactly one of reply / sequence / networkError");
+            keysOf("reply", RESPONSE_KEYS);
+            if (raw.sequence !== undefined && (!Array.isArray(raw.sequence) || raw.sequence.length === 0))
+                fail(at("sequence"), "`sequence` must be a non-empty list of responses");
+            number("times");
+            number("delay");
+            break;
+        }
+        case "request":
+            call("request");
+            if (["json", "form", "body"].filter((k) => raw[k] !== undefined).length > 1)
+                fail(node, "use only one of json / form / body");
+            break;
+        case "insert":
+            if (!raw.rows || typeof raw.rows !== "object")
+                fail(at("rows"), "an insert step needs `rows` (a mapping or a list of mappings)");
+            break;
+        case "received":
+            call("call");
+            number("times");
+            break;
+    }
+    return { ...raw, line: lineOf(node) };
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "slicetest",
+  "version": "0.1.0",
+  "description": "Framework-agnostic slice tests: drive a real app process over HTTP with a real Postgres and stubbed outbound APIs.",
+  "keywords": [
+    "testing",
+    "integration-testing",
+    "slice-test",
+    "api-testing",
+    "postgres",
+    "stub",
+    "mock-server",
+    "vitest",
+    "vitest-plugin",
+    "yaml",
+    "testcontainers",
+    "language-agnostic"
+  ],
+  "author": "pon-bok",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/revo1290/slicetest.git"
+  },
+  "homepage": "https://github.com/revo1290/slicetest#readme",
+  "bugs": {
+    "url": "https://github.com/revo1290/slicetest/issues"
+  },
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "default": "./dist/vitest.js"
+    },
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "default": "./dist/yaml.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:dist": "npm run build && vitest run --config examples/vitest.dist.config.ts && node dist/cli.js --config examples/slicetest.config.yaml",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "vitest": ">=5"
+  },
+  "dependencies": {
+    "@testcontainers/postgresql": "^12.2.0",
+    "pg": "^8.23.0",
+    "testcontainers": "^12.2.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "@types/pg": "^8.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  },
+  "bin": {
+    "slicetest": "dist/cli.js"
+  }
+}

package/schema/scenario.schema.json

@@ -0,0 +1,405 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/slicetest/schema/scenario.schema.json",
+  "title": "slicetest YAML scenarios",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "scenarios"
+  ],
+  "properties": {
+    "setup": {
+      "type": "array",
+      "description": "Steps run at the start of every scenario",
+      "items": {
+        "$ref": "#/$defs/step"
+      }
+    },
+    "scenarios": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "steps"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "May use {{field}} from `each` rows"
+          },
+          "each": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Run once per row; row fields become variables"
+          },
+          "skip": {
+            "type": "boolean"
+          },
+          "only": {
+            "type": "boolean"
+          },
+          "timeout": {
+            "type": "integer"
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/step"
+            }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "step": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "stub",
+            "on"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "stub": {
+              "type": "string",
+              "description": "Stub name (declared in `stubs`). Registers a route on it."
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "on": {
+              "type": "string",
+              "pattern": "^([A-Za-z]+|\\*)\\s+/\\S*$",
+              "description": "METHOD /path, e.g. POST /polls"
+            },
+            "when": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "query": {
+                  "type": "object"
+                },
+                "headers": {
+                  "type": "object"
+                },
+                "json": {
+                  "description": "Subset of the request JSON"
+                },
+                "body": {}
+              }
+            },
+            "reply": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "status": {
+                  "type": "integer"
+                },
+                "headers": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "string"
+                  }
+                },
+                "body": {
+                  "description": "String, or anything else to send as JSON. May use {{call.params.x}}, {{call.json.x}}, {{call.query.x}}"
+                }
+              }
+            },
+            "sequence": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "status": {
+                    "type": "integer"
+                  },
+                  "headers": {
+                    "type": "object",
+                    "additionalProperties": {
+                      "type": "string"
+                    }
+                  },
+                  "body": {
+                    "description": "String, or anything else to send as JSON. May use {{call.params.x}}, {{call.json.x}}, {{call.query.x}}"
+                  }
+                }
+              },
+              "minItems": 1
+            },
+            "networkError": {
+              "const": true
+            },
+            "times": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "delay": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "request"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "request": {
+              "type": "string",
+              "description": "Request to the app: METHOD /path"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "headers": {
+              "type": "object"
+            },
+            "query": {
+              "type": "object"
+            },
+            "json": {},
+            "form": {
+              "type": "object"
+            },
+            "body": {
+              "type": "string"
+            },
+            "follow": {
+              "type": "boolean"
+            },
+            "expect": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "status": {
+                  "type": [
+                    "integer",
+                    "string"
+                  ]
+                },
+                "headers": {
+                  "type": "object"
+                },
+                "json": {
+                  "description": "Subset of the response JSON"
+                },
+                "text": {}
+              }
+            },
+            "capture": {
+              "type": "object",
+              "description": "Save values as variables for later steps, e.g. { pollId: json.id }",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "insert",
+            "rows"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "insert": {
+              "type": "string",
+              "description": "Table to insert into"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "rows": {
+              "type": [
+                "object",
+                "array"
+              ]
+            },
+            "capture": {
+              "type": "object",
+              "description": "Save values as variables for later steps, e.g. { pollId: json.id }",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "sql"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "sql": {
+              "type": "string",
+              "description": "SQL to run ($1, $2 … for params)"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "params": {
+              "type": "array"
+            },
+            "expect": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "rows": {
+                  "type": "array",
+                  "description": "Rows in order; each row may omit columns"
+                },
+                "count": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "capture": {
+              "type": "object",
+              "description": "Save values as variables for later steps, e.g. { pollId: json.id }",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "db"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "db": {
+              "type": "string",
+              "description": "Table to read"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "where": {
+              "type": "object",
+              "description": "null = IS NULL, list = IN"
+            },
+            "orderBy": {
+              "type": [
+                "string",
+                "array"
+              ]
+            },
+            "expect": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "rows": {
+                  "type": "array",
+                  "description": "Rows in order; each row may omit columns"
+                },
+                "count": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "capture": {
+              "type": "object",
+              "description": "Save values as variables for later steps, e.g. { pollId: json.id }",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "received"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "received": {
+              "type": "string",
+              "description": "Stub name. Asserts the app called it."
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "call": {
+              "type": "string",
+              "pattern": "^([A-Za-z]+|\\*)\\s+/\\S*$",
+              "description": "METHOD /path, e.g. POST /polls"
+            },
+            "when": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "query": {
+                  "type": "object"
+                },
+                "headers": {
+                  "type": "object"
+                },
+                "json": {
+                  "description": "Subset of the request JSON"
+                },
+                "body": {}
+              }
+            },
+            "times": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Exact count; default: at least once"
+            }
+          }
+        }
+      ]
+    },
+    "matcher": {
+      "type": "object",
+      "description": "Value matcher: {$type}, {$regex}, {$contains} or {$any}",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "properties": {
+        "$type": {
+          "enum": [
+            "string",
+            "number",
+            "boolean",
+            "array",
+            "object",
+            "null"
+          ]
+        },
+        "$regex": {
+          "type": "string"
+        },
+        "$contains": {
+          "type": "string"
+        },
+        "$any": {
+          "const": true
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}