Skip to content

docs: add testing workflows guide to foundations#1115

Open
johnlindquist wants to merge 3 commits intomainfrom
docs/testing-workflows
Open

docs: add testing workflows guide to foundations#1115
johnlindquist wants to merge 3 commits intomainfrom
docs/testing-workflows

Conversation

@johnlindquist
Copy link
Contributor

@johnlindquist johnlindquist commented Feb 18, 2026

Summary

  • Adds testing guide to Foundations section covering unit testing steps, integration testing workflows, hooks/webhooks testing, error handling tests, and stress testing
  • Motivated by usage data: 242K testing runs and need for developer experience guidance
  • All code samples pass TypeScript type-checking validation
  • Link validation passes with zero errors

Test plan

  • Verify link validation passes (bun run lint:links - 0 errors)
  • Verify TypeScript code samples compile (pnpm test:docs - all testing.mdx samples pass)
  • Verify MDX renders correctly in dev server
  • Verify meta.json and index.mdx navigation works

@changeset-bot
Copy link

changeset-bot bot commented Feb 18, 2026 •
edited
Loading

⚠️ No Changeset found

Latest commit: b5a0da6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel
Copy link
Contributor

vercel bot commented Feb 18, 2026 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
example-nextjs-workflow-turbopack Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
example-nextjs-workflow-webpack Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
example-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-astro-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-express-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-fastify-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-hono-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-nitro-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-nuxt-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-sveltekit-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workbench-vite-workflow Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workflow-docs Ready Ready Preview, 💬 1 unresolved, Open in v0 Feb 19, 2026 6:57pm
workflow-nest Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm
workflow-swc-playground Ready Ready Preview, Comment, Open in v0 Feb 19, 2026 6:57pm

@github-actions
Copy link
Contributor

github-actions bot commented Feb 18, 2026 •
edited
Loading

📊 Benchmark Results

📈 Comparing against baseline from main branch. Green 🟢 = faster, Red 🔺 = slower.

workflow with no steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 0.029s (-13.6% 🟢) 1.005s (~) 0.976s 10 1.00x
💻 Local Express 0.035s (+6.5% 🔺) 1.005s (~) 0.970s 10 1.19x
🐘 Postgres Nitro 0.185s (-61.2% 🟢) 1.010s (~) 0.825s 10 6.35x
🐘 Postgres Express 0.302s (+191.7% 🔺) 1.010s (~) 0.709s 10 10.36x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 0.584s (-15.4% 🟢) 1.888s (-9.1% 🟢) 1.304s 10 1.00x
▲ Vercel Nitro 0.606s (-43.1% 🟢) 2.033s (-18.1% 🟢) 1.426s 10 1.04x

🔍 Observability: Express | Nitro

workflow with 1 step

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 1.079s (-2.4%) 2.005s (~) 0.926s 10 1.00x
💻 Local Express 1.107s (~) 2.006s (~) 0.899s 10 1.03x
🐘 Postgres Express 2.415s (-2.5%) 3.015s (~) 0.600s 10 2.24x
🐘 Postgres Nitro 2.450s (+4.4%) 3.014s (~) 0.564s 10 2.27x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.565s (+11.9% 🔺) 3.505s (+11.7% 🔺) 0.940s 10 1.00x
▲ Vercel Express 2.837s (+30.0% 🔺) 3.640s (+15.4% 🔺) 0.803s 10 1.11x

🔍 Observability: Nitro | Express

workflow with 10 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 10.588s (-2.2%) 11.025s (~) 0.437s 3 1.00x
💻 Local Express 10.849s (~) 11.023s (~) 0.174s 3 1.02x
🐘 Postgres Express 20.245s (-0.6%) 21.061s (~) 0.816s 2 1.91x
🐘 Postgres Nitro 20.301s (~) 21.057s (~) 0.756s 2 1.92x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 17.643s (~) 18.655s (-0.7%) 1.012s 2 1.00x
▲ Vercel Nitro 18.488s (+5.0% 🔺) 19.789s (+2.8%) 1.301s 2 1.05x

🔍 Observability: Express | Nitro

workflow with 25 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 26.857s (-2.3%) 27.055s (-3.5%) 0.198s 3 1.00x
💻 Local Express 27.529s (~) 28.052s (~) 0.523s 3 1.03x
🐘 Postgres Express 48.499s (-3.3%) 49.131s (-3.0%) 0.631s 2 1.81x
🐘 Postgres Nitro 50.303s (~) 51.121s (~) 0.818s 2 1.87x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 43.428s (+1.2%) 44.482s (+0.9%) 1.055s 2 1.00x
▲ Vercel Nitro 50.392s (+16.4% 🔺) 51.602s (+16.5% 🔺) 1.210s 2 1.16x

