slicetest 0.1.0 → 0.3.0

package/dist/yaml.d.ts

@@ -19,7 +19,7 @@ export interface YamlScenario {
     timeout?: number;
     steps: Step[];
 }
-export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep) & {
+export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep) & {
     line: number;
     name?: string;
 };
@@ -76,6 +76,7 @@ export interface SqlStep {
         count?: number;
     };
     capture?: Record<string, string>;
+    within?: number;
 }
 export interface DbStep {
     db: string;
@@ -86,6 +87,8 @@ export interface DbStep {
         count?: number;
     };
     capture?: Record<string, string>;
+    /** Retry for up to this many milliseconds, for effects the app applies asynchronously. */
+    within?: number;
 }
 export interface ReceivedStep {
     received: string;
@@ -93,6 +96,38 @@ export interface ReceivedStep {
     when?: Conditions;
     /** Exact number of matching calls. Default: at least one. */
     times?: number;
+    within?: number;
+}
+/** Expected rows per table: a count, or a list of subset rows. */
+export type ChangeSpec = {
+    inserted?: number | unknown[];
+    updated?: number | unknown[];
+    deleted?: number | unknown[];
+};
+/**
+ * The database changed exactly in these tables since the scenario started (or
+ * the last checkpoint). Tables that aren't listed must be unchanged.
+ */
+export interface ChangesStep {
+    changes: Record<string, ChangeSpec>;
+    within?: number;
+}
+/** Wait until the app (or `from:` a service) prints a line matching `log` (a regex) during the scenario. */
+export interface LogStep {
+    log: string;
+    from?: string;
+    /** Milliseconds to wait. Default 5000. */
+    within?: number;
+}
+/** Later `changes` steps only see what happens after this step. */
+export interface CheckpointStep {
+    checkpoint: true;
+}
+/** Compare the scenario's trace (requests, stub calls, database changes) with its stored snapshot. */
+export interface SnapshotStep {
+    snapshot: true;
+    /** Keys whose values are masked in addition to dates and UUIDs. */
+    mask?: string[];
 }
 export declare class YamlScenarioError extends Error {
 }

package/dist/yaml.js

@@ -3,9 +3,13 @@ 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"],
+    sql: ["params", "expect", "capture", "within"],
+    db: ["where", "orderBy", "expect", "capture", "within"],
+    received: ["call", "when", "times", "within"],
+    changes: ["within"],
+    log: ["from", "within"],
+    checkpoint: [],
+    snapshot: ["mask"],
 };
 const EXPECT_KEYS = {
     request: ["status", "headers", "json", "text"],
@@ -13,6 +17,7 @@ const EXPECT_KEYS = {
     db: ["rows", "count"],
 };
 const CONDITION_KEYS = ["query", "headers", "json", "body"];
+const CHANGE_KEYS = ["inserted", "updated", "deleted"];
 const RESPONSE_KEYS = ["status", "headers", "body"];
 const SCENARIO_KEYS = ["name", "steps", "each", "skip", "only", "timeout"];
 const CALL = /^([A-Za-z]+|\*)\s+(\/\S*)$/;
@@ -88,7 +93,32 @@ function parseStep(node, fail, lineOf) {
         if (!allowed.has(key))
             fail(at(key), `unknown key "${key}" in a ${kind} step (allowed: ${[...allowed].join(", ")})`);
     }
-    if (typeof raw[kind] !== "string" || !raw[kind])
+    if (kind === "changes") {
+        const tables = raw.changes;
+        if (!tables || typeof tables !== "object" || Array.isArray(tables))
+            fail(at(kind), "`changes:` must map table names to { inserted, updated, deleted }");
+        for (const [table, spec] of Object.entries(tables)) {
+            if (!spec || typeof spec !== "object" || Array.isArray(spec))
+                fail(at(kind), `changes of "${table}" must be a mapping such as { inserted: 1 }`);
+            for (const [k, v] of Object.entries(spec)) {
+                if (!CHANGE_KEYS.includes(k))
+                    fail(at(kind), `unknown key "${k}" in changes of "${table}" (allowed: ${CHANGE_KEYS.join(", ")})`);
+                if (!Array.isArray(v) && !(typeof v === "number" && v >= 0))
+                    fail(at(kind), `${table}.${k} must be a count or a list of rows`);
+            }
+        }
+    }
+    else if (kind === "checkpoint") {
+        if (raw.checkpoint !== true)
+            fail(at(kind), "use `checkpoint: true`");
+    }
+    else if (kind === "snapshot") {
+        if (raw.snapshot !== true)
+            fail(at(kind), "use `snapshot: true`");
+        if (raw.mask !== undefined && !(Array.isArray(raw.mask) && raw.mask.every((k) => typeof k === "string")))
+            fail(at("mask"), "`mask:` must be a list of keys, e.g. [token]");
+    }
+    else 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];
@@ -105,6 +135,8 @@ function parseStep(node, fail, lineOf) {
         if (raw[key] !== undefined && !CALL.test(String(raw[key])))
             fail(at(key), `\`${key}\` must look like "POST /path", got "${raw[key]}"`);
     };
