Add stable Next.js eager and lazy test coverage

.changeset/witty-mails-smile.md

@@ -0,0 +1,5 @@
+---
+"@workflow/next": patch
+---
+
+Allow `WORKFLOW_NEXT_LAZY_DISCOVERY=0` to explicitly disable deferred Next.js discovery

.github/scripts/generate-docs-data.js

@@ -144,7 +144,7 @@ function parseE2EResults(files) {
       // Extract framework from filename for detailed breakdown
       const basename = path.basename(file, '.json');
       const frameworkMatch = basename.match(
-        /-(nextjs-turbopack|nextjs-webpack|nitro|nuxt|sveltekit|vite|hono|express|fastify|astro)(?:-(canary|stable))?$/
+        /-(nextjs-turbopack|nextjs-webpack|nitro|nuxt|sveltekit|vite|hono|express|fastify|astro)(?:-(?:canary|stable(?:-lazy-discovery-(?:enabled|disabled))?))?$/
       );
       if (frameworkMatch) {
         const framework = frameworkMatch[1];

.github/workflows/tests.yml

@@ -253,6 +253,7 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
+      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.canary != true && (matrix.app.name == 'nextjs-turbopack' || matrix.app.name == 'nextjs-webpack') && '0' || '' }}
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -332,7 +333,7 @@ jobs:
         run: echo "matrix=$(node ./scripts/create-test-matrix.mjs)" >> $GITHUB_OUTPUT
 
   e2e-local-dev:
-    name: E2E Local Dev Tests (${{ matrix.app.name }} - ${{ matrix.app.canary && 'canary' || 'stable' }})
+    name: E2E Local Dev Tests (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})
     runs-on: ubuntu-latest
     timeout-minutes: 30
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'workflow-server-test') }}
@@ -345,6 +346,7 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
+      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -382,7 +384,7 @@ jobs:
           cd "${{ steps.prepare-workbench.outputs.workbench_app_path }}" && pnpm dev &
           echo "starting tests in 10 seconds" && sleep 10
           pnpm vitest run packages/core/e2e/dev.test.ts; sleep 10
-          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-dev-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-dev-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
         env:
           NODE_OPTIONS: "--enable-source-maps"
           APP_NAME: ${{ matrix.app.name }}
@@ -393,19 +395,19 @@ jobs:
 
       - name: Generate E2E summary
         if: always()
-        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Dev (${{ matrix.app.name }})" >> $GITHUB_STEP_SUMMARY || true
+        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Dev (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})" >> $GITHUB_STEP_SUMMARY || true
 
       - name: Upload E2E results
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: e2e-results-local-dev-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}
-          path: e2e-local-dev-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          name: e2e-results-local-dev-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}
+          path: e2e-local-dev-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
           retention-days: 7
           if-no-files-found: ignore
 
   e2e-local-prod:
-    name: E2E Local Prod Tests (${{ matrix.app.name }} - ${{ matrix.app.canary && 'canary' || 'stable' }})
+    name: E2E Local Prod Tests (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})
     runs-on: ubuntu-latest
     timeout-minutes: 30
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'workflow-server-test') }}
@@ -418,6 +420,7 @@ jobs:
       TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
       TURBO_TEAM: ${{ vars.TURBO_TEAM }}
       WORKFLOW_PUBLIC_MANIFEST: '1'
+      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -460,7 +463,7 @@ jobs:
         run: |
           cd "${{ steps.prepare-workbench.outputs.workbench_app_path }}" && pnpm start &
           echo "starting tests in 10 seconds" && sleep 10
-          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-prod-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-prod-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
         env:
           NODE_OPTIONS: "--enable-source-maps"
           APP_NAME: ${{ matrix.app.name }}
@@ -470,19 +473,19 @@ jobs:
 
       - name: Generate E2E summary
         if: always()
