@workflow/world-testing 4.0.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @workflow/world-testing
+
+## 4.0.1-beta.0
+
+### Patch Changes
+
+- fcf63d0: Initial publish
+- Updated dependencies [fcf63d0]
+  - workflow@4.0.1-beta.0
+  - @workflow/world@4.0.1-beta.0
+  - @workflow/cli@4.0.1-beta.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@workflow/world-testing",
+  "version": "4.0.1-beta.0",
+  "description": "",
+  "main": "dist/src/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.5",
+    "chalk": "^5.6.2",
+    "hono": "^4.9.10",
+    "jsonlines": "^0.1.1",
+    "zod": "4.1.11",
+    "@workflow/cli": "4.0.1-beta.0",
+    "workflow": "4.0.1-beta.0",
+    "@workflow/world": "4.0.1-beta.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.6.2",
+    "@types/jsonlines": "^0.1.5",
+    "vitest": "^3.2.4",
+    "@workflow/tsconfig": "4.0.1-beta.0"
+  },
+  "peerDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "scripts": {
+    "build": "wf build && tsc",
+    "start": "node --watch src/server.mts",
+    "test": "vitest"
+  }
+}

package/src/addition.mts

@@ -0,0 +1,27 @@
+import { expect, test, vi } from 'vitest';
+import { createFetcher, startServer } from './util.mjs';
+
+export function addition(world: string) {
+  test('runs an addition', { timeout: 12_000 }, async () => {
+    const server = await startServer({ world }).then(createFetcher);
+    const result = await server.invoke(
+      'workflows/addition.ts',
+      'addition',
+      [1, 2]
+    );
+    expect(result.runId).toMatch(/^wrun_.+/);
+    await vi.waitFor(
+      async () => {
+        const run = await server.getRun(result.runId);
+        expect(run).toMatchObject<Partial<typeof run>>({
+          status: 'completed',
+          output: [3],
+        });
+      },
+      {
+        interval: 200,
+        timeout: 10_000,
+      }
+    );
+  });
+}

package/src/idempotency.mts

@@ -0,0 +1,30 @@
+import { expect, test, vi } from 'vitest';
+import { hydrateWorkflowReturnValue } from 'workflow/internal/serialization';
+import { createFetcher, startServer } from './util.mjs';
+
+export function idempotency(world: string) {
+  test('idempotency', { timeout: 60_000 }, async () => {
+    const server = await startServer({ world }).then(createFetcher);
+    const result = await server.invoke('workflows/noop.ts', 'brokenWf', [1, 2]);
+    expect(result.runId).toMatch(/^wrun_.+/);
+    const run = await vi.waitFor(
+      async () => {
+        const run = await server.getRun(result.runId);
+        expect(run).toMatchObject<Partial<typeof run>>({
+          status: 'completed',
+        });
+        return run;
+      },
+      {
+        interval: 200,
+        timeout: 59_000,
+      }
+    );
+
+    const output = await hydrateWorkflowReturnValue(run.output, [], globalThis);
+
+    expect(output).toEqual({
+      numbers: Array.from({ length: 110 }, () => expect.any(Number)),
+    });
+  });
+}

package/src/index.mts

@@ -0,0 +1,7 @@
+import { addition } from './addition.mjs';
+import { idempotency } from './idempotency.mjs';
+
+export function createTestSuite(pkgName: string) {
+  addition(pkgName);
+  idempotency(pkgName);
+}