+    if (raw.within !== undefined && (typeof raw.within !== "number" || raw.within <= 0))
+        fail(at("within"), "`within` must be a positive number of milliseconds");
     const number = (key) => {
         if (raw[key] !== undefined && (typeof raw[key] !== "number" || raw[key] < 0))
             fail(at(key), `\`${key}\` must be a non-negative number`);
@@ -142,6 +174,16 @@ function parseStep(node, fail, lineOf) {
             if (!raw.rows || typeof raw.rows !== "object")
                 fail(at("rows"), "an insert step needs `rows` (a mapping or a list of mappings)");
             break;
+        case "log":
+            try {
+                new RegExp(raw.log);
+            }
+            catch (e) {
+                fail(at("log"), `\`log\` must be a regular expression: ${e.message}`);
+            }
+            if (raw.from !== undefined && typeof raw.from !== "string")
+                fail(at("from"), "`from` must be a service name");
+            break;
         case "received":
             call("call");
             number("times");

package/package.json

@@ -1,20 +1,23 @@
 {
   "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.",
+  "version": "0.3.0",
+  "description": "Framework-agnostic slice tests: drive a real app process over HTTP with a real Postgres and stubbed outbound APIs, checked against OpenAPI contracts.",
   "keywords": [
     "testing",
     "integration-testing",
     "slice-test",
     "api-testing",
     "postgres",
+    "mysql",
     "stub",
     "mock-server",
     "vitest",
     "vitest-plugin",
     "yaml",
     "testcontainers",
-    "language-agnostic"
+    "language-agnostic",
+    "openapi",
+    "contract-testing"
   ],
   "author": "pon-bok",
   "repository": {
@@ -52,25 +55,39 @@
     "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",
+    "test:dist": "npm run build && tsc -p examples/tsconfig.dist.json && 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"
+    "vitest": ">=5",
+    "mysql2": ">=3",
+    "@testcontainers/mysql": ">=11"
   },
   "dependencies": {
     "@testcontainers/postgresql": "^12.2.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "pg": "^8.23.0",
     "testcontainers": "^12.2.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
+    "@testcontainers/mysql": "^12.2.0",
     "@types/node": "^26.6.3",
     "@types/pg": "^8.23.1",
+    "mysql2": "^3.24.5",
     "typescript": "^7.0.2",
     "vitest": "^5.0.2"
   },
   "bin": {
     "slicetest": "dist/cli.js"
+  },
+  "peerDependenciesMeta": {
+    "mysql2": {
+      "optional": true
+    },
+    "@testcontainers/mysql": {
+      "optional": true
+    }
   }
 }

package/schema/scenario.schema.json

@@ -277,6 +277,11 @@
               "additionalProperties": {
                 "type": "string"
               }
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Retry this step for up to this many milliseconds, for effects the app applies asynchronously"
             }
           }
         },
@@ -325,6 +330,11 @@
               "additionalProperties": {
                 "type": "string"
               }
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Retry this step for up to this many milliseconds, for effects the app applies asynchronously"
             }
           }
         },
@@ -368,6 +378,151 @@
               "type": "integer",
               "minimum": 0,
               "description": "Exact count; default: at least once"
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Retry this step for up to this many milliseconds, for effects the app applies asynchronously"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "changes"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "changes": {
+              "type": "object",
+              "description": "The database changed exactly in these tables since the scenario started (or the last checkpoint). Unlisted tables must be unchanged.",
+              "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "inserted": {
+                    "oneOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object"
+                        }
+                      }
+                    ],
+                    "description": "Count, or subset rows"
+                  },
+                  "updated": {
+                    "oneOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object"
+                        }
+                      }
+                    ],
+                    "description": "Count, or subset rows (after the update)"
+                  },
+                  "deleted": {
+                    "oneOf": [
+                      {
+                        "type": "integer",
+                        "minimum": 0
+                      },
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "object"
+                        }
+                      }
+                    ],
+                    "description": "Count, or subset rows"
+                  }
+                }
+              }
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Retry this step for up to this many milliseconds, for effects the app applies asynchronously"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "checkpoint"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "checkpoint": {
+              "const": true,
+              "description": "Later `changes` steps only see what happens after this step"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "log"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "log": {
+              "type": "string",
+              "description": "Regular expression; waits until the app (or `from:` a service) prints a matching line during this scenario"
+            },
+            "from": {
+              "type": "string",
+              "description": "Service name (from the `services` option). Default: the app"
+            },
+            "within": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Milliseconds to wait. Default 5000"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "snapshot"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "snapshot": {
+              "const": true,
+              "description": "Compare this scenario's trace so far (requests to the app, calls to stubs, database changes; dates and UUIDs masked) with its stored snapshot. Update with vitest -u"
+            },
+            "mask": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Keys whose values are masked too, e.g. [token]"
+            },
+            "name": {
+              "type": "string",
+              "description": "Label shown when this step fails"
             }
           }
         }
@@ -402,4 +557,4 @@
       "additionalProperties": true
     }
   }
-}
+}