-        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Prod (${{ matrix.app.name }})" >> $GITHUB_STEP_SUMMARY || true
+        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Prod (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})" >> $GITHUB_STEP_SUMMARY || true
 
       - name: Upload E2E results
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: e2e-results-local-prod-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}
-          path: e2e-local-prod-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          name: e2e-results-local-prod-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}
+          path: e2e-local-prod-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
           retention-days: 7
           if-no-files-found: ignore
 
   e2e-local-postgres:
-    name: E2E Local Postgres Tests (${{ matrix.app.name }} - ${{ matrix.app.canary && 'canary' || 'stable' }})
+    name: E2E Local Postgres Tests (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})
     runs-on: ubuntu-latest
     timeout-minutes: 30
     if: ${{ !contains(github.event.pull_request.labels.*.name, 'workflow-server-test') }}
@@ -512,6 +515,7 @@ jobs:
       WORKFLOW_PUBLIC_MANIFEST: '1'
       WORKFLOW_TARGET_WORLD: "@workflow/world-postgres"
       WORKFLOW_POSTGRES_URL: "postgres://world:world@localhost:5432/world"
+      WORKFLOW_NEXT_LAZY_DISCOVERY: ${{ matrix.app.lazyDiscovery == false && '0' || matrix.app.lazyDiscovery == true && '1' || '' }}
 
     steps:
       - name: Checkout Repo
@@ -557,7 +561,7 @@ jobs:
         run: |
           cd "${{ steps.prepare-workbench.outputs.workbench_app_path }}" && pnpm start &
           echo "starting tests in 10 seconds" && sleep 10
-          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-postgres-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          pnpm run test:e2e --reporter=default --reporter=json --reporter=./packages/core/e2e/github-reporter.ts --outputFile=e2e-local-postgres-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
         env:
           NODE_OPTIONS: "--enable-source-maps"
           APP_NAME: ${{ matrix.app.name }}
@@ -567,14 +571,14 @@ jobs:
 
       - name: Generate E2E summary
         if: always()
-        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Postgres (${{ matrix.app.name }})" >> $GITHUB_STEP_SUMMARY || true
+        run: node .github/scripts/aggregate-e2e-results.js . --job-name "E2E Local Postgres (${{ matrix.app.name }} - ${{ matrix.app.runLabel }})" >> $GITHUB_STEP_SUMMARY || true
 
       - name: Upload E2E results
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: e2e-results-local-postgres-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}
-          path: e2e-local-postgres-${{ matrix.app.name }}-${{ matrix.app.canary && 'canary' || 'stable' }}.json
+          name: e2e-results-local-postgres-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}
+          path: e2e-local-postgres-${{ matrix.app.name }}-${{ matrix.app.artifactSuffix }}.json
           retention-days: 7
           if-no-files-found: ignore
 

packages/core/e2e/dev.test.ts

@@ -1,7 +1,10 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { afterEach, beforeAll, describe, expect, test } from 'vitest';
-import { getWorkbenchAppPath } from './utils';
+import {
+  getWorkbenchAppPath,
+  isNextLazyDiscoveryEnabledForTest,
+} from './utils';
 
 export interface DevTestConfig {
   generatedStepPath: string;
@@ -44,9 +47,11 @@
     );
     const testWorkflowFile = finalConfig.testWorkflowFile ?? '3_streams.ts';
     const workflowsDir = finalConfig.workflowsDir ?? 'workflows';
-    const supportsDeferredStepCopies = generatedStep.includes(
-      path.join('.well-known', 'workflow', 'v1', 'step', 'route.js')
-    );
+    const supportsDeferredStepCopies =
+      isNextLazyDiscoveryEnabledForTest() &&
+      generatedStep.includes(
+        path.join('.well-known', 'workflow', 'v1', 'step', 'route.js')
+      );
     const restoreFiles: Array<{ path: string; content: string }> = [];
 
     const fetchWithTimeout = (pathname: string) => {
@@ -127,7 +132,7 @@
           : lastError
             ? ` Last error: ${String(lastError)}`
             : '';
       throw new Error(
         `Timed out after ${timeoutMs}ms waiting for ${description}.${lastErrorSuffix}`
       );
     };

packages/core/e2e/local-build.test.ts