package/src/server.mts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import { getRun, start } from 'workflow/api';
+import { getWorld } from 'workflow/runtime';
+import * as z from 'zod';
+import flow from '../.well-known/workflow/v1/flow.js';
+import manifest from '../.well-known/workflow/v1/manifest.debug.json' with {
+  type: 'json',
+};
+import step from '../.well-known/workflow/v1/step.js';
+
+if (!process.env.WORKFLOW_TARGET_WORLD) {
+  console.error(
+    'Error: WORKFLOW_TARGET_WORLD environment variable is not set.'
+  );
+  process.exit(1);
+}
+
+type Files = keyof typeof manifest.workflows;
+type Workflows<F extends Files> = keyof (typeof manifest.workflows)[F];
+
+const Invoke = z
+  .object({
+    file: z.literal(Object.keys(manifest.workflows) as Files[]),
+    workflow: z.string(),
+    args: z.unknown().array().default([]),
+  })
+  .transform((obj) => {
+    const file = obj.file as keyof typeof manifest.workflows;
+    const workflow = z
+      .literal(
+        Object.keys(manifest.workflows[file]) as Workflows<typeof file>[]
+      )
+      .parse(obj.workflow);
+    return {
+      args: obj.args,
+      workflow: manifest.workflows[file][workflow],
+    };
+  });
+
+const app = new Hono()
+  .post('/.well-known/workflow/v1/flow', (ctx) => {
+    return flow.POST(ctx.req.raw);
+  })
+  .post('/.well-known/workflow/v1/step', (ctx) => {
+    return step.POST(ctx.req.raw);
+  })
+  .get('/_manifest', (ctx) => ctx.json(manifest))
+  .post('/invoke', async (ctx) => {
+    const json = await ctx.req.json().then(Invoke.parse);
+    const handler = await start(json.workflow, json.args);
+
+    return ctx.json({ runId: handler.runId });
+  })
+  .get('/runs/:runId', async (ctx) => {
+    return ctx.json(await getWorld().runs.get(ctx.req.param('runId')));
+  })
+  .get('/runs/:runId/readable', async (ctx) => {
+    const runId = ctx.req.param('runId');
+    const run = getRun(runId);
+    return new Response(run.getReadable());
+  });
+
+serve(
+  {
+    fetch: app.fetch,
+    port: Number(process.env.PORT) || 0,
+  },
+  async (info) => {
+    console.log(`👂 listening on http://${info.address}:${info.port}`);
+    console.log('');
+
+    process.env.PORT = info.port.toString();
+
+    for (const [filename, workflows] of Object.entries(manifest.workflows)) {
+      for (const workflowName of Object.keys(workflows)) {
+        console.log(
+          `$ curl -X POST http://localhost:${info.port}/invoke -d '${JSON.stringify(
+            {
+              file: filename,
+              workflow: workflowName,
+            }
+          )}'`
+        );
+      }
+    }
+
+    const world = getWorld();
+    if (world.start) {
+      console.log(`starting background tasks...`);
+      await world.start().then(
+        () => console.log('background tasks started.'),
+        (err) => console.error('❗ error starting background tasks:', err)
+      );
+    }
+
+    if (process.env.CONTROL_FD === '3') {
+      const control = fs.createWriteStream('', { fd: 3 });
+      control.write(`${JSON.stringify({ state: 'listening', info })}\n`);
+      control.end();
+    }
+  }
+);

package/src/util.mts