🔍 Observability: Express | Nitro

workflow with 50 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 55.843s (-2.4%) 56.107s (-3.4%) 0.264s 2 1.00x
💻 Local Express 57.404s (~) 58.103s (~) 0.699s 2 1.03x
🐘 Postgres Express 75.629s (-24.6% 🟢) 76.184s (-24.8% 🟢) 0.555s 2 1.35x
🐘 Postgres Nitro 94.172s (-6.0% 🟢) 94.196s (-6.0% 🟢) 0.024s 1 1.69x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 89.652s (+3.5%) 91.225s (+3.8%) 1.573s 1 1.00x
▲ Vercel Express 91.343s (+3.4%) 92.514s (+3.8%) 1.171s 2 1.02x

🔍 Observability: Nitro | Express

Promise.all with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 1.380s (-3.8%) 2.005s (~) 0.625s 15 1.00x
💻 Local Express 1.435s (+2.4%) 2.006s (~) 0.571s 15 1.04x
🐘 Postgres Express 2.040s (-15.3% 🟢) 2.835s (-5.9% 🟢) 0.795s 11 1.48x
🐘 Postgres Nitro 2.241s (+5.0%) 2.832s (-6.0% 🟢) 0.591s 11 1.62x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.440s (+5.7% 🔺) 3.348s (+1.6%) 0.907s 9 1.00x
▲ Vercel Express 15.719s (+547.6% 🔺) 16.881s (+400.4% 🔺) 1.163s 4 6.44x

🔍 Observability: Nitro | Express

Promise.all with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 2.324s (-10.7% 🟢) 3.008s (~) 0.684s 10 1.00x
💻 Local Express 2.689s (+5.4% 🔺) 3.007s (~) 0.318s 10 1.16x
🐘 Postgres Express 7.878s (-2.4%) 8.529s (+3.0%) 0.651s 4 3.39x
🐘 Postgres Nitro 9.862s (+16.2% 🔺) 10.036s (+11.0% 🔺) 0.175s 4 4.24x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.818s (+6.1% 🔺) 3.777s (+9.2% 🔺) 0.959s 8 1.00x
▲ Vercel Express 10.026s (+222.7% 🔺) 10.912s (+158.0% 🔺) 0.886s 3 3.56x

🔍 Observability: Nitro | Express

Promise.all with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 6.849s (-6.8% 🟢) 7.416s (-7.5% 🟢) 0.567s 5 1.00x
💻 Local Express 7.679s (+5.5% 🔺) 8.020s (~) 0.341s 4 1.12x
🐘 Postgres Express 45.217s (+8.6% 🔺) 46.109s (+9.5% 🔺) 0.892s 1 6.60x
🐘 Postgres Nitro 48.156s (~) 49.125s (~) 0.969s 1 7.03x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 9.542s (+185.6% 🔺) 10.663s (+148.0% 🔺) 1.120s 4 1.00x
▲ Vercel Express 23.985s (+417.0% 🔺) 24.516s (+336.2% 🔺) 0.531s 2 2.51x

🔍 Observability: Nitro | Express

Promise.race with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 1.420s (-0.7%) 2.005s (~) 0.585s 15 1.00x
💻 Local Express 1.437s (+1.1%) 2.005s (~) 0.568s 15 1.01x
🐘 Postgres Nitro 2.011s (-11.5% 🟢) 2.599s (-3.2%) 0.588s 12 1.42x
🐘 Postgres Express 2.092s (+6.5% 🔺) 2.476s (-1.5%) 0.384s 13 1.47x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 11.410s (+328.8% 🔺) 12.948s (+255.9% 🔺) 1.538s 3 1.00x
▲ Vercel Express 12.920s (+484.3% 🔺) 13.926s (+325.6% 🔺) 1.006s 3 1.13x

🔍 Observability: Nitro | Express

Promise.race with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 2.455s (-8.4% 🟢) 3.009s (~) 0.554s 10 1.00x
💻 Local Express 2.684s (~) 3.007s (~) 0.323s 10 1.09x
🐘 Postgres Nitro 10.274s (-22.9% 🟢) 10.697s (-22.0% 🟢) 0.423s 3 4.18x
🐘 Postgres Express 11.958s (+4.4%) 12.706s (+5.6% 🔺) 0.748s 3 4.87x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 3.926s (+48.4% 🔺) 6.183s (+73.8% 🔺) 2.256s 6 1.00x
▲ Vercel Nitro 17.675s (+666.6% 🔺) 18.894s (+494.0% 🔺) 1.218s 2 4.50x

🔍 Observability: Express | Nitro

