Files
e2e/scripts/check-docs-examples.ts
Donny/강동윤andClaude Sonnet 5.5 d88aa99e0f docs: add a Next.js guide page (#1952)
* docs: add a Next.js guide page

One page takes a Next.js developer from `e2e init` to CI: `next dev`
locally and `next start` on the build in CI from one config, the port,
`reuseExisting`, and the Next.js problems (`allowedDevOrigins` on
127.0.0.1, the route announcer that `getByRole('alert')` also matches, a
webpack watcher that reads `.e2e/`), plus the `create-next-app` starter
and the Vercel template. The hydration accordion moves here from web.mdx;
web, cache, and example-projects link to the page, with ja and zh
translations, and the e2e skill's setup reference carries the same
guidance.

Refs ENG-1378

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: move the Next.js page into a Frameworks group

Next.js is not a platform like web, mobile, or desktop, so the page moves
to docs/frameworks/nextjs.mdx under a new Frameworks navigation group. The
web page no longer points at it from the app URL paragraph.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-20 10:14:53 +00:00

116 lines
5.8 KiB
TypeScript

/**
* Asserts that every code block a docs page or the consumer skill shows from
* `docs/examples/` matches the file it came from, and that every example file
* is shown somewhere.
*
* The examples are typechecked against the built packages (`pnpm --filter
* @e2e-dev/docs typecheck`); a page cannot import a file and a
* skill is plain markdown, so the page carries a copy of each and this script
* keeps the copies honest.
*
* The map below names which page shows each example, and is the only place
* that knows it; the file list is read from the filesystem (`docs-examples.ts`)
* rather than trusted to the map, so an example added without a page is
* reported instead of silently unchecked.
*
* Usage: `node scripts/check-docs-examples.ts`. Exits 1 listing every block
* that drifted from its example, and every example no page shows.
*/
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { unmappedExamples } from './docs-examples.ts';
const ROOT = fileURLToPath(new URL('..', import.meta.url));
/** Example file to the page that shows it verbatim. */
const EXAMPLES: Record<string, string> = {
'docs/examples/vercel/e2e.config.ts': 'docs/ci/vercel-previews.mdx',
'docs/examples/browser-run/e2e.config.ts': 'docs/integrations/browser-run.mdx',
'docs/examples/runner/run.ts': 'docs/reference/runner.mdx',
'docs/examples/core/prices.ts': 'docs/core.mdx',
'docs/examples/core/checkout.ts': 'docs/core.mdx',
'docs/examples/runner/explore.ts': 'docs/reference/runner.mdx',
'docs/examples/limrun/e2e.config.ts': 'docs/integrations/limrun.mdx',
'docs/examples/limrun/greeting.e2e.ts': 'docs/integrations/limrun.mdx',
'docs/examples/quickstart/e2e.config.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/tests/example.e2e.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/tests/agent.e2e.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/mobile/e2e.config.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/mobile/tests/example.e2e.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/mobile/tests/agent.e2e.ts': 'docs/quickstart.mdx',
'docs/examples/quickstart/e2e.command.config.ts': 'docs/web.mdx',
'docs/examples/nextjs/e2e.config.ts': 'docs/frameworks/nextjs.mdx',
'docs/examples/quickstart/e2e.common.config.ts': 'docs/quickstart.mdx',
'docs/examples/javascript/e2e.config.js': 'docs/reference/config.mdx',
'docs/examples/mobile/device-provider.ts': 'docs/mobile.mdx',
'docs/examples/mobile/device-cloud-provider.ts': 'docs/mobile.mdx',
'docs/examples/mobile/testmu.config.ts': 'docs/integrations/testmu.mdx',
'docs/examples/mobile/testmu.e2e.ts': 'docs/integrations/testmu.mdx',
'docs/examples/mobile/browserstack.config.ts': 'docs/integrations/browserstack.mdx',
'docs/examples/mobile/browserstack.e2e.ts': 'docs/integrations/browserstack.mdx',
'docs/examples/mobile/e2b.config.ts': 'docs/integrations/e2b.mdx',
'docs/examples/web/browser-provider.ts': 'docs/browser.mdx',
'docs/examples/web/moli.config.ts': 'docs/integrations/moli.mdx',
'docs/examples/web/testmu-browsers.config.ts': 'docs/integrations/testmu.mdx',
'docs/examples/web/e2b-browsers.config.ts': 'docs/integrations/e2b.mdx',
'docs/examples/web/e2b-template.ts': 'docs/integrations/e2b.mdx',
'docs/examples/appium/e2e.config.ts': 'docs/migrate/appium.mdx',
'docs/examples/appium/tests/login.e2e.ts': 'docs/migrate/appium.mdx',
'docs/examples/appium/tests/order-link.e2e.ts': 'docs/migrate/appium.mdx',
'docs/examples/fixtures/tests/fixtures.ts': 'docs/fixtures.mdx',
'docs/examples/fixtures/tests/tasks.e2e.ts': 'docs/fixtures.mdx',
'docs/examples/models/e2e.decision.config.ts': 'docs/decision-models.mdx',
'docs/examples/models/tests/decision.e2e.ts': 'docs/decision-models.mdx',
'docs/examples/page-objects/tests/pages/sign-in-page.ts': 'docs/page-object-model.mdx',
'docs/examples/page-objects/tests/fixtures.ts': 'docs/page-object-model.mdx',
'docs/examples/page-objects/tests/sign-in.e2e.ts': 'docs/page-object-model.mdx',
'docs/examples/filters/e2e.config.ts': 'docs/filters.mdx',
'docs/examples/filters/areas-filter.ts': 'docs/filters.mdx',
'docs/examples/filters/e2e.areas.config.ts': 'docs/filters.mdx',
'docs/examples/filters/tuned-filter.ts': 'docs/filters.mdx',
'docs/examples/skill/e2e.config.ts': 'skills/e2e/SKILL.md',
'docs/examples/skill/e2e.setup.config.ts': 'skills/e2e/references/setup.md',
};
function read(path: string): string {
return readFileSync(join(ROOT, path), 'utf8');
}
/** The bodies of every fenced code block on the page, with the fence's indentation removed. */
function codeBlocks(text: string): string[] {
return [...text.matchAll(/^( *)```[^\n]*\n([\s\S]*?)^\1```$/gm)].map(([, indent, body]) =>
body!
.split('\n')
.map((line) => (line.startsWith(indent!) ? line.slice(indent!.length) : line))
.join('\n')
.trimEnd(),
);
}
function main(): number {
const problems: string[] = [];
// Every example file must be shown somewhere; the map is only trusted for
// where, never for whether one exists at all.
for (const file of unmappedExamples(Object.keys(EXAMPLES))) {
problems.push(`${file}: no page shows this example; add it to EXAMPLES and show it on the appropriate page`);
}
const blocks = new Map<string, string[]>();
for (const [example, page] of Object.entries(EXAMPLES)) {
const pageBlocks = blocks.get(page) ?? codeBlocks(read(page));
blocks.set(page, pageBlocks);
if (!pageBlocks.includes(read(example).trimEnd())) problems.push(`${page}: no code block matches ${example}`);
}
if (problems.length > 0) {
process.stderr.write(`${problems.join('\n')}\n`);
return 1;
}
const pages = new Set(Object.values(EXAMPLES));
process.stdout.write(
`docs examples: ${Object.keys(EXAMPLES).length} files shown verbatim in ${[...pages].join(', ')}\n`,
);
return 0;
}
process.exitCode = main();