diff --git a/.changeset/init-ci-workflow.md b/.changeset/init-ci-workflow.md new file mode 100644 index 0000000000..905fd0f9ef --- /dev/null +++ b/.changeset/init-ci-workflow.md @@ -0,0 +1,5 @@ +--- +"e2e": patch +--- + +`e2e init` can write a CI pipeline: a GitHub Actions workflow or a GitLab CI/CD file with one job for each platform the config's targets run on. Web targets run in a web job; iOS and Android targets get their own jobs, which build the app, boot a simulator or an emulator, and install the app. A config with both gets all of its jobs. The wizard asks for it in a project with the web or mobile engine and preselects the service the repository points to; `--ci github-actions` or `--ci gitlab` answers the question, and `--yes` alone writes none. The mobile jobs build Expo and bare React Native apps; any other app gets a build step to replace. GitLab's mobile jobs need self-managed runners. The jobs use the project's package manager and Node version and keep the report; for a project in a subfolder the file goes to the repository root. `init` names the secret or CI/CD variable to add and warns about what would fail on the first push. It never overwrites a pipeline file: beside an existing `.gitlab-ci.yml` it writes `.gitlab/e2e.gitlab-ci.yml` and prints the `include:` to add. diff --git a/docs/ci/github-actions.mdx b/docs/ci/github-actions.mdx index 624338f7d9..8cf9dbcf3c 100644 --- a/docs/ci/github-actions.mdx +++ b/docs/ci/github-actions.mdx @@ -17,6 +17,9 @@ export const setupPrompt = `Add a GitHub Actions workflow that runs this project These two workflows run web targets, and iOS and Android targets. For CI defaults, model keys, and exit codes, see [Continuous integration](/ci). +`e2e init --ci github-actions` writes these jobs for your targets and +package manager, with the build for an Expo or bare React Native app; see +[CI pipeline](/reference/cli#ci-pipeline). diff --git a/docs/ci/gitlab.mdx b/docs/ci/gitlab.mdx index 7a97142507..2313db760e 100644 --- a/docs/ci/gitlab.mdx +++ b/docs/ci/gitlab.mdx @@ -16,6 +16,9 @@ export const setupPrompt = `Add a GitLab CI/CD pipeline that runs this project's These jobs run web targets on GitLab's hosted Linux runners, and iOS and Android targets on your own runners. For CI defaults, model keys, and exit codes, see [Continuous integration](/ci). +`e2e init --ci gitlab` writes these jobs for your targets and package +manager, with the build for an Expo or bare React Native app; see +[CI pipeline](/reference/cli#ci-pipeline). diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index 2dae31d5c9..27576c4a78 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -111,13 +111,14 @@ bunx e2e init --yes --gateway openrouter --skills .agents/skills --mcp .mcp.json | Option | Description | | --- | --- | | `[directory]` | Where to scaffold; created when missing. Default: the working directory. | -| `-y`, `--yes` | Skips the prompts. Each answer not given as a flag takes its default: Web engine, Vercel AI Gateway, skill and MCP config in both locations, no install. | +| `-y`, `--yes` | Skips the prompts. Each answer not given as a flag takes its default: Web engine, Vercel AI Gateway, skill and MCP config in both locations, no CI pipeline, no install. | | `--example ` | Starts from an example app: `with-vite`, `with-next`, `with-astro`, `with-angular`, `with-expo`, `with-swiftui`, `with-compose`, `with-kotlin-multiplatform`, `with-flutter`, or `with-maui`. The `with-` prefix is optional. See [Starting from an example](#starting-from-an-example). | | `--engine ` | The engines for a new config: `web`, `mobile`, or `none`. Comma-separated or repeated; `web,mobile` writes a target for each. Default: asked. | | `--gateway ` | The model gateway for agent steps in a new config: `vercel`, `openrouter`, `openai-compatible`, `chatgpt`, `copilot`, `opencode-console`, `grok`, or `none`. Default: asked. | | `--endpoint ` | Base URL for `--gateway openai-compatible`, and implies it. HTTPS, or HTTP on a loopback host. Default: asked; `http://127.0.0.1:11434/v1` with `--yes`. | | `--skills ` | Where to install the agent skill: `.agents/skills`, `.claude/skills`, or `none`. Comma-separated or repeated. Default: asked. | | `--mcp ` | Where to register the MCP server: `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, or `none`. Comma-separated or repeated. Default: asked. | +| `--ci ` | The CI pipeline for the tests, one job per platform: `github-actions`, `gitlab`, or `none`. See [CI pipeline](#ci-pipeline). Default: asked; `none` with `--yes`. | | `--install`, `--no-install` | Whether to install dependencies. Default: asked; `--no-install` with `--yes`. | - A flag answers its question and skips that prompt. @@ -160,6 +161,10 @@ For a new project, the wizard asks for: Claude Code, `.cursor/mcp.json` for Cursor, `.codex/config.toml` for Codex. All are preselected. Codex loads the config in trusted projects; start a new session after installing dependencies. +- **A CI pipeline** for a project with the web or mobile engine: GitHub + Actions or GitLab CI/CD, with a job for each platform. The wizard + preselects the service the repository's remote, `.github/` folder, or + `.gitlab-ci.yml` points to. See [CI pipeline](#ci-pipeline). After you confirm the file changes, the wizard asks whether to install the selected dependencies. The installer follows the project's `packageManager` @@ -175,6 +180,87 @@ field or lockfile, then the invoking package manager, then npm. | `.gitignore` | Appends `node_modules/`, `.e2e/results/`, `.e2e/cache/`, `.e2e/sessions/`, `.e2e/report.json`, `.e2e/ai-trace.json`, `.e2e/timings.json`, `.e2e/junit.xml`, `.e2e/summary.md`, `.e2e/logs/`, and `.e2e/videos/`. Committing the cache is opt-in; see [commit the replay cache](/cache#commit-the-replay-cache) | | `.agents/skills/e2e/`, `.claude/skills/e2e/` | `SKILL.md` and one `references/.md` per `e2e guide` topic. With both chosen, the Claude Code directory is a relative symlink (`../../.agents/skills/e2e`) to the copy, the layout `npx skills add` produces | | `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml` | Registers `e2e mcp` without changing other servers | +| `.github/workflows/e2e.yml`, `.gitlab-ci.yml` | With `--ci`: a job for each platform the targets run on. At the repository root, also for a project in a subfolder. See [CI pipeline](#ci-pipeline) | + + +##### CI pipeline + +`--ci github-actions` or `--ci gitlab` writes a pipeline with one job for +each platform the config's targets run on: web, iOS, and Android. A config +with web and mobile targets gets all of its jobs in one file. Each job +installs the dependencies, runs `e2e run --target --reporter +list,junit`, and keeps `.e2e/report.json`, `.e2e/junit.xml`, and +`.e2e/results/`. + + +```bash npm +npx e2e init --yes --ci gitlab +``` + +```bash pnpm +pnpm dlx e2e init --yes --ci gitlab +``` + +```bash bun +bunx e2e init --yes --ci gitlab +``` + + +| Job | GitHub Actions | GitLab CI/CD | +| --- | --- | --- | +| Web | `ubuntu-latest`, with Chromium | The `node` image on GitLab's runners, with Chromium | +| iOS | `macos-26`: builds the app, boots the image's iPhone 17 Pro on a pinned iOS runtime, installs the app | A self-managed Mac: creates a simulator of its own on a pinned runtime | +| Android | `ubuntu-latest` with KVM: builds a release APK, runs it on an API 36 emulator | A self-managed Linux runner with KVM: boots an AVD named `e2e` | + +| Service | File | Runs | Model key | +| --- | --- | --- | --- | +| GitHub Actions | `.github/workflows/e2e.yml` | On pull requests and pushes to `main` | A repository secret, passed in the run step's `env` | +| GitLab CI/CD | `.gitlab-ci.yml` | In merge request pipelines and on the default branch. The JUnit report shows in the merge request | A CI/CD variable, which GitLab gives the job | + +- `init` reads the targets from the new config it writes, or loads an + existing one the way `e2e run` does, after you confirm the changes and + after the install. When an existing config still doesn't load, `init` says + why and falls back to `package.json`: with only the web engine, one web job + runs every target; with the mobile engine, there's no pipeline. +- The web job runs every target that isn't iOS or Android, HTTP tests + included, and all of them when the config has no mobile target. +- The mobile jobs build the app. An Expo app builds with `expo run:ios` and + `expo prebuild` and Gradle. A bare React Native app builds its + `ios/*.xcworkspace` with `xcodebuild` (through Bundler with a `Gemfile`) + and runs `android/gradlew`. Any other app gets a build step that fails + until you replace it, and `init` names the file to edit. +- The mobile jobs name the device they booted in `E2E_DEVICE`. A target + that names a device reads it with `device: process.env.E2E_DEVICE` in + `mobile()`, so the run drives that device. A target that names none drives + the booted one. +- GitLab's hosted runners can't run a simulator or an emulator, so its + mobile jobs need self-managed runners: set their `tags`. See + [GitLab CI/CD](/ci/gitlab#ios-and-android). +- The file starts from a template the package ships in `templates/ci/`, a + complete pipeline for npm at the repository root and an Expo app. `init` + fills it in for your project and keeps its comments. +- The jobs use the project's package manager, and the Node version in + `.nvmrc` or `.node-version` (24 without one). GitHub reads the file, so it + gets the exact version. GitLab runs the web job in the `node` image of the + file's major version: `node:22` for `22.22.3`. GitHub actions are pinned by + commit. +- `init` names the secret or variable to add, such as `AI_GATEWAY_API_KEY`, + with the `gh` or `glab` command that adds it. +- For a project in a subfolder, the file goes to the repository root and the + jobs run in the subfolder. +- `init` warns when the config has no `app.command`, since nothing else + starts the app on the runner. It also warns about a subscription gateway, + whose sign-in stays on your machine, and an OpenAI-compatible `baseURL` on + your machine: agent steps fail in CI with either. +- An existing pipeline file stays unchanged. Beside an existing + `.gitlab-ci.yml`, `init` writes `.gitlab/e2e.gitlab-ci.yml` and prints the + `include:` lines to add. The jobs run in the `test` stage, and `init` says + when your `stages:` leave it out. Beside a job named like one of them + (`e2e-web`, `e2e-ios`, `e2e-android`), every job's name gets `-run`. +- `init` never writes through a symlinked `.github` or `.gitlab` folder. It + warns and writes nothing. +- A workflow or `.gitlab-ci.yml` that already runs `e2e run` gets nothing, + and neither does a project without the web or mobile engine. ##### Starting from an example diff --git a/docs/telemetry.mdx b/docs/telemetry.mdx index ecd1d09257..2ab8d2e535 100644 --- a/docs/telemetry.mdx +++ b/docs/telemetry.mdx @@ -120,6 +120,7 @@ own tools count together as `tool`, and any other name as `other`. | `example` | The `--example` name (`with-vite`, `with-expo`, ...), `null` without the flag | | `engine`, `gateway` | The ids of the engines and the model gateway chosen for a new config (`web`, `mobile`, `web,mobile`, `none`; `vercel`, `openrouter`, `openai-compatible`, `chatgpt`, `copilot`, `opencode-console`, `grok`, `none`), `null` when not asked. Never the endpoint typed for an OpenAI-compatible gateway | | `skill`, `mcp`, `install` | Whether the agent skill, the MCP registration, and the dependency install were chosen | +| `ci` | The CI pipeline chosen (`github-actions`, `gitlab`, or `none`), `null` when not asked | diff --git a/packages/core/src/config/targets.ts b/packages/core/src/config/targets.ts index 5d24eccfc7..bdda6ae9df 100644 --- a/packages/core/src/config/targets.ts +++ b/packages/core/src/config/targets.ts @@ -77,7 +77,7 @@ export function resolveTargets( ); } const platform = resolvePlatform(target, where); - const name = target.name === undefined ? platform : target.name; + const name = targetName(target, platform); if (typeof name !== 'string' || !TARGET_NAME_PATTERN.test(name)) { const source = target.name === undefined ? ' (defaulted from the platform)' : ''; throw new ConfigurationError( @@ -156,13 +156,18 @@ export function digestTargets(targets: readonly ResolvedTarget[]) { })); } +/** A target's name: its own, else its platform's, so one unnamed target per platform needs none. */ +export function targetName(target: Target, platform: string): unknown { + return target.name === undefined ? platform : target.name; +} + /** * The target's platform: its own label, else the engine's declaration. Tool * packs are offered by the engine's platform while tests filter by the * target's, so a target that names one while its engine declares another is a * mistake, not an override. */ -function resolvePlatform(target: Target, where: string): string { +export function resolvePlatform(target: Target, where: string): string { const declared = target.platform; if (declared !== undefined && (typeof declared !== 'string' || declared.trim() === '')) { throw new ConfigurationError('INVALID_CONFIG', `${where} platform must be a non-empty string`); diff --git a/packages/e2e/package.json b/packages/e2e/package.json index 27a75a29f6..a809998493 100644 --- a/packages/e2e/package.json +++ b/packages/e2e/package.json @@ -80,6 +80,7 @@ "dist", "docs", "schema/*.schema.json", + "templates", "skills", "NOTICE" ], @@ -105,6 +106,7 @@ "oxc-transform": "0.158.0", "picocolors": "1.1.1", "toml-eslint-parser": "1.0.3", + "yaml": "^2.9.0", "zod": "4.6.7" }, "peerDependencies": { diff --git a/packages/e2e/src/cli/index.ts b/packages/e2e/src/cli/index.ts index 956737e8c1..6b315d84cd 100644 --- a/packages/e2e/src/cli/index.ts +++ b/packages/e2e/src/cli/index.ts @@ -550,6 +550,7 @@ function createProgram(version: string, telemetry: Telemetry, updateCheck: Updat 'e2e init my-app --example with-expo', 'e2e init --yes', 'e2e init --yes --gateway openrouter --skills .agents/skills --mcp none --install', + 'e2e init --yes --ci github-actions', ]), '', docsLine('/reference/cli'), diff --git a/packages/e2e/src/cli/init.ts b/packages/e2e/src/cli/init.ts index 3c5e92bc77..1fab9d8e78 100644 --- a/packages/e2e/src/cli/init.ts +++ b/packages/e2e/src/cli/init.ts @@ -5,7 +5,13 @@ import { spawnSync } from 'node:child_process'; import { existsSync, mkdirSync, readFileSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs'; import os from 'node:os'; import path from 'node:path'; -import { detectPackageManager, execCommand, runScriptCommand } from '../internal/package-manager.ts'; +import { + detectPackageManager, + detectWorkspacePackageManager, + execCommand, + readPackageManifest, + runScriptCommand, +} from '../internal/package-manager.ts'; import { CONFIG_NAMES, JS_CONFIG_NAMES } from '../config/names.ts'; import { DOCS_URL } from './docs-url.ts'; import { @@ -20,11 +26,34 @@ import { splitSkillDirs, type SkillInstall, } from './init/agent-skill.ts'; -import { getEnginePresets, DEFAULT_ENGINE_IDS, type EngineId } from './init/engines.ts'; +import { + CI_SERVICES, + ciJobs, + configStartsApp, + configTargets, + configUsesLocalModel, + detectCiService, + detectMobileBuilds, + findNodeVersionFile, + findRepositoryRoot, + gatewaysInConfig, + getCiService, + GITLAB_PIPELINE, + posixRelative, + readNodeMajor, + type CiChoice, + type CiFile, + type CiJobs, + type CiService, + type CiTarget, +} from './init/ci.ts'; +import { loadConfigModule } from '../config/load.ts'; +import { getEnginePreset, getEnginePresets, DEFAULT_ENGINE_IDS, type EngineId } from './init/engines.ts'; import { copyExample, ExampleCopyCancelled, ExampleDownloadError, findExample, isEmptyDirectory, type ExampleCopy } from './init/examples.ts'; import { DEFAULT_ENDPOINT, GATEWAYS, getGatewayPreset, validateEndpoint, type GatewayId } from './init/gateways.ts'; -import { findRegisteredMcpFiles, MCP_LOCATIONS, planMcpRegistration } from './init/mcp-config.ts'; -import { addDependencies, addScripts, describeManifestError, readPackage, serializePackage } from './init/package.ts'; +import { isLoopbackHost } from '@e2e-dev/core/lib/internal/urls'; +import { findRegisteredMcpFiles, linkOnPath, MCP_LOCATIONS, planMcpRegistration } from './init/mcp-config.ts'; +import { addDependencies, addScripts, declaresDependency, describeManifestError, readPackage, serializePackage } from './init/package.ts'; import { createScaffold, type ScaffoldModel } from './init/scaffold.ts'; import { MISSING_SKILL_MESSAGE, readSkillFiles } from './skill.ts'; import { playWordmark } from './wordmark.ts'; @@ -59,6 +88,12 @@ export interface InitOptions { skills?: readonly string[]; mcp?: readonly string[]; install?: boolean; + /** + * The CI pipeline to write for the web targets; `none` writes none. Not + * asked when the project has no web engine or e2e already runs in CI, and + * `--yes` alone writes none, since a pipeline runs on the next push. + */ + ci?: CiChoice; /** * The e2e command the caller runs once init has scaffolded, as words, such * as `['e2e', 'explore', 'Check the cart']`. The closing `Next:` line ends @@ -97,7 +132,7 @@ const DEFAULT_GATEWAY: GatewayId = 'vercel'; export type GatewayChoice = GatewayId | 'none'; /** The wizard's answers, each from a flag, an earlier run, or `--yes`; a missing one is asked. */ -type Answers = Pick; +type Answers = Pick; /** * Runs `e2e init`. Every prompt happens before the first write, existing @@ -122,6 +157,7 @@ export async function init(root: string, options: InitOptions = {}): Promise dir), mcp: MCP_LOCATIONS.map(({ file }) => file), install: false, + ci: 'none', } : {}; const foundSkillDirs = findInstalledSkillDirs(cwd); @@ -227,6 +264,7 @@ export async function init(root: string, options: InitOptions = {}): Promise 0 ? foundSkillDirs : defaults.skills), mcp: options.mcp ?? (foundMcpFiles.length > 0 ? foundMcpFiles : defaults.mcp), install: options.install ?? defaults.install, + ci: options.ci ?? defaults.ci, }; // Engine and model gateway are choices for a new config only; an existing config keeps its own dependencies. @@ -338,6 +376,40 @@ export async function init(root: string, options: InitOptions = {}): Promise `${name} (${command})`).join(', ')}`); } + const repositoryRoot = findRepositoryRoot(cwd, root); + // A new config's engines are the ones just chosen; an existing config's are the ones its package.json declares. + const engineInstalled = existingConfig === undefined + ? engines.length > 0 + : declaresDependency(manifest, '@e2e-dev/web') || declaresDependency(manifest, '@e2e-dev/mobile'); + // Asked once: a later run finds e2e already running in some service's pipeline and leaves the question out. + const setUp = CI_SERVICES.some((service) => service.locate(repositoryRoot).existing); + let ci: CiChoice = 'none'; + if (engineInstalled && (given.ci !== undefined || !setUp)) { + const chosen = given.ci ?? await clack.select({ + message: 'Add a CI pipeline that runs the tests?', + initialValue: detectCiService(repositoryRoot) ?? 'none', + options: [ + ...CI_SERVICES.map(({ id, label, hint }) => ({ value: id, label, hint })), + { value: 'none', label: 'None', hint: `another CI service: ${DOCS_URL}/ci` }, + ], + }); + if (isCancelled(chosen)) return cancel(); + ci = chosen; + facts.ci = ci; + } else if (!engineInstalled && options.ci !== undefined && options.ci !== 'none') { + clack.log.warn(`Ignoring --ci: init writes a pipeline for web, iOS, and Android targets, and the project has none; see ${DOCS_URL}${getCiService(options.ci).docs}`); + } + const ciService = ci === 'none' ? undefined : getCiService(ci); + const ciFile = ciService?.locate(repositoryRoot); + const ciRelative = ciFile === undefined ? '' : posixRelative(cwd, path.join(repositoryRoot, ciFile.file)); + if (ciFile?.existing === true) clack.log.warn(`Exists, not touching: ${ciRelative}`); + // Nothing is written through a symlink: a linked .github or .gitlab could put the file outside the repository. + const ciLink = ciFile === undefined || ciFile.existing ? undefined : linkOnPath(repositoryRoot, path.join(repositoryRoot, ciFile.file)); + if (ciLink !== undefined) clack.log.warn(`Symlink, not touching: ${ciLink.relative} -> ${ciLink.target} (${ciRelative})`); + const existingConfigText = existingConfig === undefined ? undefined : readFileSync(path.join(cwd, existingConfig), 'utf8'); + // Where the pipeline goes is known now; its jobs come from the config's targets, read once the dependencies are in. + const writesCi = ciService !== undefined && ciFile !== undefined && !ciFile.existing && ciLink === undefined; + // An example's package.json, config, and tests stay as the example has them. const files = example !== undefined ? [] : [ ...(pkg.original === undefined || dependencies.additions.length > 0 || scripts.length > 0 @@ -347,7 +419,10 @@ export async function init(root: string, options: InitOptions = {}): Promise ({ ...test, existing: false })), ]; - if (example === undefined && files.length === 0 && skillInstalls.length === 0 && mcpRegistrations.length === 0 && missingIgnore.length === 0) { + if ( + example === undefined && files.length === 0 && skillInstalls.length === 0 && mcpRegistrations.length === 0 && missingIgnore.length === 0 + && !writesCi + ) { clack.outro('Nothing to create; project already initialized'); return done('already-initialized', 0); } @@ -361,6 +436,7 @@ export async function init(root: string, options: InitOptions = {}): Promise 0 ? 'Replace' : install.existing ? 'Update' : 'Create'} ${install.relative}/`), ...mcpRegistrations.map((registration) => `${registration.existing ? 'Update' : 'Create'} ${registration.relative}`), ...(missingIgnore.length > 0 ? ['Update .gitignore'] : []), + ...(writesCi ? [`Create ${ciRelative}`] : []), ]; // One change per line: a dozen paths in one sentence is unreadable. clack.log.info(['Changes:', ...actions.map((action) => ` - ${action}`)].join('\n')); @@ -419,15 +495,27 @@ export async function init(root: string, options: InitOptions = {}): Promise getEnginePreset(id).platform).map((platform) => ({ name: platform, platform })), + dependsOn: (name) => declaresDependency(manifest, name), + }); + } + if (installed !== undefined && (installed.error !== undefined || installed.status !== 0)) { + const reason = installed.error?.message ?? `exit ${installed.status ?? installed.signal}`; + clack.log.error(`Installation failed (${reason}); retry with ${manager} install`); + clack.outro('Scaffold saved'); + return done('install-failed', installed.signal === 'SIGINT' ? 130 : 2); } if (!javascript && !existsSync(path.join(cwd, 'tsconfig.json'))) { clack.log.info('No tsconfig.json; add one for editor completions on e2e.config.ts and tests/'); @@ -466,6 +554,166 @@ export async function init(root: string, options: InitOptions = {}): Promise gateway.keys?.slice(0, 1) ?? []); + const nodeVersionFile = findNodeVersionFile(cwd, repositoryRoot); + const nodeMajor = nodeVersionFile === undefined ? undefined : readNodeMajor(nodeVersionFile); + const content = input.service.render({ + manager, + projectDir: posixRelative(repositoryRoot, cwd), + installDir: posixRelative(repositoryRoot, installRoot), + ...(nodeVersionFile === undefined ? {} : { nodeVersionFile: posixRelative(repositoryRoot, nodeVersionFile) }), + ...(nodeMajor === undefined ? {} : { nodeMajor }), + ...(manager === 'pnpm' && !packageManager.startsWith('pnpm@') ? { pnpmVersion: localPnpmMajor() } : {}), + yarnBerry: existsSync(path.join(installRoot, '.yarnrc.yml')) || /^yarn@[2-9]/u.test(packageManager), + // Bun before 1.2 writes the binary bun.lockb. + ...(manager === 'bun' && !existsSync(path.join(installRoot, 'bun.lock')) && existsSync(path.join(installRoot, 'bun.lockb')) ? { lockfile: 'bun.lockb' } : {}), + secrets, + jobs: input.jobs, + ...(input.jobSuffix === undefined ? {} : { jobSuffix: input.jobSuffix }), + }); + return { + content, + secrets, + logins: gateways.filter((gateway) => gateway.login !== undefined).map((gateway) => gateway.label), + // A new config leaves app.command commented out. + startsApp: input.existingConfigText !== undefined && configStartsApp(input.existingConfigText), + localModel: input.existingConfigText === undefined + ? input.model?.gateway === 'openai-compatible' && isLoopbackHost(new URL(input.model.endpoint ?? DEFAULT_ENDPOINT).hostname) + : configUsesLocalModel(input.existingConfigText), + }; +} + +/** + * The targets of an existing config, loaded the way `e2e run` loads it, or + * undefined, with the reason, when it does not load, such as when its engine + * is still not installed. + */ +async function readTargets(configPath: string): Promise { + try { + return configTargets(await loadConfigModule(configPath)); + } catch (cause) { + clack.log.warn(`Could not read the targets of ${path.basename(configPath)}: ${cause instanceof Error ? cause.message : String(cause)}`); + return undefined; + } +} + +/** + * Plans the pipeline's jobs from the config's targets and writes it, then + * says what the user still has to do for it to pass. An existing config that + * does not load falls back to its package.json: with only the web engine, one + * web job runs every target; with the mobile engine, the targets cannot be + * told apart, and there is no pipeline. + */ +async function writePipeline(input: { + readonly service: CiService; + readonly file: CiFile; + readonly relative: string; + readonly repositoryRoot: string; + readonly cwd: string; + readonly model: ScaffoldModel | undefined; + readonly existingConfig: string | undefined; + readonly existingConfigText: string | undefined; + readonly newTargets: readonly CiTarget[]; + readonly dependsOn: (name: string) => boolean; +}): Promise { + const { service, file, relative, cwd, existingConfigText } = input; + const targets = input.existingConfig === undefined ? input.newTargets : await readTargets(path.join(cwd, input.existingConfig)); + let jobs: CiJobs; + if (targets !== undefined) { + jobs = ciJobs(targets, detectMobileBuilds(cwd, input.dependsOn)); + } else if (input.dependsOn('@e2e-dev/web') && !input.dependsOn('@e2e-dev/mobile')) { + clack.log.warn(`The pipeline runs every target in one web job; run e2e init again once ${input.existingConfig} loads to split them`); + jobs = { web: 'all' }; + } else { + clack.log.warn(`No pipeline: the mobile jobs need the config's targets; run e2e init again once ${input.existingConfig} loads`); + return; + } + if (jobs.web === undefined && jobs.ios === undefined && jobs.android === undefined) { + clack.log.warn(`No web, iOS, or Android target to run in CI, so no pipeline; see ${DOCS_URL}/ci`); + return; + } + const workflow = planWorkflow({ + service, + cwd, + repositoryRoot: input.repositoryRoot, + model: input.model, + existingConfigText, + jobs, + jobSuffix: file.jobSuffix, + }); + const absolute = path.join(input.repositoryRoot, file.file); + mkdirSync(path.dirname(absolute), { recursive: true }); + writeFileSync(absolute, workflow.content, 'utf8'); + clack.log.success(`Created ${relative} (${service.label})`); + if (file.include !== undefined) { + clack.log.warn(`${GITLAB_PIPELINE} exists, not touching it; add this to it to run the e2e jobs:\n${file.include}`); + } + if (file.note !== undefined) clack.log.warn(file.note); + for (const secret of workflow.secrets) clack.log.info(service.secretHint(secret)); + for (const login of workflow.logins) { + clack.log.warn(`${login} signs in on this machine only, so agent steps fail in CI; use a gateway with an API key there, see ${DOCS_URL}/ci#model-credentials`); + } + for (const [platform, label, artifact] of [['ios', 'iOS', 'a .app for the simulator under build/'], ['android', 'Android', 'an APK at android/app/build/outputs/apk/release/app-release.apk']] as const) { + if (jobs[platform]?.build.kind === 'custom') { + clack.log.warn(`The ${label} job's build step is a placeholder that fails: replace it in ${relative} with your app's build, ${artifact}`); + } + } + if (service.id === 'gitlab' && (jobs.ios !== undefined || jobs.android !== undefined)) { + clack.log.warn(`GitLab's hosted runners can't run a simulator or an emulator: the mobile jobs need self-managed runners; set their tags in ${relative}, see ${DOCS_URL}/ci/gitlab#ios-and-android`); + if (!(existingConfigText ?? '').includes('E2E_DEVICE')) { + clack.log.warn('The GitLab mobile jobs boot a device of their own and name it in E2E_DEVICE: set device: process.env.E2E_DEVICE in each mobile() target'); + } + } + if (workflow.localModel) { + clack.log.warn(`The model endpoint is on this machine, so agent steps fail in CI; point it at a server the runner can reach, see ${DOCS_URL}/ci#model-credentials`); + } + if (jobs.web !== undefined && !workflow.startsApp) { + clack.log.warn(`Nothing starts the app in CI: set app.command in e2e.config.ts so the runner starts it, see ${DOCS_URL}/web#starting-your-app`); + } +} + +/** The major version of the pnpm on this machine, for `pnpm/action-setup`; `latest` when it cannot be read. */ +function localPnpmMajor(): string { + const result = spawnSync('pnpm', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' }); + const major = /^(\d+)\./u.exec(String(result.stdout ?? '').trim())?.[1]; + return major ?? 'latest'; +} + /** * What a new config still needs before an agent command such as `e2e explore` * can run on it: a model, the gateway's key in the environment, and an engine diff --git a/packages/e2e/src/cli/init/ci.ts b/packages/e2e/src/cli/init/ci.ts new file mode 100644 index 0000000000..e7106eac7b --- /dev/null +++ b/packages/e2e/src/cli/init/ci.ts @@ -0,0 +1,723 @@ +/** + * The CI pipeline `e2e init` writes: GitHub Actions or GitLab CI/CD, one job + * per platform the config's targets run on. The web job runs on a hosted + * Linux runner. The iOS and Android jobs build the app, boot a simulator or + * an emulator, install the app, and run its targets; init writes the build + * for Expo and bare React Native apps and a step to replace for anything else. + */ + +import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; +import path from 'node:path'; +import { isMap, isScalar, parseDocument, type Document, type Scalar, type YAMLMap, type YAMLSeq } from 'yaml'; +import { resolvePlatform, targetName } from '@e2e-dev/core/lib/config/targets'; +import { isLoopbackHost } from '@e2e-dev/core/lib/internal/urls'; +import type { PackageManager } from '../../internal/package-manager.ts'; +import type { E2EConfig } from '../../run-types.ts'; +import { GATEWAYS, type GatewayPreset } from './gateways.ts'; + +export type CiId = 'github-actions' | 'gitlab'; +export type CiChoice = CiId | 'none'; + +/** Where a service's pipeline goes, relative to the repository root. */ +export interface CiFile { + readonly file: string; + /** Whether e2e already runs there, so init writes nothing. */ + readonly existing: boolean; + /** For a file the main pipeline must include: the lines to add to it. */ + readonly include?: string; + /** Something else the main pipeline needs before the included jobs can run. */ + readonly note?: string; + /** Appended to every job name when the pipeline already has a job of one of those names. */ + readonly jobSuffix?: string; +} + +export interface CiService { + readonly id: CiId; + readonly label: string; + readonly hint: string; + /** The docs page for the service's mobile jobs and everything init does not write. */ + readonly docs: string; + locate(repositoryRoot: string): CiFile; + render(context: WorkflowContext): string; + /** How to give the run a model key it reads from the environment. */ + secretHint(name: string): string; +} + +/** Where the GitHub Actions workflow goes, relative to the repository root. */ +const GITHUB_WORKFLOW = '.github/workflows/e2e.yml'; +/** GitLab's pipeline file, and the file init writes beside one that already exists. */ +export const GITLAB_PIPELINE = '.gitlab-ci.yml'; +const GITLAB_INCLUDED = '.gitlab/e2e.gitlab-ci.yml'; + +export const CI_SERVICES: readonly CiService[] = [ + { + id: 'github-actions', + label: 'GitHub Actions', + hint: 'on every pull request and push to main', + docs: '/ci/github-actions', + locate: locateGithubWorkflow, + render: (context) => renderGithubWorkflow(context), + secretHint: (name) => `The workflow reads ${name} from the repository secrets; add it with gh secret set ${name}`, + }, + { + id: 'gitlab', + label: 'GitLab CI/CD', + hint: 'in every merge request and on the default branch', + docs: '/ci/gitlab', + locate: locateGitlabPipeline, + render: (context) => renderGitlabPipeline(context), + secretHint: (name) => + `The pipeline reads ${name} from the project's CI/CD variables; add it masked and hidden with glab variable set ${name} --masked --hidden --raw`, + }, +]; + +/** The service with this id. */ +export function getCiService(id: CiId): CiService { + const service = CI_SERVICES.find((entry) => entry.id === id); + if (service === undefined) throw new Error(`unknown CI service: ${id}`); + return service; +} + +/** + * Where the GitHub workflow goes: `.github/workflows/e2e.yml`, unless that + * file or another workflow already runs `e2e run`, in which case e2e is set up. + */ +function locateGithubWorkflow(root: string): CiFile { + const workflows = path.join(root, '.github', 'workflows'); + const running = existsSync(workflows) + ? readdirSync(workflows).filter((name) => /\.ya?ml$/u.test(name)).find((name) => readFileSync(path.join(workflows, name), 'utf8').includes('e2e run')) + : undefined; + if (running !== undefined) return { file: `.github/workflows/${running}`, existing: true }; + return { file: GITHUB_WORKFLOW, existing: existsSync(path.join(root, GITHUB_WORKFLOW)) }; +} + +/** + * Where the GitLab job goes: `.gitlab-ci.yml` when the project has none, else + * a file of its own that `.gitlab-ci.yml` includes, so init never edits the + * project's pipeline. A pipeline file that already runs `e2e run` counts as set up. + */ +function locateGitlabPipeline(root: string): CiFile { + const main = path.join(root, GITLAB_PIPELINE); + if (!existsSync(main)) return { file: GITLAB_PIPELINE, existing: false }; + const pipeline = readFileSync(main, 'utf8'); + if (pipeline.includes('e2e run')) return { file: GITLAB_PIPELINE, existing: true }; + // The jobs run in GitLab's default `test` stage, which a pipeline that lists its own stages may leave out. + const stages = gitlabStages(pipeline); + // GitLab merges jobs of the same name across included files, so the jobs step aside for ones the pipeline already has. + const taken = GITLAB_JOBS.some((name) => new RegExp(`^${name.replaceAll('.', '\\.')}\\s*:`, 'mu').test(pipeline)); + return { + file: GITLAB_INCLUDED, + existing: existsSync(path.join(root, GITLAB_INCLUDED)), + include: `include:\n - local: ${GITLAB_INCLUDED}`, + ...(stages !== undefined && !stages.includes('test') + ? { note: `The e2e jobs run in the test stage; add test to the stages in ${GITLAB_PIPELINE}` } + : {}), + ...(taken ? { jobSuffix: '-run' } : {}), + }; +} + +/** The jobs the GitLab template defines, which an existing pipeline's own jobs must not share names with. */ +const GITLAB_JOBS = ['e2e-web', '.e2e-mobile', 'e2e-ios', 'e2e-android'] as const; + +/** The names a pipeline's top-level `stages:` lists, flow (`[build, test]`) or block style; undefined without one. */ +function gitlabStages(pipeline: string): string[] | undefined { + const block = /^stages:[ \t]*(.*(?:\n[ \t]+-.*)*)/mu.exec(pipeline)?.[1]; + if (block === undefined) return undefined; + return block + .replaceAll(/[[\]]/gu, '') + .split(/[,\n]/u) + .map((item) => item.replace(/^\s*-?\s*/u, '').replace(/#.*$/u, '').trim().replaceAll(/^['"]|['"]$/gu, '')) + .filter((item) => item !== ''); +} + +/** The Node version a pipeline sets up when the project pins none. */ +const DEFAULT_NODE = '24'; + +const LOCKFILE: Record = { + npm: 'package-lock.json', + pnpm: 'pnpm-lock.yaml', + yarn: 'yarn.lock', + bun: 'bun.lock', +}; + +/** What the workflow is rendered from; every path is POSIX and relative to the repository root, `''` for the root itself. */ +export interface WorkflowContext { + readonly manager: PackageManager; + /** The e2e project: where `e2e.config.ts` is and the run starts. */ + readonly projectDir: string; + /** Where the install runs and the lockfile is: the workspace root for a workspace member. */ + readonly installDir: string; + /** A `.nvmrc` or `.node-version` file to read the Node version from. */ + readonly nodeVersionFile?: string; + /** The major Node version that file names, for a service that takes a version rather than a file. */ + readonly nodeMajor?: string; + /** The pnpm version to install when `package.json` has no `packageManager` field naming one. */ + readonly pnpmVersion?: string; + /** Yarn 2 or later, whose frozen install is `--immutable`. */ + readonly yarnBerry?: boolean; + /** The lockfile's name when it is not the manager's usual one, such as Bun's older `bun.lockb`. */ + readonly lockfile?: string; + /** Environment variables the run reads from repository secrets of the same name. */ + readonly secrets: readonly string[]; + /** The jobs to write, each with the targets it runs. */ + readonly jobs: CiJobs; + /** Appended to every GitLab job name; see {@link CiFile.jobSuffix}. */ + readonly jobSuffix?: string; +} + +/** + * The jobs a pipeline holds, one per platform. `web` runs every target that + * is not on a phone, or every target at all when the config has no phone + * target (`'all'`, no `--target`); `ios` and `android` name their targets. + * A platform with no targets gets no job. + */ +export interface CiJobs { + readonly web?: readonly string[] | 'all'; + readonly ios?: { readonly targets: readonly string[]; readonly build: IosBuild }; + readonly android?: { readonly targets: readonly string[]; readonly build: AndroidBuild }; +} + +/** + * How the iOS job builds the app for the simulator: Expo generates `ios/` + * and builds it, a bare React Native app builds its workspace with + * `xcodebuild`, and anything else gets a step that fails until it is replaced. + */ +export type IosBuild = + | { readonly kind: 'expo' } + | { readonly kind: 'react-native'; readonly workspace: string; readonly bundler: boolean } + | { readonly kind: 'custom' }; + +/** How the Android job builds a release APK; `prebuild` when Expo still has to generate `android/`. */ +export type AndroidBuild = + | { readonly kind: 'expo'; readonly prebuild: boolean } + | { readonly kind: 'react-native' } + | { readonly kind: 'custom' }; + +/** A target as the pipeline sees it: its name, for `--target`, and the platform its engine drives. */ +export interface CiTarget { + readonly name: string; + readonly platform: string; +} + +/** Phone platforms run in their own job, on a runner with a simulator or an emulator. */ +const PHONES = new Set(['ios', 'android']); + +/** + * The jobs for a config's targets. iOS and Android targets get a job each; + * the rest, web and HTTP-only alike, run in the web job, which names them + * with `--target` only when the config has phone targets too. + */ +export function ciJobs(targets: readonly CiTarget[], builds: { ios: IosBuild; android: AndroidBuild }): CiJobs { + const named = (platform: string) => targets.filter((target) => target.platform === platform).map((target) => target.name); + const others = targets.filter((target) => !PHONES.has(target.platform)).map((target) => target.name); + const phones = targets.some((target) => PHONES.has(target.platform)); + return { + ...(others.length === 0 ? {} : { web: phones ? others : 'all' }), + ...(named('ios').length === 0 ? {} : { ios: { targets: named('ios'), build: builds.ios } }), + ...(named('android').length === 0 ? {} : { android: { targets: named('android'), build: builds.android } }), + }; +} + +/** + * The targets of a loaded config, named and placed by the rules `e2e run` + * resolves them with. A target those rules reject is left out; `e2e run` + * would refuse it too. + */ +export function configTargets(config: E2EConfig): CiTarget[] { + return (Array.isArray(config.targets) ? config.targets : []).flatMap((target, index) => { + try { + const platform = resolvePlatform(target, `targets[${index}]`); + const name = targetName(target, platform); + return typeof name === 'string' ? [{ name, platform }] : []; + } catch { + return []; + } + }); +} + +/** Where every build writes the APK the Android job installs. */ +const APK = 'android/app/build/outputs/apk/release/app-release.apk'; + +/** + * The app build for each phone platform, from the project's package.json and + * native folders: Expo when it depends on `expo`, bare React Native when it + * depends on `react-native` and has the native project, else custom. + */ +export function detectMobileBuilds(projectDir: string, dependsOn: (name: string) => boolean): { ios: IosBuild; android: AndroidBuild } { + const ios = path.join(projectDir, 'ios'); + const workspace = existsSync(ios) && statSync(ios).isDirectory() + ? readdirSync(ios).find((name) => name.endsWith('.xcworkspace') && name !== 'Pods.xcworkspace') + : undefined; + const gradle = existsSync(path.join(projectDir, 'android', 'gradlew')); + if (dependsOn('expo')) { + return { ios: { kind: 'expo' }, android: { kind: 'expo', prebuild: !gradle } }; + } + if (dependsOn('react-native')) { + return { + ios: workspace === undefined + ? { kind: 'custom' } + : { kind: 'react-native', workspace: workspace.replace(/\.xcworkspace$/u, ''), bundler: existsSync(path.join(projectDir, 'Gemfile')) }, + android: gradle ? { kind: 'react-native' } : { kind: 'custom' }, + }; + } + return { ios: { kind: 'custom' }, android: { kind: 'custom' } }; +} + +/** The iOS build's commands and the comment above them; every build leaves the `.app` under `build/`. */ +function iosBuild(manager: PackageManager, build: IosBuild): { comment: string; lines: string[] } { + switch (build.kind) { + case 'expo': + return { + comment: ' Expo generates ios/ (CNG): expo run:ios prebuilds it, installs the pods, and builds without a simulator.', + lines: [exec(manager, 'expo run:ios --configuration Release --device generic --no-bundler --output build/ios')], + }; + case 'react-native': + return { + comment: ' Installs the pods, then builds the workspace for the simulator into build/.', + lines: [ + ...(build.bundler ? ['bundle install', '(cd ios && bundle exec pod install)'] : ['(cd ios && pod install)']), + `xcodebuild -workspace ios/${build.workspace}.xcworkspace -scheme ${build.workspace} -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build`, + ], + }; + case 'custom': + return { + comment: ' Replace this step with your app\'s Release build for the iOS simulator, with the .app under build/.', + lines: ['echo "Replace this step with your app\'s build for the simulator, with the .app under build/" >&2', 'exit 1'], + }; + } +} + +/** The Android build's commands and the comment above them; every build writes the APK at {@link APK}. */ +function androidBuild(manager: PackageManager, build: AndroidBuild): { comment: string; lines: string[] } { + const gradle = '(cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=x86_64)'; + switch (build.kind) { + case 'expo': + return { + comment: ' Expo generates android/ (CNG) and signs release builds with the debug keystore.\n Only the emulator\'s ABI: building all four takes about 25 minutes longer.', + lines: [...(build.prebuild ? [exec(manager, 'expo prebuild --platform android --no-install')] : []), gradle], + }; + case 'react-native': + return { + comment: ' Only the emulator\'s ABI: building all four takes about 25 minutes longer.', + lines: [gradle], + }; + case 'custom': + return { + comment: ` Replace this step with your app's release build, an APK at ${APK}.`, + lines: [`echo "Replace this step with your app's build, an APK at ${APK}" >&2`, 'exit 1'], + }; + } +} + +/** + * The command that runs a package's bin in a pipeline file. It differs from + * `execCommand` on purpose: CI files use the short forms the CI docs and + * vendor examples use (`npx`, `bunx`), not `npm exec --` or `bun run`. + */ +function exec(manager: PackageManager, command: string): string { + switch (manager) { + case 'npm': + return `npx ${command}`; + case 'pnpm': + return `pnpm exec ${command}`; + case 'yarn': + return `yarn ${command}`; + case 'bun': + return `bunx ${command}`; + } +} + +/** The install that fails instead of updating the lockfile. */ +function frozenInstall(manager: PackageManager, yarnBerry: boolean): string { + switch (manager) { + case 'npm': + return 'npm ci'; + case 'pnpm': + return 'pnpm install --frozen-lockfile'; + case 'yarn': + return yarnBerry ? 'yarn install --immutable' : 'yarn install --frozen-lockfile'; + case 'bun': + return 'bun install --frozen-lockfile'; + } +} + +/** `dir/file`, or `file` at the root. */ +function join(dir: string, file: string): string { + return dir === '' ? file : `${dir}/${file}`; +} + +/** Options that print a template back the way it is written: no wrapping, `[main]` without padding. */ +const STRINGIFY = { lineWidth: 0, flowCollectionPadding: false } as const; + +/** + * A pipeline template from `templates/ci/`, shipped beside `dist/`. Each is + * a complete pipeline for npm at the repository root, so linters and the + * docs read it as it is; init edits a copy for the project. + */ +function readTemplate(name: string): Document { + return parseDocument(readFileSync(new URL(`../../../templates/ci/${name}`, import.meta.url), 'utf8')); +} + +/** + * A template's `npx ...` command for the project's package manager. A + * template `--target` takes the job's target names, or goes for `'all'`. + */ +function templateCommand(manager: PackageManager, template: string, targets?: readonly string[] | 'all'): string { + const bare = template.replace(/^npx /u, ''); + if (targets === undefined) return exec(manager, bare); + return exec(manager, bare.replace(/ --target \S+/u, targets === 'all' ? '' : ` --target ${targets.join(',')}`)); +} + +/** The map in `items` whose `key` holds `value`, which the template guarantees. */ +function findItem(items: readonly unknown[], key: string, matches: (value: string) => boolean): YAMLMap { + const found = items.find((item): item is YAMLMap => isMap(item) && matches(String(item.get(key) ?? ''))); + if (found === undefined) throw new Error(`the CI template has no step with ${key} ${matches.toString()}`); + return found; +} + +/** Sets `key` in `map` right before `before`, or at the end when `before` is absent. */ +function setBefore(doc: Document, map: YAMLMap, key: string, value: unknown, before: string): void { + map.delete(key); + const at = map.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === before); + const pair = doc.createPair(key, value); + if (at === -1) map.items.push(pair); + else map.items.splice(at, 0, pair); +} + +/** + * Sets up one GitHub job for the project: its working directory, the Node + * version and cache, the package manager's own setup step, the frozen + * install, and the lockfile in every cache key. + */ +function setUpGithubJob(doc: Document, job: YAMLMap, context: WorkflowContext): void { + const { manager, projectDir, installDir } = context; + const lockfile = join(installDir, context.lockfile ?? LOCKFILE[manager]); + const steps = job.get('steps') as YAMLSeq; + if (projectDir !== '') setBefore(doc, job, 'defaults', { run: { 'working-directory': projectDir } }, 'steps'); + + const setupNode = findItem(steps.items, 'uses', (uses) => uses.startsWith('actions/setup-node@')); + const nodeOptions = setupNode.get('with') as YAMLMap; + if (context.nodeVersionFile !== undefined) { + nodeOptions.delete('node-version'); + setBefore(doc, nodeOptions, 'node-version-file', context.nodeVersionFile, 'cache'); + } + // setup-node caches the store of npm, pnpm, and Yarn; Bun keeps its own. + if (manager === 'bun') nodeOptions.delete('cache'); + else nodeOptions.set('cache', manager); + if (manager !== 'bun' && lockfile !== LOCKFILE[manager]) nodeOptions.set('cache-dependency-path', lockfile); + + const setup = (readTemplate('github-actions-setup.yml').get(manager) as YAMLSeq | undefined)?.items ?? []; + if (manager === 'pnpm') { + // Without a version, the action reads packageManager from the repository root's package.json unless told where the project's is. + const options = context.pnpmVersion !== undefined + ? { version: context.pnpmVersion } + : installDir === '' ? undefined : { package_json_file: join(installDir, 'package.json') }; + if (options !== undefined) (setup[0] as YAMLMap).set('with', doc.createNode(options)); + } + // setup-bun reads the version from the repository root's package.json unless told where the project's is. + if (manager === 'bun' && installDir !== '') { + (setup[0] as YAMLMap).set('with', doc.createNode({ 'bun-version-file': join(installDir, 'package.json') })); + } + steps.items.splice(steps.items.indexOf(setupNode), 0, ...setup); + + const install = findItem(steps.items, 'name', (name) => name === 'Install dependencies'); + install.set('run', frozenInstall(manager, context.yarnBerry === true)); + if (installDir !== projectDir) install.set('working-directory', installDir === '' ? '.' : installDir); + + for (const step of steps.items) { + const options = isMap(step) ? step.get('with') : undefined; + if (isMap(options) && typeof options.get('key') === 'string') { + options.set('key', String(options.get('key')).replace(`hashFiles('${LOCKFILE.npm}')`, `hashFiles('${lockfile}')`)); + } + } +} + +/** Points the job's run step at its targets with the model keys, and its upload at the project's report. */ +function finishGithubJob(doc: Document, job: YAMLMap, context: WorkflowContext, run: YAMLMap, targets: readonly string[] | 'all'): void { + const steps = (job.get('steps') as YAMLSeq).items; + const script = run.getIn(['with', 'script'], true); + if (isScalar(script)) { + // The emulator action runs a script, line by line, instead of a run step. + script.value = String(script.value).split('\n').map((line) => (line.startsWith('npx ') ? templateCommand(context.manager, line, targets) : line)).join('\n'); + if (context.projectDir !== '') (run.get('with') as YAMLMap).set('working-directory', context.projectDir); + } else { + run.set('run', templateCommand(context.manager, String(run.get('run')), targets)); + } + // The template's model key stands for the config's; the rest of the env, such as the emulator's E2E_DEVICE, stays. + const kept = (run.get('env') as YAMLMap | undefined)?.items.filter((pair) => isScalar(pair.key) && pair.key.value !== TEMPLATE_SECRET) ?? []; + const env = doc.createNode(Object.fromEntries(context.secrets.map((name) => [name, `\${{ secrets.${name} }}`]))) as YAMLMap; + env.items.push(...kept); + if (env.items.length === 0) run.delete('env'); + else run.set('env', env); + + if (context.projectDir !== '') { + const upload = findItem(steps, 'name', (name) => name === 'Upload the report').get('with') as YAMLMap; + const paths = upload.get('path', true) as Scalar; + paths.value = paths.value.split('\n').map((line) => (line === '' ? line : join(context.projectDir, line))).join('\n'); + } +} + +/** The model key the templates read, which the config's own keys replace. */ +const TEMPLATE_SECRET = 'AI_GATEWAY_API_KEY'; + +/** Replaces a mobile job's build step with the project's build, and the comment above it. */ +function setGithubBuild(job: YAMLMap, build: { comment: string; lines: string[] }): void { + const step = findItem((job.get('steps') as YAMLSeq).items, 'name', (name) => name === 'Build the app'); + step.commentBefore = build.comment; + step.set('run', build.lines.join('\n') + (build.lines.length > 1 ? '\n' : '')); +} + +/** + * The GitHub Actions workflow: one job per platform in `context.jobs`, on + * pull requests and on pushes to main. The template holds all three; a + * platform with no targets loses its job. + */ +export function renderGithubWorkflow(context: WorkflowContext): string { + const doc = readTemplate('github-actions.yml'); + const jobs = doc.get('jobs') as YAMLMap; + const byName = (job: YAMLMap, name: string): YAMLMap => findItem((job.get('steps') as YAMLSeq).items, 'name', (value) => value === name); + + for (const platform of ['web', 'ios', 'android'] as const) { + if (context.jobs[platform] === undefined) jobs.delete(platform); + else setUpGithubJob(doc, jobs.get(platform) as YAMLMap, context); + } + // The first job left keeps no blank line from the one it followed in the template. + const firstJob = jobs.items[0]?.key; + if (isScalar(firstJob)) firstJob.spaceBefore = false; + if (context.jobs.web !== undefined) { + const job = jobs.get('web') as YAMLMap; + const browsers = byName(job, 'Install browsers'); + browsers.set('run', templateCommand(context.manager, String(browsers.get('run')))); + finishGithubJob(doc, job, context, byName(job, 'Run e2e'), context.jobs.web); + } + if (context.jobs.ios !== undefined) { + const job = jobs.get('ios') as YAMLMap; + setGithubBuild(job, iosBuild(context.manager, context.jobs.ios.build)); + finishGithubJob(doc, job, context, byName(job, 'Run e2e'), context.jobs.ios.targets); + } + if (context.jobs.android !== undefined) { + const job = jobs.get('android') as YAMLMap; + setGithubBuild(job, androidBuild(context.manager, context.jobs.android.build)); + finishGithubJob(doc, job, context, byName(job, 'Run e2e'), context.jobs.android.targets); + } + return doc.toString(STRINGIFY); +} + +/** The `npm`, `pnpm`, Yarn 1, or Bun cache a GitLab job keeps in the project, since GitLab caches only paths inside it. */ +const GITLAB_STORE: Record = { + npm: '.npm', + pnpm: '.pnpm-store', + yarn: '.yarn-cache', + bun: undefined, +}; + +/** Node 25 and later ship no corepack, and their `node` images no Yarn; these install it where it is missing. */ +const COREPACK = ['command -v corepack || npm install --global corepack', 'corepack enable']; + +/** The commands that install the package manager and the dependencies in a `node` image, with the cache inside the project. */ +function gitlabInstall(context: WorkflowContext): string[] { + const { manager } = context; + switch (manager) { + case 'npm': + return ['npm ci --cache .npm --prefer-offline']; + case 'pnpm': + return [ + ...(context.pnpmVersion === undefined ? COREPACK : [`npm install --global pnpm@${context.pnpmVersion}`]), + 'pnpm config set store-dir .pnpm-store', + 'pnpm install --frozen-lockfile', + ]; + case 'yarn': + return context.yarnBerry === true + ? [...COREPACK, 'yarn install --immutable'] + : ['command -v yarn || npm install --global yarn', 'yarn install --frozen-lockfile --cache-folder .yarn-cache']; + case 'bun': + return ['npm install --global bun', 'bun install --frozen-lockfile']; + } +} + +/** + * A mobile job's script on a self-managed shell runner: install, build, then + * the template's own device lines, with the run pointed at the job's targets. + * Paths stay relative to the project, which the script changes into. + */ +function gitlabMobileScript(doc: Document, job: YAMLMap, context: WorkflowContext, build: { comment: string; lines: string[] }, targets: readonly string[]): void { + const { manager, projectDir, installDir } = context; + const cd = (dir: string): string[] => (dir === '' ? [] : [`cd "$CI_PROJECT_DIR/${dir}"`]); + const script = job.get('script') as YAMLSeq>; + // The template's lines after its Expo build: the device, the app's install, and the run. + const lastBuildLine = script.items.findLastIndex((item) => /\bnpx expo |gradlew/u.test(String(item.value))); + const device = script.items.slice(lastBuildLine + 1); + const lines = doc.createNode([ + ...cd(installDir), + frozenInstall(manager, context.yarnBerry === true), + ...(installDir === projectDir ? [] : projectDir === '' ? ['cd "$CI_PROJECT_DIR"'] : cd(projectDir)), + ...build.lines, + ]) as YAMLSeq>; + lines.items[lines.items.length - build.lines.length]!.commentBefore = build.comment; + for (const item of device) { + if (String(item.value).startsWith('npx ')) item.value = templateCommand(manager, item.value, targets); + } + lines.items.push(...device); + job.set('script', lines); +} + +/** + * The GitLab CI/CD pipeline: one job per platform in `context.jobs`, in + * merge request pipelines and on the default branch. The web job runs in a + * `node` image on GitLab's runners; the mobile jobs need self-managed ones. + * The rules sit on the jobs, not in a `workflow:` block, so the same file + * works as `.gitlab-ci.yml` and as a file another pipeline includes. + */ +export function renderGitlabPipeline(context: WorkflowContext): string { + const { manager, projectDir, installDir } = context; + const doc = readTemplate('gitlab-ci.yml'); + const root = doc.contents as YAMLMap; + const cd = (dir: string): string[] => (dir === '' ? [] : [`cd "$CI_PROJECT_DIR/${dir}"`]); + const prefixed = (seq: YAMLSeq>) => { + for (const item of seq.items) item.value = join(projectDir, item.value); + }; + + if (context.jobs.web === undefined) { + root.delete('e2e-web'); + } else { + const job = root.get('e2e-web') as YAMLMap; + // Yarn 2 and later keep their own cache and ignore --cache-folder. + const store = manager === 'yarn' && context.yarnBerry === true ? undefined : GITLAB_STORE[manager]; + const usesCorepack = (manager === 'pnpm' && context.pnpmVersion === undefined) || (manager === 'yarn' && context.yarnBerry === true); + job.set('image', `node:${context.nodeMajor ?? DEFAULT_NODE}`); + if (usesCorepack) (job.get('variables') as YAMLMap).set('COREPACK_ENABLE_DOWNLOAD_PROMPT', '0'); + (job.getIn(['cache', 'key', 'files']) as YAMLSeq).set(0, join(installDir, context.lockfile ?? LOCKFILE[manager])); + const cachePaths = job.getIn(['cache', 'paths']) as YAMLSeq; + if (store === undefined) cachePaths.delete(1); + else cachePaths.set(1, `${join(installDir, store)}/`); + const [, browsers, run] = (job.get('script') as YAMLSeq>).items; + job.set('script', doc.createNode([ + ...cd(installDir), + ...gitlabInstall(context), + ...(installDir === projectDir ? [] : projectDir === '' ? ['cd "$CI_PROJECT_DIR"'] : cd(projectDir)), + templateCommand(manager, browsers!.value), + templateCommand(manager, run!.value, context.jobs.web), + ])); + if (projectDir !== '') { + prefixed(job.getIn(['artifacts', 'paths']) as YAMLSeq>); + const junit = job.getIn(['artifacts', 'reports', 'junit'], true) as Scalar; + junit.value = join(projectDir, junit.value); + } + } + + if (context.jobs.ios === undefined) root.delete('e2e-ios'); + else gitlabMobileScript(doc, root.get('e2e-ios') as YAMLMap, context, iosBuild(manager, context.jobs.ios.build), context.jobs.ios.targets); + if (context.jobs.android === undefined) root.delete('e2e-android'); + else gitlabMobileScript(doc, root.get('e2e-android') as YAMLMap, context, androidBuild(manager, context.jobs.android.build), context.jobs.android.targets); + if (context.jobs.ios === undefined && context.jobs.android === undefined) { + root.delete('.e2e-mobile'); + } else if (projectDir !== '') { + const mobile = root.get('.e2e-mobile') as YAMLMap; + prefixed(mobile.getIn(['artifacts', 'paths']) as YAMLSeq>); + const junit = mobile.getIn(['artifacts', 'reports', 'junit'], true) as Scalar; + junit.value = join(projectDir, junit.value); + } + + const firstJob = root.items[0]?.key; + if (isScalar(firstJob)) firstJob.spaceBefore = false; + if (context.jobSuffix !== undefined) { + for (const pair of root.items) { + if (isScalar(pair.key)) pair.key.value = `${String(pair.key.value)}${context.jobSuffix}`; + const extended = isMap(pair.value) ? pair.value.get('extends', true) : undefined; + if (isScalar(extended)) extended.value = `${String(extended.value)}${context.jobSuffix}`; + } + } + return doc.toString(STRINGIFY); +} + +/** + * The repository the project is in: the nearest directory at or above `dir` + * with a `.git` entry (a directory, or a file in a worktree or submodule), + * else `fallback`, the directory `e2e init` was pointed at. + */ +export function findRepositoryRoot(dir: string, fallback: string): string { + for (let current = path.resolve(dir); ; current = path.dirname(current)) { + if (existsSync(path.join(current, '.git'))) return current; + if (path.dirname(current) === current) return path.resolve(fallback); + } +} + +/** + * The service the repository looks hosted on: GitLab for a `.gitlab-ci.yml` + * or a remote on a `gitlab.` host, GitHub for a `.github/` directory or a + * github.com remote. Undefined when nothing points either way. + */ +export function detectCiService(repositoryRoot: string): CiId | undefined { + let remotes = ''; + const gitConfig = path.join(repositoryRoot, '.git', 'config'); + try { + if (statSync(gitConfig).isFile()) remotes = readFileSync(gitConfig, 'utf8'); + } catch { + // No git config: a worktree, a submodule, or no repository yet. + } + if (existsSync(path.join(repositoryRoot, GITLAB_PIPELINE)) || /url\s*=.*\bgitlab\./u.test(remotes)) return 'gitlab'; + if (existsSync(path.join(repositoryRoot, '.github')) || /url\s*=.*github\.com[:/]/u.test(remotes)) return 'github-actions'; + return undefined; +} + +/** The `.nvmrc` or `.node-version` nearest the project, up to the repository root. */ +export function findNodeVersionFile(projectDir: string, repositoryRoot: string): string | undefined { + const root = path.resolve(repositoryRoot); + for (let current = path.resolve(projectDir); ; current = path.dirname(current)) { + for (const name of ['.nvmrc', '.node-version']) { + if (existsSync(path.join(current, name))) return path.join(current, name); + } + if (current === root || path.dirname(current) === current) return undefined; + } +} + +/** The major version a `.nvmrc` or `.node-version` names (`24`, `v24.8.0`, `24.8`), or undefined for an alias such as `lts/*`. */ +export function readNodeMajor(file: string): string | undefined { + try { + return /^v?(\d+)(?:\.|\s|$)/u.exec(readFileSync(file, 'utf8').trim())?.[1]; + } catch { + return undefined; + } +} + +/** `target` relative to `root` with forward slashes; `''` for the root itself. */ +export function posixRelative(root: string, target: string): string { + return path.relative(root, target).split(path.sep).join('/'); +} + +/** + * The gateways an existing config uses, recognized by the import `e2e init` + * writes for each, in any quoting or alongside other names. A config that + * builds its model another way matches none, and the pipeline sets no model key. + */ +export function gatewaysInConfig(config: string): readonly GatewayPreset[] { + return GATEWAYS.filter((gateway) => importPattern(gateway.import)?.test(config) === true); +} + +/** + * A pattern for an import line like `import { gateway } from 'ai';` that + * also matches it with double quotes, other names beside it, or other spacing. + */ +function importPattern(line: string): RegExp | undefined { + const parts = /^import \{ (\w+) \} from '([^']+)';$/u.exec(line); + if (parts === null) return undefined; + const [, name, specifier] = parts; + const escaped = specifier!.replaceAll(/[.*+?^${}()|[\]\\/]/gu, '\\$&'); + return new RegExp(`import\\s*\\{[^}]*\\b${name!}\\b[^}]*\\}\\s*from\\s*['"]${escaped}['"]`, 'u'); +} + +/** Whether a config points an OpenAI-compatible model at a loopback `baseURL`, which a CI runner cannot reach. */ +export function configUsesLocalModel(config: string): boolean { + return [...config.matchAll(/^\s*baseURL\s*:\s*['"`]([^'"`]+)['"`]/gmu)].some(([, url]) => { + try { + return isLoopbackHost(new URL(url!).hostname); + } catch { + return false; + } + }); +} + +/** Whether a config sets an app `command`, so the runner can start the app on a fresh CI machine. */ +export function configStartsApp(config: string): boolean { + return config.split('\n').some((line) => !line.trimStart().startsWith('//') && /\bcommand\s*:/u.test(line)); +} diff --git a/packages/e2e/src/cli/init/engines.ts b/packages/e2e/src/cli/init/engines.ts index 5d7a952085..6b8578fb75 100644 --- a/packages/e2e/src/cli/init/engines.ts +++ b/packages/e2e/src/cli/init/engines.ts @@ -24,6 +24,8 @@ export interface EnginePreset { readonly aiExample: (options: string) => string; /** Whether the run hint sets APP_URL, for engines that drive a URL. */ readonly needsAppUrl: boolean; + /** The platform the target drives, which is also its name in the config, for the CI job that runs it. */ + readonly platform: 'web' | 'ios' | 'android'; } /** Builds prompt choices and scaffolds with defaults for the machine running init. */ @@ -64,6 +66,7 @@ test('app opens', ${options}async ({ app, browser }) => { // }); `, needsAppUrl: true, + platform: 'web', }, { id: 'mobile', @@ -104,6 +107,7 @@ test('Settings opens', ${options}async ({ app, screen }) => { // }); `, needsAppUrl: false, + platform: ios ? 'ios' : 'android', }, ] as const satisfies readonly EnginePreset[]; } diff --git a/packages/e2e/src/cli/init/flags.ts b/packages/e2e/src/cli/init/flags.ts index b76953b1fe..c2abb2676a 100644 --- a/packages/e2e/src/cli/init/flags.ts +++ b/packages/e2e/src/cli/init/flags.ts @@ -4,6 +4,7 @@ import { InvalidArgumentError, Option, type Command } from 'commander'; import type { InitOptions } from '../init.ts'; import { parseNames } from '../parse-names.ts'; import { SKILL_LOCATIONS } from './agent-skill.ts'; +import { CI_SERVICES } from './ci.ts'; import { getEnginePresets, type EngineId } from './engines.ts'; import { EXAMPLES, findExample } from './examples.ts'; import { GATEWAYS, validateEndpoint } from './gateways.ts'; @@ -41,6 +42,12 @@ export function addInitOptions(command: Command): Command { ) .option('--skills ', `where to install the agent skill, comma-separated: ${SKILL_DIRS.join(', ')}, or none`, parseNames('skill directory')) .option('--mcp ', `where to register the MCP server, comma-separated: ${MCP_FILES.join(', ')}, or none`, parseNames('MCP config file')) + .addOption( + new Option('--ci ', 'CI pipeline that runs the web tests; none writes none, and --yes alone writes none').choices([ + ...CI_SERVICES.map((service) => service.id), + 'none', + ]), + ) .option('--install', 'install dependencies after scaffolding') .option('--no-install', 'do not install dependencies'); } diff --git a/packages/e2e/src/cli/init/mcp-config.ts b/packages/e2e/src/cli/init/mcp-config.ts index 597cabb1f5..a17fcb2319 100644 --- a/packages/e2e/src/cli/init/mcp-config.ts +++ b/packages/e2e/src/cli/init/mcp-config.ts @@ -79,7 +79,7 @@ function readDocument(absolute: string): McpConfigDocument | undefined { * every existing component is a plain entry. A component past the link is not * inspected: it lives wherever the link points. */ -function linkOnPath(cwd: string, target: string): McpLink | undefined { +export function linkOnPath(cwd: string, target: string): McpLink | undefined { let current = cwd; for (const segment of path.relative(cwd, target).split(path.sep)) { current = path.join(current, segment); diff --git a/packages/e2e/src/cli/init/package.ts b/packages/e2e/src/cli/init/package.ts index 61e14087b6..eb2705087d 100644 --- a/packages/e2e/src/cli/init/package.ts +++ b/packages/e2e/src/cli/init/package.ts @@ -39,7 +39,7 @@ export function describeManifestError(cause: unknown): string { } /** True when any dependency section lists `name`, so existing versions and workspace links are kept. */ -function declaresDependency(manifest: PackageManifest, name: string): boolean { +export function declaresDependency(manifest: PackageManifest, name: string): boolean { return [manifest.dependencies, manifest.devDependencies, manifest.peerDependencies, manifest.optionalDependencies] .some((block) => block?.[name] !== undefined); } diff --git a/packages/e2e/src/telemetry/events.ts b/packages/e2e/src/telemetry/events.ts index 53310241f4..47c6740489 100644 --- a/packages/e2e/src/telemetry/events.ts +++ b/packages/e2e/src/telemetry/events.ts @@ -82,6 +82,8 @@ export interface InitOutcome { /** Whether the agent skill, the MCP registration, and the install were chosen. */ readonly skill: boolean; readonly mcp: boolean; + /** The CI pipeline chosen (`github-actions`, `gitlab`, `none`), null when not asked. */ + readonly ci: string | null; readonly install: boolean; } @@ -159,6 +161,7 @@ export function initCompletedEvent(outcome: InitOutcome): TelemetryEvent { gateway: outcome.gateway, skill: outcome.skill, mcp: outcome.mcp, + ci: outcome.ci, install: outcome.install, }, }; diff --git a/packages/e2e/templates/ci/github-actions-setup.yml b/packages/e2e/templates/ci/github-actions-setup.yml new file mode 100644 index 0000000000..1d25efe2b9 --- /dev/null +++ b/packages/e2e/templates/ci/github-actions-setup.yml @@ -0,0 +1,9 @@ +# The steps `e2e init` adds to github-actions.yml before setup-node, one per +# package manager that npm's runner image does not already have. +pnpm: + - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0 +bun: + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 +# Yarn 2 and later come from the packageManager field through corepack; the runner image has only Yarn 1. +yarn: + - run: corepack enable diff --git a/packages/e2e/templates/ci/github-actions.yml b/packages/e2e/templates/ci/github-actions.yml new file mode 100644 index 0000000000..9719a7067e --- /dev/null +++ b/packages/e2e/templates/ci/github-actions.yml @@ -0,0 +1,206 @@ +# Written by `e2e init --ci github-actions`: the e2e tests on every pull request +# and every push to main, one job per platform. See https://e2e.com/docs/ci/github-actions +name: e2e + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + web: + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: 24 + cache: npm + - name: Install dependencies + run: npm ci + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ~/.cache/ms-playwright + key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package-lock.json') }} + + - name: Install browsers + run: npx e2e-web install chromium --with-deps + + - name: Run e2e + run: npx e2e run --target web --reporter list,junit + env: + AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }} + + - name: Upload the report + if: ${{ !cancelled() }} + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: e2e-web + path: | + .e2e/report.json + .e2e/junit.xml + .e2e/results + # .e2e is a hidden directory, which upload-artifact skips when it expands a folder. + include-hidden-files: true + if-no-files-found: warn + retention-days: 7 + + ios: + runs-on: macos-26 + # A Release build for the simulator alone can take 35 minutes on this runner. + timeout-minutes: 90 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: 24 + cache: npm + - name: Install dependencies + run: npm ci + + # Expo generates ios/ (CNG): expo run:ios prebuilds it, installs the pods, and builds without a simulator. + - name: Build the app + run: npx expo run:ios --configuration Release --device generic --no-bundler --output build/ios + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ~/.agent-device/apple-runner/derived + key: agent-device-runner-${{ runner.os }}-${{ hashFiles('package-lock.json') }} + + # Boots the image's own iPhone 17 Pro on a pinned runtime: a simulator made with `simctl create` + # can spend minutes on its first boot. Bump the runtime on purpose, after a local run on it, + # since the accessibility tree changes between iOS releases. + - name: Boot a simulator and install the app + env: + IOS_RUNTIME: com.apple.CoreSimulator.SimRuntime.iOS-26-5 + run: | + set -euo pipefail + UDID=$(xcrun simctl list devices available -j | jq -r --arg rt "$IOS_RUNTIME" '.devices[$rt][]? | select(.name == "iPhone 17 Pro") | .udid' | head -n 1) + if [ -z "$UDID" ]; then + echo "::error::No iPhone 17 Pro on $IOS_RUNTIME" + xcrun simctl list runtimes + exit 1 + fi + xcrun simctl boot "$UDID" + xcrun simctl bootstatus "$UDID" + APP=$(find build -maxdepth 5 -name '*.app' -type d | head -n 1) + if [ -z "$APP" ]; then + echo "::error::No .app under build/" + exit 1 + fi + xcrun simctl install "$UDID" "$APP" + # A target with device: process.env.E2E_DEVICE drives this simulator, whatever else the image has. + echo "E2E_DEVICE=$UDID" >> "$GITHUB_ENV" + + - name: Run e2e + run: npx e2e run --target ios --workers 1 --reporter list,junit + env: + AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }} + + - name: Upload the report + if: ${{ !cancelled() }} + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: e2e-ios + path: | + .e2e/report.json + .e2e/junit.xml + .e2e/results + # .e2e is a hidden directory, which upload-artifact skips when it expands a folder. + include-hidden-files: true + if-no-files-found: warn + retention-days: 7 + + android: + runs-on: ubuntu-latest + timeout-minutes: 60 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: 24 + cache: npm + - uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0 + with: + distribution: temurin + java-version: 17 + - name: Install dependencies + run: npm ci + + - name: Enable KVM + run: | + echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules + sudo udevadm control --reload-rules + sudo udevadm trigger --name-match=kvm + + # Expo generates android/ (CNG) and signs release builds with the debug keystore. + # Only the emulator's ABI: building all four takes about 25 minutes longer. + - name: Build the app + run: | + npx expo prebuild --platform android --no-install + (cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=x86_64) + + # The runner image's command-line tools can be older than the system image's package format, + # and the emulator action uses them to create the device, so the job puts current ones in place first. + # The action downloads the image once and fails the job when that download drops, and sdkmanager + # can report success for a package that holds no image, so the image is installed and checked here. + - name: Install the emulator system image + env: + CMDLINE_TOOLS: commandlinetools-linux-16111833_latest.zip + CMDLINE_TOOLS_SHA256: 0877a1d048fe4a24efe2eff536ca4223f7adeb58648bb81909d33c446918cfa8 + run: | + curl -fsSL --retry 3 -o "$RUNNER_TEMP/$CMDLINE_TOOLS" "https://dl.google.com/android/repository/$CMDLINE_TOOLS" + echo "$CMDLINE_TOOLS_SHA256 $RUNNER_TEMP/$CMDLINE_TOOLS" | sha256sum --check --quiet + rm -rf "$ANDROID_HOME/cmdline-tools/latest" + unzip -q "$RUNNER_TEMP/$CMDLINE_TOOLS" -d "$RUNNER_TEMP/cmdline-tools" + mv "$RUNNER_TEMP/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest" + SDKMANAGER="$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" + IMAGE="$ANDROID_HOME/system-images/android-36/google_apis/x86_64" + "$SDKMANAGER" --licenses < <(yes) > /dev/null + for attempt in 1 2 3; do + if "$SDKMANAGER" --install 'system-images;android-36;google_apis;x86_64' > /dev/null && ls "$IMAGE"/*.img > /dev/null 2>&1; then + exit 0 + fi + echo "Download attempt $attempt failed" + rm -rf "$IMAGE" + sleep 30 + done + exit 1 + + - name: Run e2e + uses: reactivecircus/android-emulator-runner@a421e43855164a8197daf9d8d40fe71c6996bb0d # v2.38.0 + with: + api-level: 36 + arch: x86_64 + target: google_apis + profile: pixel_7 + emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim + disable-animations: true + script: | + adb install -r android/app/build/outputs/apk/release/app-release.apk + npx e2e run --target android --workers 1 --reporter list,junit + env: + AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }} + # The emulator the action boots, for a target with device: process.env.E2E_DEVICE. + E2E_DEVICE: emulator-5554 + + - name: Upload the report + if: ${{ !cancelled() }} + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: e2e-android + path: | + .e2e/report.json + .e2e/junit.xml + .e2e/results + # .e2e is a hidden directory, which upload-artifact skips when it expands a folder. + include-hidden-files: true + if-no-files-found: warn + retention-days: 7 diff --git a/packages/e2e/templates/ci/gitlab-ci.yml b/packages/e2e/templates/ci/gitlab-ci.yml new file mode 100644 index 0000000000..8d931f5bad --- /dev/null +++ b/packages/e2e/templates/ci/gitlab-ci.yml @@ -0,0 +1,95 @@ +# Written by `e2e init --ci gitlab`: the e2e tests in every merge request and on +# the default branch, one job per platform. See https://e2e.com/docs/ci/gitlab + +e2e-web: + image: node:24 + interruptible: true + timeout: 30 minutes + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + variables: + # GitLab caches only paths inside the project. + PLAYWRIGHT_BROWSERS_PATH: $CI_PROJECT_DIR/.cache/ms-playwright + cache: + key: + files: + - package-lock.json + paths: + - .cache/ms-playwright/ + - .npm/ + script: + - npm ci --cache .npm --prefer-offline + - npx e2e-web install chromium --with-deps + - npx e2e run --target web --reporter list,junit + artifacts: + when: always + expire_in: 7 days + paths: + - .e2e/report.json + - .e2e/junit.xml + - .e2e/results/ + reports: + junit: .e2e/junit.xml + +# GitLab's hosted runners can't run a simulator or an emulator, so the mobile jobs run on +# self-managed runners with the shell executor: a Mac with Xcode, and Linux with KVM, a JDK, +# and the Android SDK, each with Node.js and the project's package manager. Replace the tags +# with your runners' tags. +.e2e-mobile: + interruptible: true + timeout: 90 minutes + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + artifacts: + when: always + expire_in: 7 days + paths: + - .e2e/report.json + - .e2e/junit.xml + - .e2e/results/ + # The Android job's emulator output, for a boot that fails. + - .e2e/emulator.log + reports: + junit: .e2e/junit.xml + +e2e-ios: + extends: .e2e-mobile + tags: [macos] + script: + - npm ci + # Expo generates ios/ (CNG): expo run:ios prebuilds it, installs the pods, and builds without a simulator. + - npx expo run:ios --configuration Release --device generic --no-bundler --output build/ios + # A simulator of the job's own on a pinned runtime, so the run never drives a device another job left booted. + - export E2E_DEVICE=$(xcrun simctl create "e2e-$CI_JOB_ID" "iPhone 17 Pro" com.apple.CoreSimulator.SimRuntime.iOS-26-5) + - echo "$E2E_DEVICE" > "$CI_PROJECT_DIR/.simulator-udid" + - xcrun simctl bootstatus "$E2E_DEVICE" -b + - xcrun simctl install "$E2E_DEVICE" "$(find build -maxdepth 5 -name '*.app' -type d | head -n 1)" + - npx e2e run --target ios --workers 1 --reporter list,junit + after_script: + # after_script starts a new shell in the project directory, after a failed script too, but not after a timeout. + - xcrun simctl delete "$(cat "$CI_PROJECT_DIR/.simulator-udid")" || true + +e2e-android: + extends: .e2e-mobile + tags: [linux-kvm] + script: + - npm ci + # Expo generates android/ (CNG) and signs release builds with the debug keystore. + # Only the emulator's ABI: building all four takes about 25 minutes longer. + - npx expo prebuild --platform android --no-install + - (cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=x86_64) + # An emulator of the job's own: the port comes from CI_CONCURRENT_ID, so parallel jobs on one runner don't share one. + # It boots an AVD named e2e that you create on the runner. + - mkdir -p .e2e + - PORT=$((5554 + 2 * CI_CONCURRENT_ID)) + - export E2E_DEVICE=emulator-$PORT + - adb -s $E2E_DEVICE emu kill || true + - $ANDROID_HOME/emulator/emulator -avd e2e -read-only -port $PORT -no-window -no-audio -no-boot-anim -no-snapshot -gpu swiftshader_indirect > .e2e/emulator.log 2>&1 & + - timeout 300 adb -s $E2E_DEVICE wait-for-device + - timeout 300 sh -c 'until [ "$(adb -s $E2E_DEVICE shell getprop sys.boot_completed | tr -d "\r")" = 1 ]; do sleep 2; done' + - adb -s $E2E_DEVICE install -r android/app/build/outputs/apk/release/app-release.apk + - npx e2e run --target android --workers 1 --reporter list,junit + after_script: + - adb -s emulator-$((5554 + 2 * CI_CONCURRENT_ID)) emu kill || true diff --git a/packages/e2e/tests/unit/cli-init.test.ts b/packages/e2e/tests/unit/cli-init.test.ts index 14b5f9c6a9..856e91172f 100644 --- a/packages/e2e/tests/unit/cli-init.test.ts +++ b/packages/e2e/tests/unit/cli-init.test.ts @@ -16,6 +16,7 @@ import os from 'node:os'; import path from 'node:path'; import * as clack from '@clack/prompts'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { parse as parseYaml } from 'yaml'; import { init } from '../../src/cli/init.ts'; import { planSkillInstall } from '../../src/cli/init/agent-skill.ts'; import { dependencyRange } from '../../src/cli/init/versions.ts'; @@ -49,6 +50,14 @@ function output(): string { return stdoutSpy.mock.calls.map((call: readonly unknown[]) => String(call[0])).join(''); } +/** Installs a stand-in for package `name` in the throwaway project, whose ESM entry is `source`. */ +function stubPackage(name: string, source: string): void { + const root = path.join(dir, 'node_modules', ...name.split('/')); + mkdirSync(root, { recursive: true }); + writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name, type: 'module', exports: './index.js' })); + writeFileSync(path.join(root, 'index.js'), source); +} + /** Reads one file from the throwaway project. */ function read(file: string): string { return readFileSync(path.join(dir, file), 'utf8'); @@ -157,6 +166,7 @@ describe('e2e init', () => { gateway: 'vercel', skill: true, mcp: true, + ci: 'none', install: false, }); expect(await init(dir, { yes: true })).toMatchObject({ @@ -185,6 +195,7 @@ describe('e2e init', () => { gateway: 'none', skill: true, mcp: false, + ci: null, install: false, }); @@ -252,7 +263,7 @@ describe('e2e init', () => { vi.mocked(clack.select).mockResolvedValueOnce('none'); vi.mocked(clack.confirm).mockResolvedValueOnce(true).mockResolvedValueOnce(false); - expect((await init(dir)).exitCode).toBe(0); + expect((await init(dir, { ci: 'none' })).exitCode).toBe(0); expect(clack.select).toHaveBeenCalledTimes(1); expect(clack.multiselect).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining('Which engines?'), @@ -306,7 +317,7 @@ describe('e2e init', () => { vi.mocked(clack.text).mockResolvedValueOnce(' http://127.0.0.1:11434/v1 '); vi.mocked(clack.confirm).mockResolvedValueOnce(true).mockResolvedValueOnce(false); - expect((await init(dir)).exitCode).toBe(0); + expect((await init(dir, { ci: 'none' })).exitCode).toBe(0); expect(clack.select).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ message: expect.stringContaining('Which model gateway'), initialValue: 'vercel', @@ -378,6 +389,7 @@ describe('e2e init', () => { gateway: 'openrouter', skill: true, mcp: true, + ci: 'none', install: true, }); expect(clack.select).not.toHaveBeenCalled(); @@ -420,7 +432,7 @@ describe('e2e init', () => { it('asks only the questions no flag answered', async () => { vi.mocked(clack.select).mockResolvedValueOnce('none'); vi.mocked(clack.confirm).mockResolvedValueOnce(true); - expect(await init(dir, { engines: ['web'], skills: ['.claude/skills'], mcp: [], install: false })).toMatchObject({ + expect(await init(dir, { engines: ['web'], skills: ['.claude/skills'], mcp: [], ci: 'none', install: false })).toMatchObject({ exitCode: 0, engine: 'web', gateway: 'none', @@ -556,14 +568,16 @@ describe('e2e init', () => { }); }); - it.each(['engine', 'gateway', 'endpoint', 'skill', 'mcp', 'files', 'install'])('leaves the directory untouched when cancelling at %s', async (stage) => { + it.each(['engine', 'gateway', 'endpoint', 'skill', 'mcp', 'ci', 'files', 'install'])('leaves the directory untouched when cancelling at %s', async (stage) => { const cancel: typeof clack.CANCEL_SYMBOL = clack.CANCEL_SYMBOL; answers = { engines: stage === 'engine' ? cancel : ['web', 'mobile'], skills: stage === 'skill' ? cancel : ['.agents/skills'], mcp: stage === 'mcp' ? cancel : ['.mcp.json'], }; - vi.mocked(clack.select).mockResolvedValueOnce(stage === 'gateway' ? cancel : 'openai-compatible'); + vi.mocked(clack.select) + .mockResolvedValueOnce(stage === 'gateway' ? cancel : 'openai-compatible') + .mockResolvedValueOnce(stage === 'ci' ? cancel : 'github-actions'); vi.mocked(clack.text).mockResolvedValueOnce(stage === 'endpoint' ? cancel : 'http://127.0.0.1:11434/v1'); vi.mocked(clack.confirm) .mockResolvedValueOnce(stage !== 'files') @@ -1172,4 +1186,283 @@ describe('e2e init', () => { } }); }); + + describe('with a CI workflow', () => { + const workflow = '.github/workflows/e2e.yml'; + + it('writes the GitHub Actions workflow with --ci and says what CI still needs', async () => { + expect(await init(dir, { yes: true, ci: 'github-actions' })).toMatchObject({ exitCode: 0, result: 'scaffolded', ci: 'github-actions' }); + expect(read(workflow)).toContain('run: npx e2e run --reporter list,junit'); + expect(read(workflow)).toContain('AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}'); + expect(output()).toContain(`Created ${workflow} (GitHub Actions)`); + expect(output()).toContain('add it with gh secret set AI_GATEWAY_API_KEY'); + // The new config leaves app.command commented out, so nothing would start the app on the runner. + expect(output()).toContain('Nothing starts the app in CI: set app.command in e2e.config.ts'); + }); + + it('writes none under --yes alone, and none over an existing workflow', async () => { + expect(await init(dir, { yes: true })).toMatchObject({ ci: 'none' }); + expect(existsSync(path.join(dir, workflow))).toBe(false); + + mkdirSync(path.join(dir, '.github', 'workflows'), { recursive: true }); + writeFileSync(path.join(dir, workflow), 'name: mine\n'); + expect(await init(dir, { yes: true, ci: 'github-actions' })).toMatchObject({ result: 'already-initialized' }); + expect(read(workflow)).toBe('name: mine\n'); + expect(output()).toContain(`Exists, not touching: ${workflow}`); + }); + + it('asks with GitHub Actions preselected in a GitHub repository, and not again once the workflow exists', async () => { + answers.engines = ['web']; + mkdirSync(path.join(dir, '.github')); + vi.mocked(clack.select).mockResolvedValueOnce('none').mockResolvedValueOnce('github-actions'); + vi.mocked(clack.confirm).mockResolvedValueOnce(true).mockResolvedValueOnce(false); + expect(await init(dir)).toMatchObject({ exitCode: 0, ci: 'github-actions' }); + expect(clack.select).toHaveBeenLastCalledWith(expect.objectContaining({ + message: 'Add a CI pipeline that runs the tests?', + initialValue: 'github-actions', + options: [ + expect.objectContaining({ value: 'github-actions' }), + expect.objectContaining({ value: 'gitlab' }), + expect.objectContaining({ value: 'none' }), + ], + })); + expect(output()).toContain(`Create ${workflow}`); + // No model was chosen, so the workflow reads no key. + expect(read(workflow)).not.toContain('env:'); + + vi.mocked(clack.select).mockClear(); + expect(await init(dir)).toMatchObject({ result: 'already-initialized', ci: null }); + expect(clack.select).not.toHaveBeenCalled(); + }); + + it('preselects none outside a GitHub repository', async () => { + answers.engines = ['web']; + vi.mocked(clack.confirm).mockResolvedValueOnce(false); + await init(dir); + expect(clack.select).toHaveBeenLastCalledWith(expect.objectContaining({ initialValue: 'none' })); + }); + + it.each([ + { host: 'darwin', platform: 'ios', label: 'iOS' }, + { host: 'linux', platform: 'android', label: 'Android' }, + ] as const)('writes the $platform job alone for a mobile-only project on $host', async ({ host, platform, label }) => { + vi.spyOn(os, 'platform').mockReturnValue(host); + expect(await init(dir, { yes: true, engines: ['mobile'], ci: 'github-actions' })).toMatchObject({ exitCode: 0, ci: 'github-actions' }); + const jobs = (parseYaml(read(workflow)) as { jobs: Record }).jobs; + expect(Object.keys(jobs)).toEqual([platform]); + expect(read(workflow)).toContain(`npx e2e run --target ${platform} --workers 1 --reporter list,junit`); + // Not an Expo or React Native project, so the build is the user's to write. + expect(output()).toContain(`The ${label} job's build step is a placeholder that fails`); + // app.command starts a web app; a phone job installs its build. + expect(output()).not.toContain('Nothing starts the app in CI'); + }); + + it('runs the web and phone targets in their own jobs when the config has both', async () => { + vi.spyOn(os, 'platform').mockReturnValue('darwin'); + await init(dir, { yes: true, engines: ['web', 'mobile'], ci: 'github-actions' }); + expect(Object.keys((parseYaml(read(workflow)) as { jobs: object }).jobs)).toEqual(['web', 'ios']); + expect(read(workflow)).toContain('run: npx e2e run --target web --reporter list,junit'); + expect(read(workflow)).toContain('run: npx e2e run --target ios --workers 1 --reporter list,junit'); + }); + + it('builds an Expo app in the phone jobs', async () => { + vi.spyOn(os, 'platform').mockReturnValue('linux'); + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ dependencies: { expo: '*' } })); + await init(dir, { yes: true, engines: ['mobile'], ci: 'github-actions' }); + expect(read(workflow)).toContain('npx expo prebuild --platform android --no-install'); + expect(output()).not.toContain('placeholder'); + }); + + it('tells GitLab users the phone jobs need self-managed runners and a device from E2E_DEVICE', async () => { + vi.spyOn(os, 'platform').mockReturnValue('darwin'); + await init(dir, { yes: true, engines: ['mobile'], ci: 'gitlab' }); + expect(Object.keys(parseYaml(read('.gitlab-ci.yml')) as object)).toEqual(['.e2e-mobile', 'e2e-ios']); + expect(output()).toContain("GitLab's hosted runners can't run a simulator or an emulator"); + expect(output()).toContain('set device: process.env.E2E_DEVICE in each mobile() target'); + }); + + it('asks nothing for a new config with no engine, whatever package.json still lists', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { '@e2e-dev/web': '*' } })); + answers.engines = []; + vi.mocked(clack.confirm).mockResolvedValueOnce(true).mockResolvedValueOnce(false); + expect(await init(dir, { gateway: 'none', skills: [], mcp: [] })).toMatchObject({ exitCode: 0, ci: null }); + expect(clack.select).not.toHaveBeenCalledWith(expect.objectContaining({ message: 'Add a CI pipeline that runs the tests?' })); + }); + + it('counts an engine an existing project declares as a peer', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ peerDependencies: { '@e2e-dev/web': '*' } })); + writeFileSync(path.join(dir, 'e2e.config.ts'), "export default { targets: [{ platform: 'web' }] };\n"); + await init(dir, { yes: true, ci: 'github-actions' }); + expect(read(workflow)).toContain('run: npx e2e run --reporter list,junit'); + }); + + it('writes no pipeline for a project with neither engine', async () => { + expect(await init(dir, { yes: true, engines: [], ci: 'github-actions' })).toMatchObject({ exitCode: 0, ci: null }); + expect(existsSync(path.join(dir, '.github'))).toBe(false); + expect(output()).toContain('Ignoring --ci: init writes a pipeline for web, iOS, and Android targets, and the project has none'); + }); + + it('writes the workflow at the repository root for a project in a subfolder', async () => { + const project = path.join(dir, 'e2e'); + mkdirSync(path.join(dir, '.git'), { recursive: true }); + mkdirSync(project); + writeFileSync(path.join(dir, '.nvmrc'), '24\n'); + expect((await init(project, { yes: true, ci: 'github-actions' })).exitCode).toBe(0); + expect(existsSync(path.join(project, '.github'))).toBe(false); + expect(read(workflow)).toContain(' working-directory: e2e\n'); + expect(read(workflow)).toContain(' node-version-file: .nvmrc\n'); + expect(read(workflow)).toContain("hashFiles('e2e/package-lock.json')"); + expect(output()).toContain('Created ../.github/workflows/e2e.yml (GitHub Actions)'); + }); + + it('reads the key and the start command from an existing config', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/web': '*' } })); + stubPackage('@openrouter/ai-sdk-provider', 'export const openrouter = () => undefined;'); + writeFileSync(path.join(dir, 'e2e.config.ts'), [ + "import { openrouter } from '@openrouter/ai-sdk-provider';", + "export default { model: openrouter, targets: [{ platform: 'web', app: { url: 'http://localhost:3100', command: { executable: 'npm', args: ['run', 'dev'] } } }] };", + '', + ].join('\n')); + expect((await init(dir, { yes: true, ci: 'github-actions' })).exitCode).toBe(0); + expect(read(workflow)).toContain('OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}'); + expect(output()).not.toContain('Nothing starts the app in CI'); + }); + + it('writes .gitlab-ci.yml with --ci gitlab and names the CI/CD variable to add', async () => { + expect(await init(dir, { yes: true, ci: 'gitlab' })).toMatchObject({ exitCode: 0, ci: 'gitlab' }); + expect(read('.gitlab-ci.yml')).toContain(' - npx e2e run --reporter list,junit\n'); + expect(output()).toContain('Created .gitlab-ci.yml (GitLab CI/CD)'); + expect(output()).toContain('glab variable set AI_GATEWAY_API_KEY --masked --hidden --raw'); + // A second run finds the job in the pipeline and asks nothing more. + expect(await init(dir, { yes: true, ci: 'gitlab' })).toMatchObject({ result: 'already-initialized' }); + expect(output()).toContain('Exists, not touching: .gitlab-ci.yml'); + }); + + it('leaves an existing .gitlab-ci.yml alone and writes a file for it to include', async () => { + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'build:\n script: [make]\n'); + await init(dir, { yes: true, ci: 'gitlab' }); + expect(read('.gitlab-ci.yml')).toBe('build:\n script: [make]\n'); + expect(read('.gitlab/e2e.gitlab-ci.yml')).toMatch(/^e2e-web:\n/mu); + expect(output()).toContain('.gitlab-ci.yml exists, not touching it; add this to it to run the e2e jobs:'); + expect(output()).toMatch(/include:\n\S*\s+- local: \.gitlab\/e2e\.gitlab-ci\.yml/u); + }); + + it('preselects GitLab in a repository with a GitLab remote', async () => { + answers.engines = ['web']; + mkdirSync(path.join(dir, '.git')); + writeFileSync(path.join(dir, '.git', 'config'), '[remote "origin"]\n\turl = https://gitlab.com/acme/app.git\n'); + vi.mocked(clack.confirm).mockResolvedValueOnce(false); + await init(dir); + expect(clack.select).toHaveBeenLastCalledWith(expect.objectContaining({ initialValue: 'gitlab' })); + }); + + it('installs a workspace member at the workspace root with the workspace manager', async () => { + vi.stubEnv('npm_config_user_agent', 'npm/11.0.0'); + mkdirSync(path.join(dir, '.git')); + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ private: true, packageManager: 'pnpm@10.0.0' })); + writeFileSync(path.join(dir, 'pnpm-workspace.yaml'), "packages:\n - 'apps/*'\n"); + writeFileSync(path.join(dir, 'pnpm-lock.yaml'), ''); + const project = path.join(dir, 'apps', 'web'); + mkdirSync(project, { recursive: true }); + expect((await init(project, { yes: true, ci: 'github-actions' })).exitCode).toBe(0); + expect(read(workflow)).toContain(' - name: Install dependencies\n run: pnpm install --frozen-lockfile\n working-directory: .\n'); + expect(read(workflow)).toContain("hashFiles('pnpm-lock.yaml')"); + expect(read(workflow)).toContain(' run: pnpm exec e2e run --reporter list,junit\n'); + }); + + it('reads the target names and platforms from an existing config', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/web': '*', '@e2e-dev/mobile': '*' } })); + writeFileSync(path.join(dir, 'e2e.config.ts'), [ + 'const engine = (platform: string) => ({ platform });', + "export default { targets: [{ name: 'chromium', engine: engine('web') }, { name: 'iphone', engine: engine('ios') }, { name: 'pixel', engine: engine('android') }] };", + '', + ].join('\n')); + await init(dir, { yes: true, ci: 'github-actions' }); + expect(read(workflow)).toContain('run: npx e2e run --target chromium --reporter list,junit'); + expect(read(workflow)).toContain('run: npx e2e run --target iphone --workers 1 --reporter list,junit'); + expect(read(workflow)).toContain('npx e2e run --target pixel --workers 1 --reporter list,junit'); + }); + + it('runs every target in one web job when an existing web config does not load, and says why', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/web': '*' } })); + writeFileSync(path.join(dir, 'e2e.config.ts'), "import { web } from 'not-installed-engine';\nexport default { targets: [{ engine: web() }] };\n"); + await init(dir, { yes: true, ci: 'github-actions' }); + expect(Object.keys((parseYaml(read(workflow)) as { jobs: object }).jobs)).toEqual(['web']); + expect(read(workflow)).toContain('run: npx e2e run --reporter list,junit'); + expect(output()).toContain('Could not read the targets of e2e.config.ts'); + expect(output()).toContain('The pipeline runs every target in one web job'); + expect(output()).not.toContain('No web, iOS, or Android target'); + }); + + it('writes no pipeline when an existing mobile config does not load', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/mobile': '*' } })); + writeFileSync(path.join(dir, 'e2e.config.ts'), "import { mobile } from 'not-installed-engine';\nexport default { targets: [{ engine: mobile() }] };\n"); + await init(dir, { yes: true, ci: 'github-actions' }); + expect(existsSync(path.join(dir, workflow))).toBe(false); + expect(output()).toContain('No pipeline: the mobile jobs need the config\'s targets'); + }); + + it('loads an existing config only after the changes are confirmed and the dependencies installed', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/web': '*' } })); + writeFileSync(path.join(dir, 'e2e.config.ts'), "import { engine } from 'late-engine';\nexport default { targets: [{ name: 'chromium', engine }] };\n"); + // The install puts the engine in place; before it, the config could not load. + vi.mocked(spawnSync).mockImplementationOnce(() => { + stubPackage('late-engine', "export const engine = { platform: 'web' };"); + return spawnResult(0); + }); + await init(dir, { yes: true, ci: 'github-actions', install: true }); + expect(read(workflow)).toContain('run: npx e2e run --reporter list,junit'); + expect(output()).not.toContain('Could not read the targets'); + + // Cancelled at the confirmation, the config never runs. + rmSync(path.join(dir, workflow)); + writeFileSync(path.join(dir, 'e2e.config.ts'), "globalThis.configRan = true;\nexport default { targets: [{ platform: 'web' }] };\n"); + vi.mocked(clack.confirm).mockResolvedValueOnce(false); + await init(dir, { ci: 'github-actions', skills: [], mcp: [] }); + expect((globalThis as { configRan?: boolean }).configRan).toBeUndefined(); + }); + + it('warns that a model served on this machine is out of the runner\'s reach', async () => { + await init(dir, { yes: true, gateway: 'openai-compatible', ci: 'gitlab' }); + expect(output()).toContain('The model endpoint is on this machine, so agent steps fail in CI'); + rmSync(path.join(dir, 'e2e.config.ts')); + rmSync(path.join(dir, '.gitlab-ci.yml')); + await init(dir, { yes: true, gateway: 'openai-compatible', endpoint: 'https://llm.example/v1', ci: 'gitlab' }); + expect(output().match(/The model endpoint is on this machine/gu)).toHaveLength(1); + }); + + it('reads a loopback endpoint from an existing config too', async () => { + writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { e2e: '*', '@e2e-dev/web': '*' } })); + stubPackage('@ai-sdk/openai-compatible', 'export const createOpenAICompatible = (options) => options;'); + writeFileSync(path.join(dir, 'e2e.config.ts'), [ + "import { createOpenAICompatible } from '@ai-sdk/openai-compatible';", + "const model = createOpenAICompatible({ name: 'local',", + " baseURL: 'http://127.0.0.1:11434/v1',", + '});', + "export default { model, targets: [{ platform: 'web' }] };", + '', + ].join('\n')); + await init(dir, { yes: true, ci: 'gitlab' }); + expect(output()).toContain('The model endpoint is on this machine, so agent steps fail in CI'); + }); + + // A junction needs no symlink privilege on Windows. + it.skipIf(!symlinks && process.platform !== 'win32')('writes nothing through a symlinked .github folder', async () => { + const elsewhere = mkdtempSync(path.join(os.tmpdir(), 'e2e-init-elsewhere-')); + try { + symlinkSync(elsewhere, path.join(dir, '.github'), process.platform === 'win32' ? 'junction' : 'dir'); + expect(await init(dir, { yes: true, ci: 'github-actions' })).toMatchObject({ exitCode: 0 }); + expect(readdirSync(elsewhere)).toEqual([]); + expect(output()).toContain(`Symlink, not touching: .github -> ${realpathSync(elsewhere)} (.github/workflows/e2e.yml)`); + } finally { + rmSync(elsewhere, { recursive: true, force: true }); + } + }); + + it('warns that a subscription gateway has no key to give CI', async () => { + await init(dir, { yes: true, gateway: 'chatgpt', ci: 'github-actions' }); + expect(read(workflow)).not.toContain('env:'); + expect(output()).toContain('ChatGPT Plus/Pro subscription signs in on this machine only, so agent steps fail in CI'); + }); + }); }); diff --git a/packages/e2e/tests/unit/init-ci.test.ts b/packages/e2e/tests/unit/init-ci.test.ts new file mode 100644 index 0000000000..314a9051fa --- /dev/null +++ b/packages/e2e/tests/unit/init-ci.test.ts @@ -0,0 +1,506 @@ +import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { parse } from 'yaml'; +import { + ciJobs, + configStartsApp, + configTargets, + configUsesLocalModel, + detectMobileBuilds, + findNodeVersionFile, + findRepositoryRoot, + gatewaysInConfig, + detectCiService, + getCiService, + readNodeMajor, + renderGithubWorkflow, + renderGitlabPipeline, + type CiJobs, + type WorkflowContext, +} from '../../src/cli/init/ci.ts'; + +const base: WorkflowContext = { manager: 'npm', projectDir: '', installDir: '', secrets: [], jobs: { web: 'all' } }; + +/** Expo on both phones beside a web target: the template's own case. */ +const expoJobs: CiJobs = { + web: ['web'], + ios: { targets: ['ios'], build: { kind: 'expo' } }, + android: { targets: ['android'], build: { kind: 'expo', prebuild: true } }, +}; + +/** One step or job of a rendered pipeline, as YAML reads it. */ +type Node = Record; + +/** A rendered GitHub workflow's job and its steps. */ +function githubJob(text: string, name = 'web'): { job: Node; steps: Node[]; step: (name: string) => Node; uses: (action: string) => Node | undefined } { + const job = (parse(text) as { jobs: Record }).jobs[name]!; + const steps = job['steps'] as Node[]; + return { + job, + steps, + step: (stepName) => steps.find((step) => step['name'] === stepName)!, + uses: (action) => steps.find((step) => String(step['uses']).startsWith(`${action}@`)), + }; +} + +/** The templates as shipped, read the way init reads them. */ +const templates = path.resolve(import.meta.dirname, '../../templates/ci'); + +describe('renderGithubWorkflow', () => { + it('writes the template unchanged for npm at the repository root, Expo on both phones, and the model key from secrets', () => { + expect(renderGithubWorkflow({ ...base, secrets: ['AI_GATEWAY_API_KEY'], jobs: expoJobs })).toBe(readFileSync(path.join(templates, 'github-actions.yml'), 'utf8')); + }); + + it('writes only the web job, running every target, when the config has no phone target', () => { + const workflow = parse(renderGithubWorkflow(base)) as { jobs: Record }; + expect(Object.keys(workflow.jobs)).toEqual(['web']); + expect(githubJob(renderGithubWorkflow(base)).step('Run e2e')['run']).toBe('npx e2e run --reporter list,junit'); + }); + + it('writes only the phone jobs for a mobile-only config, each naming its targets', () => { + const workflow = renderGithubWorkflow({ ...base, jobs: { ios: { targets: ['iphone', 'ipad'], build: { kind: 'expo' } }, android: expoJobs.android! } }); + expect(Object.keys((parse(workflow) as { jobs: object }).jobs)).toEqual(['ios', 'android']); + // No line of only spaces where the web job was. + expect(workflow).toContain('jobs:\n ios:\n'); + expect(workflow).not.toMatch(/^ +$/mu); + // The emulator's E2E_DEVICE stays when there is no model key to pass. + expect(githubJob(workflow, 'android').step('Run e2e')['env']).toEqual({ E2E_DEVICE: 'emulator-5554' }); + expect(githubJob(workflow, 'ios').step('Run e2e')['run']).toBe('npx e2e run --target iphone,ipad --workers 1 --reporter list,junit'); + expect((githubJob(workflow, 'android').step('Run e2e')['with'] as Node)['script']).toBe( + 'adb install -r android/app/build/outputs/apk/release/app-release.apk\nnpx e2e run --target android --workers 1 --reporter list,junit\n', + ); + }); + + it('runs the web job on every target off the phones when a config has both', () => { + const workflow = renderGithubWorkflow({ ...base, jobs: { ...expoJobs, web: ['web', 'api'] } }); + expect(githubJob(workflow).step('Run e2e')['run']).toBe('npx e2e run --target web,api --reporter list,junit'); + }); + + it('builds a bare React Native app with its workspace, through Bundler when it has a Gemfile', () => { + const workflow = renderGithubWorkflow({ ...base, jobs: { + ios: { targets: ['ios'], build: { kind: 'react-native', workspace: 'MyApp', bundler: true } }, + android: { targets: ['android'], build: { kind: 'react-native' } }, + } }); + expect(githubJob(workflow, 'ios').step('Build the app')['run']).toBe( + "bundle install\n(cd ios && bundle exec pod install)\nxcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build\n", + ); + expect(githubJob(workflow, 'android').step('Build the app')['run']).toBe('(cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=x86_64)'); + expect(workflow).toContain(' # Installs the pods, then builds the workspace for the simulator into build/.\n - name: Build the app\n'); + }); + + it('skips Expo prebuild when android/ is already there', () => { + const workflow = renderGithubWorkflow({ ...base, jobs: { android: { targets: ['android'], build: { kind: 'expo', prebuild: false } } } }); + expect(githubJob(workflow, 'android').step('Build the app')['run']).toBe('(cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=x86_64)'); + }); + + it('writes a build step that fails until it is replaced for any other app, saying where the build goes', () => { + const workflow = renderGithubWorkflow({ ...base, jobs: { ios: { targets: ['ios'], build: { kind: 'custom' } }, android: { targets: ['android'], build: { kind: 'custom' } } } }); + expect(githubJob(workflow, 'ios').step('Build the app')['run']).toBe('echo "Replace this step with your app\'s build for the simulator, with the .app under build/" >&2\nexit 1\n'); + expect(workflow).toContain(" # Replace this step with your app's release build, an APK at android/app/build/outputs/apk/release/app-release.apk.\n"); + }); + + it('keeps the template comments and pinned tags', () => { + const workflow = renderGithubWorkflow({ ...base, manager: 'pnpm', pnpmVersion: '10' }); + expect(workflow).toMatch(/^# Written by `e2e init --ci github-actions`/u); + expect(workflow).toContain(' branches: [main]\n'); + expect(workflow).toMatch(/uses: pnpm\/action-setup@[0-9a-f]{40} # v\d/u); + }); + + it('sets no env block when the run reads no key', () => { + expect(githubJob(renderGithubWorkflow(base)).step('Run e2e')).not.toHaveProperty('env'); + expect(githubJob(renderGithubWorkflow({ ...base, jobs: expoJobs }), 'ios').step('Run e2e')).not.toHaveProperty('env'); + }); + + it('sets up every job for a workspace member: its folder, the install at the workspace root, and the cache keys', () => { + const workflow = renderGithubWorkflow({ ...base, manager: 'pnpm', projectDir: 'apps/app', installDir: '', pnpmVersion: '10', jobs: expoJobs }); + for (const name of ['web', 'ios', 'android']) { + const { job, step, uses } = githubJob(workflow, name); + expect(job['defaults']).toEqual({ run: { 'working-directory': 'apps/app' } }); + expect(Object.keys(job).indexOf('defaults')).toBe(Object.keys(job).indexOf('steps') - 1); + expect(uses('pnpm/action-setup')?.['with']).toEqual({ version: '10' }); + expect(step('Install dependencies')).toEqual({ name: 'Install dependencies', run: 'pnpm install --frozen-lockfile', 'working-directory': '.' }); + expect((step('Upload the report')['with'] as Node)['path']).toBe('apps/app/.e2e/report.json\napps/app/.e2e/junit.xml\napps/app/.e2e/results\n'); + expect(workflow).not.toContain("hashFiles('package-lock.json')"); + } + // The emulator action runs its script from the project, which defaults.run does not reach. + expect((githubJob(workflow, 'android').step('Run e2e')['with'] as Node)['working-directory']).toBe('apps/app'); + expect(githubJob(workflow, 'ios').step('Build the app')['run']).toBe('pnpm exec expo run:ios --configuration Release --device generic --no-bundler --output build/ios'); + }); + + it('points the cache at a lockfile below the root, and pnpm at the package.json with its packageManager field', () => { + const below = githubJob(renderGithubWorkflow({ ...base, manager: 'pnpm', projectDir: 'e2e', installDir: 'e2e', nodeVersionFile: '.nvmrc' })); + expect(below.uses('pnpm/action-setup')?.['with']).toEqual({ package_json_file: 'e2e/package.json' }); + expect(below.uses('actions/setup-node')?.['with']).toEqual({ 'node-version-file': '.nvmrc', cache: 'pnpm', 'cache-dependency-path': 'e2e/pnpm-lock.yaml' }); + expect(below.step('Install dependencies')).not.toHaveProperty('working-directory'); + expect(githubJob(renderGithubWorkflow({ ...base, manager: 'pnpm' })).uses('pnpm/action-setup')).not.toHaveProperty('with'); + }); + + it.each([ + { yarnBerry: false, install: 'yarn install --frozen-lockfile' }, + { yarnBerry: true, install: 'yarn install --immutable' }, + ])('enables corepack before setup-node for Yarn and installs with $install', ({ yarnBerry, install }) => { + const { steps, step } = githubJob(renderGithubWorkflow({ ...base, manager: 'yarn', yarnBerry })); + expect(steps.findIndex((item) => item['run'] === 'corepack enable')).toBe(steps.findIndex((item) => String(item['uses']).startsWith('actions/setup-node@')) - 1); + expect(step('Install dependencies')['run']).toBe(install); + expect(step('Run e2e')['run']).toBe('yarn e2e run --reporter list,junit'); + }); + + it('sets up Bun and keeps setup-node for the runner without a cache', () => { + const { step, uses } = githubJob(renderGithubWorkflow({ ...base, manager: 'bun' })); + expect(uses('oven-sh/setup-bun')).toBeDefined(); + expect(uses('actions/setup-node')?.['with']).toEqual({ 'node-version': 24 }); + expect(step('Install dependencies')['run']).toBe('bun install --frozen-lockfile'); + expect(uses('actions/cache')?.['with']).toMatchObject({ key: expect.stringContaining("hashFiles('bun.lock')") }); + expect(step('Run e2e')['run']).toBe('bunx e2e run --reporter list,junit'); + expect(uses('oven-sh/setup-bun')).not.toHaveProperty('with'); + const below = githubJob(renderGithubWorkflow({ ...base, manager: 'bun', projectDir: 'site', installDir: 'site' })); + expect(below.uses('oven-sh/setup-bun')?.['with']).toEqual({ 'bun-version-file': 'site/package.json' }); + }); + + it('keys the caches on Bun\'s older bun.lockb when that is the lockfile', () => { + const workflow = renderGithubWorkflow({ ...base, manager: 'bun', lockfile: 'bun.lockb', jobs: expoJobs }); + expect(workflow).toContain("hashFiles('bun.lockb')"); + expect(workflow).not.toContain("hashFiles('bun.lock')"); + expect((gitlabJob(renderGitlabPipeline({ ...base, manager: 'bun', lockfile: 'bun.lockb' }))['cache'] as Node)['key']).toEqual({ files: ['bun.lockb'] }); + }); + + it('keeps a folder name with a space as one value', () => { + expect(githubJob(renderGithubWorkflow({ ...base, projectDir: 'my app', installDir: 'my app' })).job['defaults']).toEqual({ run: { 'working-directory': 'my app' } }); + }); +}); + +/** A rendered GitLab pipeline's job. */ +function gitlabJob(text: string, name = 'e2e-web'): Node { + return (parse(text) as Record)[name]!; +} + +describe('renderGitlabPipeline', () => { + it('writes the template unchanged for npm at the repository root and Expo on both phones, with no key in the file', () => { + // CI/CD variables reach the job's environment on their own; the file names no key. + expect(renderGitlabPipeline({ ...base, secrets: ['AI_GATEWAY_API_KEY'], jobs: expoJobs })).toBe(readFileSync(path.join(templates, 'gitlab-ci.yml'), 'utf8')); + }); + + it('keeps the header and starts with no blank line when the pipeline has no web job', () => { + const pipeline = renderGitlabPipeline({ ...base, jobs: { android: expoJobs.android! } }); + expect(pipeline).toMatch(/^# Written by `e2e init --ci gitlab`[^\n]*\n# the default branch, one job per platform\. See https:\/\/e2e\.com\/docs\/ci\/gitlab\n\n# GitLab's hosted runners/u); + expect(Object.keys(parse(pipeline) as object)).toEqual(['.e2e-mobile', 'e2e-android']); + }); + + it('writes only the web job, without the mobile base or its comment, when the config has no phone target', () => { + const pipeline = renderGitlabPipeline(base); + expect(Object.keys(parse(pipeline) as object)).toEqual(['e2e-web']); + expect(pipeline).not.toContain('self-managed'); + expect(gitlabJob(pipeline)['script']).toContain('npx e2e run --reporter list,junit'); + }); + + it('runs the phone jobs on self-managed runners: install, build, a device of their own, then the targets', () => { + const pipeline = renderGitlabPipeline({ ...base, jobs: { ios: { targets: ['iphone'], build: { kind: 'react-native', workspace: 'MyApp', bundler: false } }, android: { targets: ['android'], build: { kind: 'custom' } } } }); + expect(Object.keys(parse(pipeline) as object)).toEqual(['.e2e-mobile', 'e2e-ios', 'e2e-android']); + const ios = gitlabJob(pipeline, 'e2e-ios'); + expect(ios['tags']).toEqual(['macos']); + expect(ios['script']).toEqual([ + 'npm ci', + '(cd ios && pod install)', + "xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' -derivedDataPath build", + 'export E2E_DEVICE=$(xcrun simctl create "e2e-$CI_JOB_ID" "iPhone 17 Pro" com.apple.CoreSimulator.SimRuntime.iOS-26-5)', + 'echo "$E2E_DEVICE" > "$CI_PROJECT_DIR/.simulator-udid"', + 'xcrun simctl bootstatus "$E2E_DEVICE" -b', + `xcrun simctl install "$E2E_DEVICE" "$(find build -maxdepth 5 -name '*.app' -type d | head -n 1)"`, + 'npx e2e run --target iphone --workers 1 --reporter list,junit', + ]); + const android = gitlabJob(pipeline, 'e2e-android')['script'] as string[]; + expect(android.slice(0, 3)).toEqual(['npm ci', 'echo "Replace this step with your app\'s build, an APK at android/app/build/outputs/apk/release/app-release.apk" >&2', 'exit 1']); + expect(android.at(-1)).toBe('npx e2e run --target android --workers 1 --reporter list,junit'); + expect(pipeline).toContain(" # Replace this step with your app's release build, an APK at android/app/build/outputs/apk/release/app-release.apk.\n - echo"); + }); + + it('installs at the workspace root and runs in the project folder', () => { + const pipeline = renderGitlabPipeline({ ...base, manager: 'pnpm', projectDir: 'apps/web', installDir: '', pnpmVersion: '10', nodeMajor: '26', jobs: expoJobs }); + const job = gitlabJob(pipeline); + expect(job['image']).toBe('node:26'); + expect(job['script']).toEqual([ + 'npm install --global pnpm@10', + 'pnpm config set store-dir .pnpm-store', + 'pnpm install --frozen-lockfile', + 'cd "$CI_PROJECT_DIR/apps/web"', + 'pnpm exec e2e-web install chromium --with-deps', + 'pnpm exec e2e run --target web --reporter list,junit', + ]); + expect(job['cache']).toEqual({ key: { files: ['pnpm-lock.yaml'] }, paths: ['.cache/ms-playwright/', '.pnpm-store/'] }); + expect(job['artifacts']).toMatchObject({ + paths: ['apps/web/.e2e/report.json', 'apps/web/.e2e/junit.xml', 'apps/web/.e2e/results/'], + reports: { junit: 'apps/web/.e2e/junit.xml' }, + }); + expect(job['variables']).not.toHaveProperty('COREPACK_ENABLE_DOWNLOAD_PROMPT'); + expect((gitlabJob(pipeline, 'e2e-ios')['script'] as string[]).slice(0, 3)).toEqual([ + 'pnpm install --frozen-lockfile', + 'cd "$CI_PROJECT_DIR/apps/web"', + 'pnpm exec expo run:ios --configuration Release --device generic --no-bundler --output build/ios', + ]); + expect(gitlabJob(pipeline, '.e2e-mobile')['artifacts']).toMatchObject({ reports: { junit: 'apps/web/.e2e/junit.xml' } }); + }); + + it('changes into a project below the root before the install, and lets corepack read packageManager', () => { + const job = gitlabJob(renderGitlabPipeline({ ...base, manager: 'pnpm', projectDir: 'site', installDir: 'site' })); + expect(job['variables']).toMatchObject({ COREPACK_ENABLE_DOWNLOAD_PROMPT: '0' }); + // Node 25 and later ship no corepack. + expect((job['script'] as string[]).slice(0, 3)).toEqual(['cd "$CI_PROJECT_DIR/site"', 'command -v corepack || npm install --global corepack', 'corepack enable']); + expect(job['cache']).toEqual({ key: { files: ['site/pnpm-lock.yaml'] }, paths: ['.cache/ms-playwright/', 'site/.pnpm-store/'] }); + }); + + it.each([ + // The node:26 image has no Yarn 1, and Node 25 and later no corepack. + { yarnBerry: false, install: ['command -v yarn || npm install --global yarn', 'yarn install --frozen-lockfile --cache-folder .yarn-cache'], store: ['.yarn-cache/'] }, + { yarnBerry: true, install: ['command -v corepack || npm install --global corepack', 'corepack enable', 'yarn install --immutable'], store: [] }, + ])('installs Yarn dependencies with $install', ({ yarnBerry, install, store }) => { + const job = gitlabJob(renderGitlabPipeline({ ...base, manager: 'yarn', yarnBerry })); + expect((job['script'] as string[]).slice(0, install.length)).toEqual(install); + expect((job['cache'] as Node)['paths']).toEqual(['.cache/ms-playwright/', ...store]); + }); + + it('installs Bun into the node image and runs the web job beside a phone job', () => { + const job = gitlabJob(renderGitlabPipeline({ ...base, manager: 'bun', jobs: { web: ['web'], ios: expoJobs.ios! } })); + expect((job['script'] as string[]).slice(0, 2)).toEqual(['npm install --global bun', 'bun install --frozen-lockfile']); + expect((job['script'] as string[]).at(-1)).toBe('bunx e2e run --target web --reporter list,junit'); + expect((job['cache'] as Node)['paths']).toEqual(['.cache/ms-playwright/']); + }); + + it('renames every job, and what the phone jobs extend, beside a pipeline that has one of the names', () => { + const pipeline = renderGitlabPipeline({ ...base, jobs: expoJobs, jobSuffix: '-run' }); + expect(Object.keys(parse(pipeline) as object)).toEqual(['e2e-web-run', '.e2e-mobile-run', 'e2e-ios-run', 'e2e-android-run']); + expect(gitlabJob(pipeline, 'e2e-ios-run')['extends']).toBe('.e2e-mobile-run'); + expect(pipeline).toMatch(/^# Written by `e2e init --ci gitlab`/u); + expect(pipeline).toContain(' # GitLab caches only paths inside the project.\n'); + }); +}); + +describe('ciJobs', () => { + const builds = { ios: { kind: 'expo' }, android: { kind: 'expo', prebuild: true } } as const; + + it('gives each phone platform its job and runs everything else in the web job', () => { + expect(ciJobs([{ name: 'web', platform: 'web' }], builds)).toEqual({ web: 'all' }); + expect(ciJobs([{ name: 'chromium', platform: 'web' }, { name: 'api', platform: 'custom' }, { name: 'iphone', platform: 'ios' }, { name: 'pixel', platform: 'android' }], builds)).toEqual({ + web: ['chromium', 'api'], + ios: { targets: ['iphone'], build: builds.ios }, + android: { targets: ['pixel'], build: builds.android }, + }); + expect(ciJobs([{ name: 'ios', platform: 'ios' }, { name: 'ipad', platform: 'ios' }], builds)).toEqual({ ios: { targets: ['ios', 'ipad'], build: builds.ios } }); + }); + + it('runs targets of other platforms, such as HTTP tests, in the web job, beside phone jobs too', () => { + expect(ciJobs([{ name: 'default', platform: 'custom' }], builds)).toEqual({ web: 'all' }); + expect(ciJobs([{ name: 'api', platform: 'custom' }, { name: 'ios', platform: 'ios' }], builds)).toEqual({ web: ['api'], ios: { targets: ['ios'], build: builds.ios } }); + expect(ciJobs([], builds)).toEqual({}); + }); +}); + +describe('configTargets', () => { + it('names and places each target the way e2e run resolves it, leaving out a target it would refuse', () => { + expect(configTargets({ targets: [ + { engine: { platform: 'web' } }, + { name: 'iphone', engine: { platform: 'ios' } }, + { name: 'api', platform: 'custom' }, + { name: 'unknown' }, + // A platform that contradicts its engine is a config error to e2e run. + { name: 'mixed', platform: 'web', engine: { platform: 'ios' } }, + ] } as never)).toEqual([{ name: 'web', platform: 'web' }, { name: 'iphone', platform: 'ios' }, { name: 'api', platform: 'custom' }]); + expect(configTargets({} as never)).toEqual([]); + }); +}); + +describe('detectMobileBuilds', () => { + let dir: string; + + beforeEach(() => { + dir = mkdtempSync(path.join(os.tmpdir(), 'e2e-init-builds-')); + }); + + afterEach(() => { + rmSync(dir, { recursive: true, force: true }); + }); + + it('builds Expo with CNG, and skips prebuild when android/ is committed', () => { + expect(detectMobileBuilds(dir, (name) => name === 'expo')).toEqual({ ios: { kind: 'expo' }, android: { kind: 'expo', prebuild: true } }); + mkdirSync(path.join(dir, 'android')); + writeFileSync(path.join(dir, 'android', 'gradlew'), ''); + expect(detectMobileBuilds(dir, (name) => name === 'expo').android).toEqual({ kind: 'expo', prebuild: false }); + }); + + it('builds bare React Native from its workspace and Gradle wrapper, else falls back to a step to replace', () => { + const rn = (name: string) => name === 'react-native'; + expect(detectMobileBuilds(dir, rn)).toEqual({ ios: { kind: 'custom' }, android: { kind: 'custom' } }); + mkdirSync(path.join(dir, 'ios', 'MyApp.xcworkspace'), { recursive: true }); + mkdirSync(path.join(dir, 'ios', 'Pods.xcworkspace')); + mkdirSync(path.join(dir, 'android')); + writeFileSync(path.join(dir, 'android', 'gradlew'), ''); + writeFileSync(path.join(dir, 'Gemfile'), ''); + expect(detectMobileBuilds(dir, rn)).toEqual({ ios: { kind: 'react-native', workspace: 'MyApp', bundler: true }, android: { kind: 'react-native' } }); + }); + + it('writes a step to replace for a native app', () => { + expect(detectMobileBuilds(dir, () => false)).toEqual({ ios: { kind: 'custom' }, android: { kind: 'custom' } }); + }); + + it('reads no workspace from an ios that is a file', () => { + writeFileSync(path.join(dir, 'ios'), ''); + expect(detectMobileBuilds(dir, (name) => name === 'react-native').ios).toEqual({ kind: 'custom' }); + }); +}); + +describe('the pinned actions', () => { + const repository = path.resolve(import.meta.dirname, '../../../..'); + + /** Every Markdown page under `dir`, recursively, leaving out installed packages. */ + function pages(dir: string): string[] { + return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const absolute = path.join(dir, entry.name); + if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : pages(absolute); + return entry.isFile() && /\.mdx?$/u.test(entry.name) ? [absolute] : []; + }); + } + + /** Every `uses: owner/action@ # ` in `text`, as [action, pin]. */ + function pinsIn(text: string): [string, string][] { + return [...text.matchAll(/uses: ([\w.-]+\/[\w.-]+)@(\S+ # \S+)/gu)].map(([, action, ref]) => [action!, `${action!}@${ref!}`]); + } + + it('match the pins in the docs and the e2e skill, so a user copying either gets what init writes', () => { + const pins = new Map(readdirSync(templates).flatMap((file) => pinsIn(readFileSync(path.join(templates, file), 'utf8')))); + expect([...pins.keys()]).toEqual(expect.arrayContaining(['actions/checkout', 'actions/setup-node', 'pnpm/action-setup', 'oven-sh/setup-bun'])); + const mismatches = [...pages(path.join(repository, 'docs')), ...pages(path.join(repository, 'skills/e2e'))].flatMap((file) => + pinsIn(readFileSync(file, 'utf8')) + .filter(([action, pin]) => pins.has(action) && pins.get(action) !== pin) + .map(([, pin]) => `${path.relative(repository, file)}: ${pin}`)); + expect(mismatches).toEqual([]); + }); +}); + +describe('project detection', () => { + let dir: string; + + beforeEach(() => { + dir = mkdtempSync(path.join(os.tmpdir(), 'e2e-init-ci-')); + }); + + afterEach(() => { + rmSync(dir, { recursive: true, force: true }); + }); + + it('finds the repository above the project, or falls back to the init directory', () => { + const project = path.join(dir, 'apps', 'web'); + mkdirSync(project, { recursive: true }); + expect(findRepositoryRoot(project, project)).toBe(project); + mkdirSync(path.join(dir, '.git')); + expect(findRepositoryRoot(project, project)).toBe(dir); + // A worktree or submodule has a .git file. + writeFileSync(path.join(dir, 'apps', '.git'), 'gitdir: elsewhere\n'); + expect(findRepositoryRoot(project, project)).toBe(path.join(dir, 'apps')); + }); + + it('tells GitHub from GitLab by the remote, a .github folder, or a .gitlab-ci.yml', () => { + mkdirSync(path.join(dir, '.git')); + expect(detectCiService(dir)).toBeUndefined(); + writeFileSync(path.join(dir, '.git', 'config'), '[remote "origin"]\n\turl = git@gitlab.com:acme/app.git\n'); + expect(detectCiService(dir)).toBe('gitlab'); + writeFileSync(path.join(dir, '.git', 'config'), '[remote "origin"]\n\turl = https://github.com/acme/app.git\n'); + expect(detectCiService(dir)).toBe('github-actions'); + rmSync(path.join(dir, '.git'), { recursive: true }); + mkdirSync(path.join(dir, '.github')); + expect(detectCiService(dir)).toBe('github-actions'); + // A GitLab pipeline file wins over a .github folder that holds only templates. + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'build:\n script: [make]\n'); + expect(detectCiService(dir)).toBe('gitlab'); + }); + + it('writes .gitlab-ci.yml, or a file beside an existing one, and counts a pipeline that runs e2e as set up', () => { + const gitlab = getCiService('gitlab'); + expect(gitlab.locate(dir)).toEqual({ file: '.gitlab-ci.yml', existing: false }); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'build:\n script: [make]\n'); + expect(gitlab.locate(dir)).toEqual({ + file: '.gitlab/e2e.gitlab-ci.yml', + existing: false, + include: 'include:\n - local: .gitlab/e2e.gitlab-ci.yml', + }); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'e2e:\n script: [npx e2e run]\n'); + expect(gitlab.locate(dir)).toEqual({ file: '.gitlab-ci.yml', existing: true }); + }); + + it('says when an existing pipeline lists stages without test, where the included job runs', () => { + const gitlab = getCiService('gitlab'); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'stages: [build, deploy]\nbuild:\n script: [make]\n'); + expect(gitlab.locate(dir).note).toBe('The e2e jobs run in the test stage; add test to the stages in .gitlab-ci.yml'); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'stages:\n - build\n - test\nbuild:\n script: [make]\n'); + expect(gitlab.locate(dir).note).toBeUndefined(); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'build:\n script: [make]\n'); + expect(gitlab.locate(dir).note).toBeUndefined(); + // A stage whose name only contains test is another stage. + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'stages: [build, unit-test]\n'); + expect(gitlab.locate(dir).note).toBe('The e2e jobs run in the test stage; add test to the stages in .gitlab-ci.yml'); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), "stages:\n - 'build'\n - \"test\" # unit and e2e\nvariables: {}\n"); + expect(gitlab.locate(dir).note).toBeUndefined(); + }); + + it('renames the jobs beside a pipeline that already has a job of one of their names', () => { + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'e2e:\n script: [npx cypress run]\n'); + expect(getCiService('gitlab').locate(dir)).not.toHaveProperty('jobSuffix'); + writeFileSync(path.join(dir, '.gitlab-ci.yml'), 'e2e-ios:\n script: [npx detox test]\n'); + expect(getCiService('gitlab').locate(dir)).toMatchObject({ file: '.gitlab/e2e.gitlab-ci.yml', jobSuffix: '-run' }); + }); + + it('counts any GitHub workflow that runs e2e as set up', () => { + const github = getCiService('github-actions'); + expect(github.locate(dir)).toEqual({ file: '.github/workflows/e2e.yml', existing: false }); + mkdirSync(path.join(dir, '.github', 'workflows'), { recursive: true }); + writeFileSync(path.join(dir, '.github', 'workflows', 'lint.yml'), 'jobs: {}\n'); + expect(github.locate(dir).existing).toBe(false); + writeFileSync(path.join(dir, '.github', 'workflows', 'ci.yaml'), 'jobs:\n test:\n steps:\n - run: npx e2e run\n'); + expect(github.locate(dir)).toEqual({ file: '.github/workflows/ci.yaml', existing: true }); + }); + + it.each([ + ['24\n', '24'], + ['v24.8.0', '24'], + ['26.1', '26'], + ['lts/*', undefined], + ])('reads the Node major from %j', (content, major) => { + writeFileSync(path.join(dir, '.nvmrc'), content); + expect(readNodeMajor(path.join(dir, '.nvmrc'))).toBe(major); + }); + + it('reads the Node version file nearest the project, never above the repository', () => { + const project = path.join(dir, 'repo', 'e2e'); + mkdirSync(project, { recursive: true }); + writeFileSync(path.join(dir, '.nvmrc'), '22\n'); + expect(findNodeVersionFile(project, path.join(dir, 'repo'))).toBeUndefined(); + writeFileSync(path.join(dir, 'repo', '.node-version'), '24\n'); + expect(findNodeVersionFile(project, path.join(dir, 'repo'))).toBe(path.join(dir, 'repo', '.node-version')); + writeFileSync(path.join(project, '.nvmrc'), '26\n'); + expect(findNodeVersionFile(project, path.join(dir, 'repo'))).toBe(path.join(project, '.nvmrc')); + }); +}); + +describe('reading an existing config', () => { + it('names the gateways by the import line init writes', () => { + expect(gatewaysInConfig("import { gateway } from 'ai';\n").map(({ id }) => id)).toEqual(['vercel']); + expect(gatewaysInConfig("import { chatgpt } from 'e2e/oauth/chatgpt';\n").map(({ id }) => id)).toEqual(['chatgpt']); + expect(gatewaysInConfig("import { anthropic } from '@ai-sdk/anthropic';\n")).toEqual([]); + // As a formatter or a hand edit leaves it: double quotes, other names, no semicolon. + expect(gatewaysInConfig('import { generateText, gateway } from "ai"\n').map(({ id }) => id)).toEqual(['vercel']); + expect(gatewaysInConfig('import {openrouter} from "@openrouter/ai-sdk-provider";\n').map(({ id }) => id)).toEqual(['openrouter']); + expect(gatewaysInConfig("import { gatewayish } from 'ai';\n")).toEqual([]); + }); + + it('finds an OpenAI-compatible baseURL on this machine', () => { + expect(configUsesLocalModel(" baseURL: 'http://127.0.0.1:11434/v1',")).toBe(true); + expect(configUsesLocalModel(' baseURL: "http://localhost:8080/v1",')).toBe(true); + expect(configUsesLocalModel(" baseURL: 'https://llm.example/v1',")).toBe(false); + expect(configUsesLocalModel(" // baseURL: 'http://127.0.0.1:11434/v1',")).toBe(false); + }); + + it('tells a command the runner starts from a commented-out one', () => { + expect(configStartsApp(" command: { executable: 'npm', args: ['run', 'dev'] },")).toBe(true); + expect(configStartsApp(" // command: { executable: 'npm', args: ['run', 'dev'] },")).toBe(false); + }); +}); diff --git a/packages/e2e/tests/unit/init-examples.test.ts b/packages/e2e/tests/unit/init-examples.test.ts index 131d8ff357..49b13a9a1d 100644 --- a/packages/e2e/tests/unit/init-examples.test.ts +++ b/packages/e2e/tests/unit/init-examples.test.ts @@ -57,7 +57,7 @@ async function* chunks(buffer: Buffer, size = 700): AsyncGenerator { } /** A GitHub tarball of the `with-vite` example as the codeload service serves it. */ -function viteTarball(root = 'e2e-e2e-1.0.0'): Buffer { +function viteTarball(root = 'e2e-e2e-1.0.0', config = 'export default {};\n'): Buffer { return gzipSync( tar([ { name: 'pax_global_header', type: 'g', content: '52 comment=0123456789abcdef0123456789abcdef01234567\n' }, @@ -66,7 +66,7 @@ function viteTarball(root = 'e2e-e2e-1.0.0'): Buffer { { name: `${root}/examples/`, type: '5' }, { name: `${root}/examples/with-vite/`, type: '5' }, { name: `${root}/examples/with-vite/package.json`, content: '{\n "name": "e2e-example-with-vite",\n "private": true,\n "scripts": { "test:e2e": "e2e run" },\n "devDependencies": { "e2e": "^0.15.2", "@e2e-dev/web": "^0.11.1", "vite": "^8.3.2" }\n}\n' }, - { name: `${root}/examples/with-vite/e2e.config.ts`, content: 'export default {};\n' }, + { name: `${root}/examples/with-vite/e2e.config.ts`, content: config }, { name: `${root}/examples/with-vite/.gitignore`, content: 'node_modules/\n' }, { name: `${root}/examples/with-vite/tests/`, type: '5' }, { name: `${root}/examples/with-vite/tests/deterministic.e2e.ts`, content: '// tests\n' }, @@ -178,6 +178,18 @@ describe('e2e init --example', () => { expect(output()).toContain('Next: cd my-app, then npm install, then npm run test:e2e'); }); + it('writes a CI pipeline for the example before its dependencies are installed', async () => { + // Its engine is not installed yet, so the config cannot load. (@e2e-dev/web would resolve beside this CLI here.) + const config = "import { web } from 'engine-not-installed-yet';\nexport default { targets: [{ engine: web() }] };\n"; + vi.stubGlobal('fetch', vi.fn(async () => new Response(new Uint8Array(viteTarball(undefined, config))))); + const target = path.join(dir, 'my-app'); + expect(await init(target, { yes: true, example: 'with-vite', ci: 'github-actions' })).toMatchObject({ exitCode: 0, ci: 'github-actions' }); + const workflow = readFileSync(path.join(target, '.github/workflows/e2e.yml'), 'utf8'); + expect(workflow).toContain('run: npx e2e run --reporter list,junit'); + // clack wraps the long warning to the terminal's width. + expect(output()).toContain('The pipeline runs every target in one'); + }); + it('falls back to main when the tag is missing and says so', async () => { const fetchMock = vi.fn(async (url: string) => (url.includes('refs/tags/') ? new Response('', { status: 404 }) : new Response(new Uint8Array(viteTarball('e2e-main'))))); vi.stubGlobal('fetch', fetchMock); @@ -232,7 +244,7 @@ describe('e2e init --example', () => { vi.stubGlobal('fetch', vi.fn(async () => new Response(new Uint8Array(viteTarball())))); mkdirSync(path.join(dir, '.git')); vi.mocked(clack.confirm).mockResolvedValue(false); - expect(await init(dir, { interactive: true, example: 'with-vite', skills: [], mcp: [] })).toMatchObject({ exitCode: 0, result: 'cancelled' }); + expect(await init(dir, { interactive: true, example: 'with-vite', skills: [], mcp: [], ci: 'none' })).toMatchObject({ exitCode: 0, result: 'cancelled' }); expect(readdirSync(dir)).toEqual(['.git']); }); }); diff --git a/packages/e2e/tests/unit/telemetry-events.test.ts b/packages/e2e/tests/unit/telemetry-events.test.ts index 1a550ca6ad..4642029e57 100644 --- a/packages/e2e/tests/unit/telemetry-events.test.ts +++ b/packages/e2e/tests/unit/telemetry-events.test.ts @@ -69,6 +69,7 @@ describe('telemetry events', () => { gateway: 'openai-compatible', skill: true, mcp: false, + ci: 'github-actions', install: true, }), ).toEqual({ @@ -82,6 +83,7 @@ describe('telemetry events', () => { gateway: 'openai-compatible', skill: true, mcp: false, + ci: 'github-actions', install: true, }, }); diff --git a/plugins/e2e/skills/e2e/references/running.md b/plugins/e2e/skills/e2e/references/running.md index 084793f539..a95c08aeca 100644 --- a/plugins/e2e/skills/e2e/references/running.md +++ b/plugins/e2e/skills/e2e/references/running.md @@ -224,6 +224,15 @@ CI mode is on when `CI` is set (not `0` or `false`): `retries` 1, `ONLY_IN_CI`, the replay cache `read-only` unless the config sets a mode explicitly (`cache: 'read-write'` or `cache.mode`), `reuseExisting` ignored. +`npx e2e init --yes --ci github-actions` writes a workflow like this one with +a job per platform the config's targets run on (web, iOS, Android), for the +project's package manager and model key; `--ci gitlab` writes the same jobs as +`.gitlab-ci.yml` (or `.gitlab/e2e.gitlab-ci.yml` to include beside an existing +one), its mobile jobs on self-managed runners. The mobile jobs build an Expo or +bare React Native app; for any other app, replace the failing build step. It +leaves existing pipeline files alone. Set `app.command` in the config so the +runner starts the app. + ```yaml # .github/workflows/e2e.yml # Omits the github() reporter: it needs pull-requests: write and diff --git a/plugins/e2e/skills/e2e/references/setup.md b/plugins/e2e/skills/e2e/references/setup.md index 0afc20fb9a..c63c7b02a7 100644 --- a/plugins/e2e/skills/e2e/references/setup.md +++ b/plugins/e2e/skills/e2e/references/setup.md @@ -47,7 +47,8 @@ Gateway, installs the skill in `.agents/skills/` (`.claude/skills/e2e` symlinks to it), registers MCP in `.mcp.json`, `.cursor/mcp.json`, and `.codex/config.toml`, skips installing dependencies. A flag per question overrides one default: `--engine` (`web,mobile` for both), `--gateway`, `--endpoint`, `--skills`, -`--mcp` (comma-separated locations, or `none`), `--install`; `npx e2e init --help` lists the values. +`--mcp` (comma-separated locations, or `none`), `--ci github-actions`, `--ci gitlab`, or `--ci none` (a +pipeline with a job per platform; `--yes` writes none), `--install`; `npx e2e init --help` lists the values. To start a new app from one of the repo's examples instead, run `npx e2e init my-app --example with-vite` (or `with-expo`, `with-flutter`, ...): it downloads the example into an empty directory with its config and tests, then diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c161c1ef13..cdaa6665ec 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -563,6 +563,9 @@ importers: toml-eslint-parser: specifier: 1.0.3 version: 1.0.3 + yaml: + specifier: ^2.9.0 + version: 2.9.0 zod: specifier: 4.6.7 version: 4.6.7 diff --git a/skills/e2e/references/running.md b/skills/e2e/references/running.md index 084793f539..a95c08aeca 100644 --- a/skills/e2e/references/running.md +++ b/skills/e2e/references/running.md @@ -224,6 +224,15 @@ CI mode is on when `CI` is set (not `0` or `false`): `retries` 1, `ONLY_IN_CI`, the replay cache `read-only` unless the config sets a mode explicitly (`cache: 'read-write'` or `cache.mode`), `reuseExisting` ignored. +`npx e2e init --yes --ci github-actions` writes a workflow like this one with +a job per platform the config's targets run on (web, iOS, Android), for the +project's package manager and model key; `--ci gitlab` writes the same jobs as +`.gitlab-ci.yml` (or `.gitlab/e2e.gitlab-ci.yml` to include beside an existing +one), its mobile jobs on self-managed runners. The mobile jobs build an Expo or +bare React Native app; for any other app, replace the failing build step. It +leaves existing pipeline files alone. Set `app.command` in the config so the +runner starts the app. + ```yaml # .github/workflows/e2e.yml # Omits the github() reporter: it needs pull-requests: write and diff --git a/skills/e2e/references/setup.md b/skills/e2e/references/setup.md index 0afc20fb9a..c63c7b02a7 100644 --- a/skills/e2e/references/setup.md +++ b/skills/e2e/references/setup.md @@ -47,7 +47,8 @@ Gateway, installs the skill in `.agents/skills/` (`.claude/skills/e2e` symlinks to it), registers MCP in `.mcp.json`, `.cursor/mcp.json`, and `.codex/config.toml`, skips installing dependencies. A flag per question overrides one default: `--engine` (`web,mobile` for both), `--gateway`, `--endpoint`, `--skills`, -`--mcp` (comma-separated locations, or `none`), `--install`; `npx e2e init --help` lists the values. +`--mcp` (comma-separated locations, or `none`), `--ci github-actions`, `--ci gitlab`, or `--ci none` (a +pipeline with a job per platform; `--yes` writes none), `--install`; `npx e2e init --help` lists the values. To start a new app from one of the repo's examples instead, run `npx e2e init my-app --example with-vite` (or `with-expo`, `with-flutter`, ...): it downloads the example into an empty directory with its config and tests, then