@@ -0,0 +1,99 @@
+import cp from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { WorkflowRunSchema } from '@workflow/world';
+import chalk, { type ChalkInstance } from 'chalk';
+import jsonlines from 'jsonlines';
+import { assert, onTestFailed, onTestFinished } from 'vitest';
+import * as z from 'zod';
+import type manifest from '../.well-known/workflow/v1/manifest.debug.json';
+
+export const Control = z.object({
+  state: z.literal('listening'),
+  info: z.object({
+    port: z.number(),
+  }),
+});
+type Control = z.infer<typeof Control>;
+
+type Files = keyof typeof manifest.workflows;
+type Workflows<F extends Files> = keyof (typeof manifest.workflows)[F];
+
+export const Worlds = {
+  embedded: 'embedded',
+  postgres: '@workflow/world-postgres',
+};
+
+export async function startServer(opts: { world: string }) {
+  let serverPath = new URL('./server.mts', import.meta.url).pathname;
+
+  if (!existsSync(serverPath)) {
+    serverPath = new URL('./server.mjs', import.meta.url).pathname;
+  }
+
+  const proc = cp.spawn('node', [serverPath], {
+    stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      WORKFLOW_TARGET_WORLD: opts.world,
+      CONTROL_FD: '3',
+    },
+  });
+  onTestFinished(() => {
+    proc.kill();
+  });
+
+  const stdio = [] as { stream: ChalkInstance; chunk: string }[];
+  proc.stdout?.on('data', (chunk) => {
+    stdio.push({ stream: chalk.white, chunk: chunk.toString() });
+  });
+  proc.stderr?.on('data', (chunk) => {
+    stdio.push({ stream: chalk.red, chunk: chunk.toString() });
+  });
+
+  onTestFailed(() => {
+    console.log('=== SERVER STDIO ===');
+    let buffer = '';
+    for (const { stream, chunk } of stdio) {
+      buffer += stream.inverse(chunk);
+    }
+    console.log(buffer);
+  });
+
+  const fd3 = proc.stdio[3];
+  assert(fd3, 'fd3 should be defined');
+
+  for await (const chunk of fd3.pipe(jsonlines.parse())) {
+    return Control.parse(chunk);
+  }
+
+  throw new Error('Server did not start correctly');
+}
+
+const Invoke = z.object({ runId: z.coerce.string() });
+
+export function createFetcher(control: Control) {
+  return {
+    async invoke<F extends Files, W extends Workflows<F>>(
+      file: F,
+      workflow: W,
+      args: unknown[]
+    ) {
+      const x = await fetch(`http://localhost:${control.info.port}/invoke`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({ file, workflow, args }),
+      });
+      const data = await x.json().then(Invoke.parse);
+      return data;
+    },
+    async getRun(id: string) {
+      const x = await fetch(
+        `http://localhost:${control.info.port}/runs/${encodeURIComponent(id)}`
+      );
+      const data = await x.json();
+      return WorkflowRunSchema.parseAsync(data);
+    },
+  };
+}

package/test/embedded.test.ts

@@ -0,0 +1,3 @@
+import { createTestSuite } from '../src/index.mjs';
+
+createTestSuite('embedded');

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@workflow/tsconfig/base.json",
+  "compilerOptions": {
+    "moduleResolution": "NodeNext",
+    "allowJs": true,
+    "module": "NodeNext",
+    "outDir": "dist"
+  },
+  "include": ["src", ".well-known"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}

package/turbo.json

@@ -0,0 +1,13 @@
+{
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["src", "workflows"],
+      "outputs": [".well-known", "dist"]
+    },
+    "test": {
+      "dependsOn": ["build"]
+    }
+  }
+}

package/workflows/addition.ts

@@ -0,0 +1,16 @@
+import { RetryableError } from 'workflow';
+
+async function add(num: number, num2: number): Promise<number> {
+  'use step';
+  if (Math.random() < 0.2) {
+    throw new RetryableError('Random failure, please retry');
+  }
+  return num + num2;
+}
+
+export async function addition(num: number, num2: number): Promise<number> {
+  'use workflow';
+  const result = await add(num, num2);
+  console.log({ result });
+  return result;
+}

package/workflows/noop.ts

@@ -0,0 +1,37 @@
+let count = 0;
+export async function noop(_i: number) {
+  'use step';
+
+  count++;
+  return count;
+}
+
+export async function brokenWf() {
+  'use workflow';
+
+  const numbers = [] as number[];
+
+  {
+    const promises: Promise<number>[] = [];
+    for (let i = 0; i < 10; i++) {
+      promises.push(noop(i));
+    }
+
+    console.log('await 10');
+    numbers.push(...(await Promise.all(promises)));
+  }
+
+  {
+    const promises: Promise<number>[] = [];
+    for (let i = 0; i < 100; i++) {
+      promises.push(noop(1000 + i));
+    }
+
+    console.log('await 100');
+    numbers.push(...(await Promise.all(promises)));
+  }
+
+  console.log('done.');
+
+  return { numbers };
+}