Promise.race with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 7.211s (-8.4% 🟢) 8.019s (-3.0%) 0.808s 4 1.00x
💻 Local Express 8.482s (+5.1% 🔺) 9.020s (+9.1% 🔺) 0.539s 4 1.18x
🐘 Postgres Express 49.629s (-3.7%) 50.149s (-3.8%) 0.520s 1 6.88x
🐘 Postgres Nitro 49.713s (-4.3%) 50.107s (-3.9%) 0.394s 1 6.89x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 7.093s (+83.9% 🔺) 8.331s (+79.2% 🔺) 1.237s 4 1.00x
▲ Vercel Nitro 13.375s (+331.9% 🔺) 14.116s (+254.2% 🔺) 0.741s 3 1.89x

🔍 Observability: Express | Nitro

Stream Benchmarks (includes TTFB metrics)
workflow with stream

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 0.117s (-33.4% 🟢) 1.002s (~) 0.010s (-9.9% 🟢) 1.016s (~) 0.899s 10 1.00x
💻 Local Express 0.177s (+4.7%) 1.003s (~) 0.012s (+2.6%) 1.017s (~) 0.841s 10 1.51x
🐘 Postgres Express 1.146s (-53.4% 🟢) 1.897s (-26.6% 🟢) 0.001s (-15.4% 🟢) 2.014s (-33.2% 🟢) 0.868s 10 9.82x
🐘 Postgres Nitro 1.325s (-40.5% 🟢) 1.714s (-39.1% 🟢) 0.001s (-23.5% 🟢) 2.012s (-33.3% 🟢) 0.687s 10 11.35x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.028s (+3.1%) 2.888s (+9.6% 🔺) 0.597s (-1.6%) 4.109s (+8.2% 🔺) 2.081s 10 1.00x
▲ Vercel Nitro 2.154s (+11.2% 🔺) 3.159s (+17.5% 🔺) 0.366s (-37.7% 🟢) 4.097s (+7.2% 🔺) 1.943s 10 1.06x

🔍 Observability: Express | Nitro

Summary

Fastest Framework by World

Winner determined by most benchmark wins

World 🥇 Fastest Framework Wins
💻 Local Nitro 12/12
🐘 Postgres Express 9/12
▲ Vercel Express 6/12
Fastest World by Framework

Winner determined by most benchmark wins

Framework 🥇 Fastest World Wins
Express 💻 Local 11/12
Nitro 💻 Local 12/12
Column Definitions
  • Workflow Time: Runtime reported by workflow (completedAt - createdAt) - primary metric
  • TTFB: Time to First Byte - time from workflow start until first stream byte received (stream benchmarks only)
  • Slurp: Time from first byte to complete stream consumption (stream benchmarks only)
  • Wall Time: Total testbench time (trigger workflow + poll for result)
  • Overhead: Testbench overhead (Wall Time - Workflow Time)
  • Samples: Number of benchmark iterations run
  • vs Fastest: How much slower compared to the fastest configuration for this benchmark

Worlds:

  • 💻 Local: In-memory filesystem world (local development)
  • 🐘 Postgres: PostgreSQL database world (local development)
  • ▲ Vercel: Vercel production/preview deployment
  • 🌐 Turso: Community world (local development)
  • 🌐 MongoDB: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Jazz: Community world (local development)

📋 View full workflow run

❌ Some benchmark jobs failed:

  • Local: success
  • Postgres: success
  • Vercel: failure

Check the workflow run for details.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 18, 2026 •
edited
Loading

🧪 E2E Test Results

❌ Some tests failed

Summary

Passed Failed Skipped Total
❌ ▲ Vercel Production 533 1 38 572
✅ 💻 Local Development 556 0 68 624
✅ 📦 Local Production 556 0 68 624
✅ 🐘 Local Postgres 556 0 68 624
✅ 🪟 Windows 49 0 3 52
❌ 🌍 Community Worlds 110 46 9 165
✅ 📋 Other 135 0 21 156
Total 2495 47 275 2817

❌ Failed Tests

▲ Vercel Production (1 failed)

nuxt (1 failed):

  • parallelSleepWorkflow
🌍 Community Worlds (46 failed)

mongodb (1 failed):

  • webhookWorkflow

