Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/init-ci-workflow.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions docs/ci/github-actions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<SetupPrompt>

Expand Down
3 changes: 3 additions & 0 deletions docs/ci/gitlab.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

<SetupPrompt>

Expand Down
88 changes: 87 additions & 1 deletion docs/reference/cli.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>` | 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 <ids>` | The engines for a new config: `web`, `mobile`, or `none`. Comma-separated or repeated; `web,mobile` writes a target for each. Default: asked. |
| `--gateway <id>` | The model gateway for agent steps in a new config: `vercel`, `openrouter`, `openai-compatible`, `chatgpt`, `copilot`, `opencode-console`, `grok`, or `none`. Default: asked. |
| `--endpoint <url>` | 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 <dirs>` | Where to install the agent skill: `.agents/skills`, `.claude/skills`, or `none`. Comma-separated or repeated. Default: asked. |
| `--mcp <files>` | Where to register the MCP server: `.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`, or `none`. Comma-separated or repeated. Default: asked. |
| `--ci <id>` | 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.
Expand Down Expand Up @@ -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`
Expand All @@ -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/<topic>.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) |

<a id="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 <its targets> --reporter
list,junit`, and keeps `.e2e/report.json`, `.e2e/junit.xml`, and
`.e2e/results/`.

<CodeGroup>
```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
```
</CodeGroup>

| 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.

<a id="starting-from-an-example" />
##### Starting from an example
Expand Down
1 change: 1 addition & 0 deletions docs/telemetry.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

</Accordion>
<Accordion title="e2e_upgrade_completed, once per e2e upgrade">
Expand Down
9 changes: 7 additions & 2 deletions packages/core/src/config/targets.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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 {
Comment thread
kacperkapusciak marked this conversation as resolved.
Resolved
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`);
Expand Down
2 changes: 2 additions & 0 deletions packages/e2e/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
"dist",
"docs",
"schema/*.schema.json",
"templates",
"skills",
"NOTICE"
],
Expand All @@ -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": {
Expand Down
1 change: 1 addition & 0 deletions packages/e2e/src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
Expand Down
Loading
Loading