@@ -3,7 +3,10 @@
 import path from 'node:path';
 import { describe, expect, test } from 'vitest';
 import { usesVercelWorld } from '../../utils/src/world-target';
-import { getWorkbenchAppPath } from './utils';
+import {
+  getWorkbenchAppPath,
+  isNextLazyDiscoveryEnabledForTest,
+} from './utils';
 
 interface CommandResult {
   stdout: string;
@@ -52,7 +55,7 @@
           ? `signal ${signal}`
           : `exit code ${String(code)}`;
         reject(
           new Error(
             `Command "${command} ${args.join(' ')}" failed with ${exitInfo}\n${output}`
           )
         );
@@ -119,7 +122,10 @@
 
     expect(result.output).not.toContain('Error:');
 
-    if (DEFERRED_BUILD_MODE_PROJECTS.has(project)) {
+    if (
+      DEFERRED_BUILD_MODE_PROJECTS.has(project) &&
+      isNextLazyDiscoveryEnabledForTest()
+    ) {
       const deferredBuildSupported = !result.output.includes(
         DEFERRED_BUILD_UNSUPPORTED_WARNING
       );

packages/core/e2e/utils.ts

@@ -5,6 +5,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { createVercelWorld } from '@workflow/world-vercel';
 import { onTestFailed } from 'vitest';
+import { parseEnvironmentFlag } from '../../next/src/environment-flag.js';
 import type { Run } from '../src/runtime';
 import { getWorld, setWorld } from '../src/runtime';
 
@@ -19,6 +20,10 @@ function splitArgs(raw: string): string[] {
   return value.split(/\s+/);
 }
 
+export function isNextLazyDiscoveryEnabledForTest(): boolean {
+  return parseEnvironmentFlag(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY) ?? true;
+}
+
 export function getWorkbenchAppPath(overrideAppName?: string): string {
   const explicitWorkbenchPath = process.env.WORKBENCH_APP_PATH;
   const appName = process.env.APP_NAME ?? overrideAppName;

packages/next/src/builder.test.ts

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { shouldUseDeferredBuilder } from './builder.js';
+import { parseEnvironmentFlag } from './environment-flag.js';
+
+const originalLazyDiscoveryEnv = process.env.WORKFLOW_NEXT_LAZY_DISCOVERY;
+
+afterEach(() => {
+  if (originalLazyDiscoveryEnv === undefined) {
+    delete process.env.WORKFLOW_NEXT_LAZY_DISCOVERY;
+  } else {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = originalLazyDiscoveryEnv;
+  }
+});
+
+describe('shouldUseDeferredBuilder', () => {
+  it('treats WORKFLOW_NEXT_LAZY_DISCOVERY=0 as disabled', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '0';
+
+    expect(shouldUseDeferredBuilder('16.2.1')).toBe(false);
+  });
+
+  it('treats WORKFLOW_NEXT_LAZY_DISCOVERY=false as disabled', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = 'false';
+
+    expect(shouldUseDeferredBuilder('16.2.1')).toBe(false);
+  });
+
+  it('treats WORKFLOW_NEXT_LAZY_DISCOVERY=off as disabled', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = 'off';
+
+    expect(parseEnvironmentFlag(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY)).toBe(
+      false
+    );
+    expect(shouldUseDeferredBuilder('16.2.1')).toBe(false);
+  });
+
+  it('enables deferred mode for compatible versions when the env is enabled', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '1';
+
+    expect(shouldUseDeferredBuilder('16.2.1')).toBe(true);
+  });
+});

packages/next/src/builder.ts

@@ -1,6 +1,7 @@
 import semver from 'semver';
 import { getNextBuilderDeferred } from './builder-deferred.js';
 import { getNextBuilderEager } from './builder-eager.js';
+import { parseEnvironmentFlag } from './environment-flag.js';
 
 export const DEFERRED_BUILDER_MIN_VERSION = '16.2.0-canary.48';
 