turso (45 failed):

  • addTenWorkflow
  • addTenWorkflow
  • should work with react rendering in step
  • promiseAllWorkflow
  • promiseRaceWorkflow
  • promiseAnyWorkflow
  • hookWorkflow
  • webhookWorkflow
  • sleepingWorkflow
  • parallelSleepWorkflow
  • nullByteWorkflow
  • workflowAndStepMetadataWorkflow
  • fetchWorkflow
  • promiseRaceStressTestWorkflow
  • error handling error propagation workflow errors nested function calls preserve message and stack trace
  • error handling error propagation workflow errors cross-file imports preserve message and stack trace
  • error handling error propagation step errors basic step error preserves message and stack trace
  • error handling error propagation step errors cross-file step error preserves message and function names in stack
  • error handling retry behavior regular Error retries until success
  • error handling retry behavior FatalError fails immediately without retries
  • error handling retry behavior RetryableError respects custom retryAfter delay
  • error handling retry behavior maxRetries=0 disables retries
  • error handling retry behavior workflow completes despite transient 5xx on step_completed
  • error handling catchability FatalError can be caught and detected with FatalError.is()
  • hookCleanupTestWorkflow - hook token reuse after workflow completion
  • concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
  • stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
  • stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
  • closureVariableWorkflow - nested step functions with closure variables
  • spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
  • health check (queue-based) - workflow and step endpoints respond to health check messages
  • pathsAliasWorkflow - TypeScript path aliases resolve correctly
  • Calculator.calculate - static workflow method using static step methods from another class
  • AllInOneService.processNumber - static workflow method using sibling static step methods
  • ChainableService.processWithThis - static step methods using this to reference the class
  • thisSerializationWorkflow - step function invoked with .call() and .apply()
  • customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
  • instanceMethodStepWorkflow - instance methods with "use step" directive
  • crossContextSerdeWorkflow - classes defined in step code are deserializable in workflow context
  • stepFunctionAsStartArgWorkflow - step function reference passed as start() argument
  • cancelRun - cancelling a running workflow
  • cancelRun via CLI - cancelling a running workflow
  • pages router addTenWorkflow via pages router
  • pages router promiseAllWorkflow via pages router
  • pages router sleepingWorkflow via pages router

Details by Category

❌ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 48 0 4
✅ example 48 0 4
✅ express 48 0 4
✅ fastify 48 0 4
✅ hono 48 0 4
✅ nextjs-turbopack 51 0 1
✅ nextjs-webpack 51 0 1
✅ nitro 48 0 4
❌ nuxt 47 1 4
✅ sveltekit 48 0 4
✅ vite 48 0 4
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 45 0 7
✅ express-stable 45 0 7
✅ fastify-stable 45 0 7
✅ hono-stable 45 0 7
✅ nextjs-turbopack-canary 49 0 3
✅ nextjs-turbopack-stable 49 0 3
✅ nextjs-webpack-canary 49 0 3
✅ nextjs-webpack-stable 49 0 3
✅ nitro-stable 45 0 7
✅ nuxt-stable 45 0 7
✅ sveltekit-stable 45 0 7
✅ vite-stable 45 0 7
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 45 0 7
✅ express-stable 45 0 7
✅ fastify-stable 45 0 7
✅ hono-stable 45 0 7
✅ nextjs-turbopack-canary 49 0 3
✅ nextjs-turbopack-stable 49 0 3
✅ nextjs-webpack-canary 49 0 3
✅ nextjs-webpack-stable 49 0 3
✅ nitro-stable 45 0 7
✅ nuxt-stable 45 0 7
✅ sveltekit-stable 45 0 7
✅ vite-stable 45 0 7
✅ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 45 0 7
✅ express-stable 45 0 7
✅ fastify-stable 45 0 7
✅ hono-stable 45 0 7
✅ nextjs-turbopack-canary 49 0 3
✅ nextjs-turbopack-stable 49 0 3
✅ nextjs-webpack-canary 49 0 3
✅ nextjs-webpack-stable 49 0 3
✅ nitro-stable 45 0 7
✅ nuxt-stable 45 0 7
✅ sveltekit-stable 45 0 7
✅ vite-stable 45 0 7
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 49 0 3
❌ 🌍 Community Worlds
App Passed Failed Skipped
✅ mongodb-dev 3 0 0
❌ mongodb 48 1 3
✅ redis-dev 3 0 0
✅ redis 49 0 3
✅ turso-dev 3 0 0
❌ turso 4 45 3
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 45 0 7
✅ e2e-local-postgres-nest-stable 45 0 7
✅ e2e-local-prod-nest-stable 45 0 7

📋 View full workflow run

❌ Some E2E test jobs failed:

  • Vercel Prod: failure
  • Local Dev: success
  • Local Prod: success
  • Local Postgres: success
  • Windows: success

Check the workflow run for details.

@johnlindquist
docs(foundations): fix testing guide API usage
7ae4f1f 
- Add missing export to step function declarations
- Replace nonexistent getHookByToken() with direct resumeHook(token)
  matching the public API from the Hooks & Webhooks guide
- Replace brittle setTimeout with retry loop for hook delivery
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@johnlindquist

Comments