@@ -13,7 +14,8 @@ export const WORKFLOW_DEFERRED_ENTRIES = [
 let warnedAboutFlagAndVersion = false;
 
 export function shouldUseDeferredBuilder(nextVersion: string): boolean {
-  const flagEnabled = Boolean(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY);
+  const flagEnabled =
+    parseEnvironmentFlag(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY) ?? false;
   const versionCompatible = semver.gte(
     nextVersion,
     DEFERRED_BUILDER_MIN_VERSION

packages/next/src/environment-flag.ts

@@ -0,0 +1,16 @@
+const FALSE_ENV_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+export function parseEnvironmentFlag(
+  rawValue: string | undefined
+): boolean | undefined {
+  const normalizedValue = rawValue?.trim().toLowerCase();
+  if (!normalizedValue) {
+    return undefined;
+  }
+
+  if (FALSE_ENV_VALUES.has(normalizedValue)) {
+    return false;
+  }
+
+  return true;
+}

packages/next/src/index.test.ts

@@ -109,4 +109,34 @@ describe('withWorkflow outputFileTracingRoot', () => {
       workingDir: process.cwd(),
     });
   });
+
+  it('preserves an explicit lazyDiscovery disable override', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '0';
+
+    withWorkflow(
+      {},
+      {
+        workflows: {
+          lazyDiscovery: true,
+        },
+      }
+    );
+
+    expect(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY).toBe('0');
+  });
+
+  it('treats an empty lazyDiscovery env override as unset', () => {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '';
+
+    withWorkflow(
+      {},
+      {
+        workflows: {
+          lazyDiscovery: true,
+        },
+      }
+    );
+
+    expect(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY).toBe('1');
+  });
 });

packages/next/src/index.ts

@@ -1,5 +1,6 @@
 import type { NextConfig } from 'next';
 import semver from 'semver';
+import { parseEnvironmentFlag } from './environment-flag.js';
 import {
   getNextBuilder,
   shouldUseDeferredBuilder,
@@ -61,8 +62,17 @@ export function withWorkflow(
     };
   } = {}
 ) {
-  if (workflows?.lazyDiscovery) {
-    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '1';
+  const lazyDiscoveryOverride = parseEnvironmentFlag(
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY
+  );
+  if (lazyDiscoveryOverride === undefined) {
+    if (workflows?.lazyDiscovery) {
+      process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = '1';
+    }
+  } else {
+    process.env.WORKFLOW_NEXT_LAZY_DISCOVERY = lazyDiscoveryOverride
+      ? '1'
+      : '0';
   }
 
   if (!process.env.VERCEL_DEPLOYMENT_ID) {

packages/next/src/loader.ts

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { connect, type Socket } from 'node:net';
 import { dirname, join, relative } from 'node:path';
 import { transform } from '@swc/core';
+import { parseEnvironmentFlag } from './environment-flag.js';
 import {
   parseMessage,
   type SocketMessage,
@@ -687,11 +688,15 @@ export default function workflowLoader(
 
     // Detect workflow patterns in the source code.
     const patterns = await detectPatterns(sourceForTransform);
-    // Always notify discovery tracking, even for `false/false`, so files that
-    // previously had workflow/step usage are removed from the tracked sets.
-    // Deferred step copy files must report using their original source path so
-    // deferred rebuilds can react to source edits outside generated artifacts.
-    if (!isDeferredStepCopyFile || deferredStepSourceMetadata?.absolutePath) {
+    const shouldTrackDeferredDiscovery =
+      parseEnvironmentFlag(process.env.WORKFLOW_NEXT_LAZY_DISCOVERY) ?? false;
+
+    // Discovery tracking is only needed for deferred builds. Eager builds
+    // discover inputs up front and should ignore any stale socket metadata.
+    if (
+      shouldTrackDeferredDiscovery &&
+      (!isDeferredStepCopyFile || deferredStepSourceMetadata?.absolutePath)
+    ) {
       const hasSerde = patterns.hasSerde;
       const nextPatternState: DiscoveredPatternState = {
         hasWorkflow: patterns.hasUseWorkflow,