Write Playwright Tests with Gemini CLI: Setup Guide (2026)

Google changed who can use Gemini CLI this summer, and most setup guides for playwright with gemini cli never noticed. The ones that rank today still tell you to sign in with a free Google account, which stopped serving requests on June 18, 2026.

That leaves teams with a tool that opens a browser, reads a page, and writes a test, but a login path that quietly fails. Worse, the tests it writes often guess at selectors and skip waits, so the first CI run goes red.

This guide fixes both problems. You will install the current Gemini CLI, pick an auth method that still works, wire in Playwright MCP, load Playwright skills, and generate tests that pass in CI, with every command and config shown as it runs on a real machine.

Why playwright with gemini cli looks different in 2026

Gemini CLI is Google's open-source terminal agent. You type a request in plain English, and the agent reads files, runs commands, and calls tools on your behalf. Version 0.59.0 shipped on September 8, 2026, and the project still releases weekly.

On May 19, 2026, Google announced a transition. Since June 18, 2026, Gemini CLI no longer serves requests for Google AI Pro, Google AI Ultra, or people using it free through Gemini Code Assist for individuals. Those users are pointed to Antigravity CLI instead.

The same announcement is clear about who keeps access. Gemini Code Assist Standard and Enterprise licenses are unchanged. Paid Gemini API keys and Gemini Enterprise Agent Platform keys still work. The GitHub repository stays Apache 2.0 licensed with no changes, and Google keeps shipping security fixes and model updates.

So why bother with Gemini CLI at all? Three reasons hold up in practice:

• It runs anywhere Node runs. No IDE, no desktop app, and it works over SSH and inside CI containers.
• Its MCP support is mature. Gemini CLI has had first-class Model Context Protocol support since 2025, and that is exactly what Playwright MCP needs.
• It is scriptable. A headless mode with JSON output lets you chain "generate test, run test, fix test" without a human in the loop.

The npm download curve tells the honest story. Interest peaked in April 2026, then fell after the consumer cutoff. Enterprise and API-key teams are the ones still installing it, and this guide is written for them.

If you are on a consumer plan, the comparison section near the end shows how the same Playwright setup carries over to Antigravity CLI. Everyone else can move straight to the prerequisites.

Prerequisites for playwright with gemini cli

Before you type a single prompt, make sure the environment can actually run a browser and talk to Gemini. Most failed setups trace back to one of these four items.

1. Node.js 20 or newer. The Gemini CLI package declares a Node engine of 20 or above. Playwright MCP itself needs Node 18 or newer, so 20 covers both.
2. A Playwright project. Run npm init playwright@latest if you do not have one. Playwright 1.63.0 is the current release.
3. A working auth path. One of a paid Gemini API key, a Vertex AI project, or a Gemini Code Assist Standard or Enterprise license.
4. An app to test. The examples here use the public TestDino demo store at storedemo.testdino.com, a small electronics shop with search, cart, and login pages, so you can follow along before pointing the agent at your own staging URL.

The auth choice decides your daily budget, so pick it deliberately. These are the limits Google publishes on the Gemini CLI quota page as of September 2026.

A single Playwright MCP session can burn dozens of requests, because every snapshot, click, and assertion is a separate tool call. Budget for that when you choose a tier.

With the environment sorted, the install itself takes about a minute.

Step 1: install Gemini CLI and choose an auth method

Install the CLI globally, then confirm the version. The output below is from a Windows 10 machine with Node 22.

npm install -g @google/gemini-cli
gemini --version
# 0.59.0

Homebrew users can run brew install gemini-cli instead, and npx @google/gemini-cli works if you would rather not install anything. All three give you the same binary.

Pick the auth method that survives 2026

Run gemini once inside your project folder. The first screen asks how you want to authenticate. Choose option 2 for an API key or option 3 for Vertex AI. Option 1 only works if your organization holds a Code Assist Standard or Enterprise license.

For the API-key route, create a key in Google AI Studio and store it in an env file that Gemini CLI reads automatically. The project-level file wins over the user-level one.

GEMINI_API_KEY=your_key_here

For Vertex AI, set the project and location instead. Gemini CLI also honors these when you export them in your shell profile.

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=my-gcp-project
GOOGLE_CLOUD_LOCATION=us-central1

If you pick option 1 on a personal account, the browser login succeeds and then the CLI rejects the session. This is what the cutoff looks like in practice, and it is the reason the API key path comes first in this guide.

Choose a model before you generate anything

Gemini CLI defaults to Auto routing, which picks a Pro model for complex prompts and a Flash model for simple ones. On the current 0.59 build the picker lists gemini-3.1-pro-preview and gemini-3.5-flash behind Auto, with a Manual option to pin any model. Inside a session, /model opens that picker, and the flag below does the same at launch.

gemini -m gemini-3-pro-preview

Test generation is a "complex prompt" in practice. The model has to hold a page snapshot, your rules file, and the spec it is writing at the same time. Pinning a Pro model for generation and dropping back to Flash for quick questions keeps quality up and cost down.

There is one trap on an unpaid API key. That tier is limited to Flash models, so a Pro request comes back as a 404 or a 429, and Auto routing keeps retrying while the session shows "Thinking" for minutes. Pin a Flash model in the project settings and the problem disappears. In our runs, Gemini 3 Flash handled the whole generate, run, and heal loop against the demo store without trouble.

{
  "model": { "name": "gemini-3-flash-preview" }
}

Next, give the agent a browser.

Step 2: connect the Playwright MCP server to Gemini CLI

Playwright MCP is the bridge. It exposes browser actions as tools that any MCP client can call, and Gemini CLI is one of those clients. This is the single most searched part of any gemini cli mcp setup, and it is also where most people get stuck on folder trust.

Five-step overview from installing Gemini CLI to streaming AI-generated Playwright test results into TestDino

Add the server with one command

Gemini CLI ships a management command that writes the config for you. Run it from your project root so the server lands in project scope.

gemini mcp add playwright npx @playwright/mcp@latest
# MCP server "playwright" added to project settings. (stdio)

That command creates or updates the project settings file. The result is the same JSON block that Cursor, VS Code, and Claude Code use, which is why the Playwright MCP setup for Cursor and this guide feel so similar.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Prefer a user-wide install so every project gets the server? Add -s user and the block goes to the settings file in your home directory instead.

Trust the folder, or nothing connects

Here is the gotcha, visible in the last line of the screenshot above. Gemini CLI enforces a fail-closed workspace trust model. In an untrusted folder, project settings are ignored, env files are skipped, and MCP servers do not connect.

Launch gemini in the folder and the trust dialog appears before anything else. Pick "Trust folder" and the decision is saved to a trusted folders file in your home directory. You can change it later with /permissions.

In CI, where there is no dialog, use the flag or env var below.

gemini --skip-trust -p "Open https://storedemo.testdino.com and list the product categories on the home page"
# or, for the whole job:
export GEMINI_CLI_TRUST_WORKSPACE=true

Verify the connection

Once trusted, start a session and run /mcp list. You should see the playwright server marked as connected with a tool list under it. /mcp desc prints a description for every tool, and /mcp reload re-discovers tools if you change the server arguments.

The core tool set covers browser_navigate, browser_snapshot, browser_click, browser_type, browser_fill_form, browser_take_screenshot, and browser_wait_for. Those are the same tools that power the accessibility tree approach: the model reads structured page semantics, not pixels.

Flags worth adding to the args array

The default server is headed and shares a persistent browser profile. Both are fine for a first run and wrong for CI. These are the options from the Playwright MCP README that matter for test generation.

A production-friendly version of the config looks like this. The testing capability is the one most guides skip, and it is the difference between a guessed locator and a verified one.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--caps", "testing",
        "--viewport-size", "1280x720"
      ],
      "timeout": 60000
    }
  }
}

Stop approving every click

By default, Gemini CLI asks before each tool call. That is thirty prompts for a single login flow. You have three levers, from broad to precise:

• --approval-mode auto_edit auto-approves edit tools but still asks for MCP calls.
• --trust on the mcp add command bypasses confirmation for that server only.
• A policy rule in your user policies folder, which is the most controlled option.

[[rule]]
mcpName = "playwright"
decision = "allow"
priority = 200

The policy engine layers admin, user, and workspace rules, and a user rule beats the built-in defaults. Avoid --yolo for anything that touches a real environment, because it approves shell commands too. With the Playwright server trusted, browser calls run silently while a shell command still stops for a yes, which is the balance you want.

With the browser connected and approvals tamed, the next job is teaching the agent how your team writes tests.

Step 3: add Playwright skills and a GEMINI.md file

Connecting MCP gives the model eyes. It does not give it taste. Left alone, Gemini will happily write CSS selectors, sprinkle fixed waits, and share state across tests. Two files fix that: an agent skill pack and a project context file.

Install the Playwright skill pack

Gemini CLI supports the Agent Skills open standard. A skill is a folder with a SKILL.md file that stays dormant until the model decides it is relevant, so it costs no context until it is needed. Skills live in the user folder for all projects or in the project folder for one repo.

The open-source TestDino Playwright skill packages 70 guides across five packs: core, ci, playwright-cli, pom, and migration. The install is one command, and the repo is MIT licensed.

npx skills add testdino-hq/playwright-skill

The skills installer drops the pack into .agents/skills, which Gemini CLI reads as a workspace alias. If you prefer Gemini's own installer, point it at the repository and scope it to the workspace. The --consent flag skips the security prompt for non-interactive installs.

gemini skills install https://github.com/testdino-hq/playwright-skill.git --scope workspace --consent
gemini skills list

Inside a session, /skills confirms what was discovered. When a prompt matches a skill's description, the model calls activate_skill, you approve it once, and the guide body loads into the conversation.

Write a GEMINI.md that states your rules

GEMINI.md is Gemini CLI's project context file. The CLI loads the global file from your home directory, then every GEMINI.md from the workspace root down, and concatenates them into each prompt. /memory show prints the merged result so you can check what the model actually sees.

Keep it short and specific. Every line should be a rule the model would otherwise break. This version is a good starting point for an existing Playwright repo.

# Playwright test rules
- Use the Playwright MCP server to inspect the live page before writing any locator.
- Prefer getByRole, getByLabel, getByPlaceholder, and getByText. Never use CSS or XPath.
- Never call page.waitForTimeout(). Use web-first assertions like expect(locator).toBeVisible().
- One user flow per test. No shared state between tests.
- Read baseURL from playwright.config.ts; never hardcode the host in a spec.
- Put new specs in tests/ and name them <feature>.spec.ts.
- After writing a spec, run `npx playwright test <file>` and fix failures before reporting done.

Running /init in an empty project generates a starter GEMINI.md by scanning the directory, which is handy if you want a base to edit rather than a blank file. The Playwright best practices guide is a good source for rules worth adding as your suite grows.

Now you have a browser, a skill pack, and rules. Time to generate something.

Step 4: generate, run, and heal your first test

Point Playwright at the app you want to test. The examples below use the TestDino demo store, so set it as the base URL once and every generated spec can use relative paths. Then launch gemini in the project and describe the flow the way you would explain it to a new teammate. This is the core of how to use gemini cli with playwright day to day.

use: {
  baseURL: 'https://storedemo.testdino.com',
  trace: 'on-first-retry',
},

Prompt for a spec, not for a script

The difference between a prompt that works and one that produces junk is whether you ask for verification. Tell the agent to inspect the page first, and tell it what done looks like.

Use the Playwright MCP server to open https://storedemo.testdino.com/products.
Explore the page and take an accessibility snapshot. Then open /cart.
Write tests/store.spec.ts covering: searching for "GoPro" shows the GoPro HERO10 Black
product and hides the others, and the cart page shows "Your cart is empty" with a
Continue Shopping button. Follow GEMINI.md. Run the spec with
npx playwright test tests/store.spec.ts and fix it until it passes.

Gemini will call browser_navigate, then browser_snapshot, then start typing into the search box. With the testing capability enabled, it can call browser_generate_locator on the elements it plans to use, so the locators are checked against the real page before they land in the file.

What a good generated spec looks like

The spec below is what Gemini 3 Flash produced from that prompt on the first attempt, with the rules file in place. Every locator is role or placeholder based, and every check is a web-first assertion that waits on its own.

import { test, expect } from '@playwright/test';

test.describe('TestDino demo store', () => {
  test('search narrows the catalog to a matching product', async ({ page }) => {
    await page.goto('/products');
    await page.getByPlaceholder('Search products...').fill('GoPro');
    await expect(page.getByRole('heading', { name: 'GoPro HERO10 Black' })).toBeVisible();
    await expect(page.getByRole('heading', { name: 'JBL Charge 4 Bluetooth Speaker' })).toBeHidden();
  });

  test('cart page starts empty', async ({ page }) => {
    await page.goto('/cart');
    await expect(page.getByRole('heading', { name: 'Your cart is empty' })).toBeVisible();
    await expect(page.getByRole('button', { name: 'Continue Shopping' })).toBeVisible();
  });
});

If the output uses CSS selectors or a fixed sleep, the fix is not a better prompt. It is a missing rule in GEMINI.md or an inactive skill. Check /memory show first. The Playwright locators guide explains why role-based locators survive UI changes that break CSS.

Run it and let the agent heal failures

Ask the agent to run the spec, or run it yourself. A passing run prints one line per test and a summary count.

npx playwright test tests/store.spec.ts
#   ok 1 [chromium] › tests\store.spec.ts:13:7 › TestDino demo store › cart page starts empty (652ms)
#   ok 2 [chromium] › tests\store.spec.ts:4:7 › TestDino demo store › search narrows the catalog to a matching product (696ms)
#   2 passed (1.4s)

When Gemini runs the tests itself, it closes the turn with a summary of what it explored, what it wrote, and whether the run passed. Read that summary against your rules file. If it mentions guessing a locator instead of reading a snapshot, that is a rule to tighten.

When a test fails, paste the error back and ask for a diagnosis, not a patch. The agent can re-open the page with MCP, compare the current snapshot to the locator that failed, and tell you whether the UI changed or the test was wrong.

tests/store.spec.ts failed with a timeout on getByRole('heading', { name: 'Your basket is empty' }).
Open https://storedemo.testdino.com/cart with Playwright MCP, snapshot the page, and tell me
whether the heading text changed. Only edit the test if the app is correct.

That last sentence matters. An agent that "fixes" a test around a real bug hides the bug. Playwright's own planner, generator, and healer agents follow the same rule, though note that npx playwright init-agents currently supports only the vscode, claude, codex, and opencode loops, so with Gemini CLI you drive these steps through prompts instead.

Tip: Enable checkpointing in settings.json with general.checkpointing.enabled set to true. Every file-modifying tool call then snapshots your project into a shadow git repo, and /restore rolls back a bad edit without touching your real history.

Pick the right browser channel for the job

MCP is not the only way to give Gemini CLI a browser. Playwright's own README now recommends the CLI plus skills route for high-throughput coding agents, because it avoids loading large tool schemas and full accessibility trees into context. The trade-off is visibility: the model only sees what each command prints.

TestDino measured the gap while building the Cursor guide: roughly 114,000 tokens for an MCP session versus about 27,000 for the same work through the Playwright CLI. The full breakdown lives in Playwright CLI vs MCP. For Gemini CLI, the practical rule is MCP for exploration and debugging, CLI for long batch generation.

To add the CLI route, install the tool globally and drop its skill into your Gemini skills folder.

npm install -g @playwright/cli@latest
npx degit microsoft/playwright-cli/skills/playwright-cli ~/.gemini/skills/playwright-cli

Run the whole loop headless in CI

Gemini CLI switches to headless mode whenever you pass -p or run without a TTY. Combine it with JSON output and the trust env var, and you can generate or repair tests as a pipeline step. Exit code 0 means success, 1 is a general error, 42 is an input error, and 53 means the turn limit was hit.

GEMINI_CLI_TRUST_WORKSPACE=true gemini \
  --approval-mode auto_edit \
  --output-format json \
  -p "Run npx playwright test. For each failure, open the page on https://storedemo.testdino.com with Playwright MCP, diagnose the cause, and propose a fix as a diff. Do not edit files."

The demand for this workflow is not niche. Downloads of the Playwright MCP package grew more than tenfold between September 2025 and July 2026, which is a decent proxy for how many agents now have a browser attached.

Generated tests are only useful if you can see how they behave over time. That is the last step.

Step 5: stream results to TestDino and fix flaky tests

AI-written tests need more scrutiny than hand-written ones, not less. You want to know which generated specs fail after every deploy, which fail one run in five, and which never fail at all. TestDino gives you that view from a Playwright reporter, with no upload step.

Add the reporter

Install the package and register it in your Playwright config next to your existing reporters. Results stream to the dashboard as each test finishes.

npm install @testdino/playwright

import { defineConfig } from '@playwright/test';
export default defineConfig({
  reporter: [
    ['list'],
    ['@testdino/playwright', { token: process.env.TESTDINO_TOKEN }],
  ],
  use: { trace: 'on-first-retry' },
});

Create the token under Project Settings and API Keys in the TestDino app, then export it as TESTDINO_TOKEN locally and as a repository secret in CI. Keep trace: 'on-first-retry' on, because the dashboard's embedded trace viewer is where you will debug the agent's failures.

A local run now ends with a run summary box and a link to the live results. There is no upload command to remember, which matters when the agent is the one running the tests.

Wire it into GitHub Actions

The workflow is standard Playwright plus one env var. The same pattern works for GitLab, Azure DevOps, Jenkins, and the other providers covered in Playwright in GitHub Actions.

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install --with-deps
      - name: Run tests with TestDino
        env:
          TESTDINO_TOKEN: ${{ secrets.TESTDINO_TOKEN }}
        run: npx playwright test

Tag the specs Gemini wrote, for example with @ai-generated, so you can compare their flake rate against the hand-written ones. That comparison is the fastest way to find out whether your GEMINI.md rules are working.

Give Gemini CLI your CI history with TestDino MCP

Playwright MCP shows the agent the page as it is right now. It cannot tell the agent that a test has failed on WebKit every Tuesday for a month. TestDino's MCP server fills that gap with 38 tools for querying runs, failures, and flaky tests. Add it beside the Playwright server.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated", "--caps", "testing"]
    },
    "testdino": {
      "command": "npx",
      "args": ["-y", "@testdino/mcp@latest"],
      "env": { "TESTDINO_PAT": "$TESTDINO_PAT" }
    }
  }
}

The personal access token is created under User Settings and Personal Access Tokens, and it is different from the project API key the reporter uses. Gemini CLI expands $TESTDINO_PAT from your environment, so the secret never sits in the settings file. Restart the session, run /mcp list, and the TestDino tools appear beside the Playwright ones. Ask the agent to run health once to confirm it can see your projects.

Tip: Before you fix flaky tests one by one, put a number on the problem. TestDino's free tools include a flaky cost calculator that turns debug hours and CI reruns into a yearly dollar figure, plus a locator playground for checking getByRole queries before the agent uses them. Find them at TestDino's free tools.

With both servers connected, a single prompt closes the loop: find the flakiest test, open the page, diagnose, and propose a fix.

Use the TestDino MCP tools to list the 3 flakiest tests in the last 20 runs of
the main branch. For the top one, open the failing page on
https://storedemo.testdino.com with Playwright MCP, compare the current
accessibility snapshot to the failing locator, and explain the root cause.
Propose a fix but do not edit the file yet.

The Playwright flaky tests guide covers the usual root causes, and the agent's diagnosis will usually match one of them.

Now that the full loop works, it is worth asking whether Gemini CLI is the right agent to run it.

Playwright with gemini cli vs Antigravity CLI, Claude Code, and Cursor

Every tool in this table uses the same Playwright MCP server and the same JSON config block. What differs is who can log in, where the config lives, and how much the tool does without an MCP server at all.

Moving the setup to Antigravity CLI

If your account was moved on June 18, the Playwright config carries over with two edits. Antigravity CLI reads MCP servers from a global config file in the .gemini/config folder or a workspace file at .agents/mcp_config.json, and it uses serverUrl instead of url or httpUrl for remote servers. The stdio block for Playwright is unchanged.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated", "--caps", "testing"]
    }
  }
}

GEMINI.md is still parsed, and Gemini CLI extensions can be converted with agy plugin import gemini. The full walkthrough for Google's IDE lives in Playwright tests with Antigravity.

When another agent fits better

Choose Claude Code when you want a multi-agent pipeline with strong file reasoning; the Claude Code with Playwright guide walks through a four-agent setup. Choose Cursor when your team lives in the editor and wants inline generation; Cursor with Playwright covers it. Choose Gemini CLI when you need an open-source, scriptable agent behind an enterprise license or your own API key.

For a wider survey of the agents in this space, agentic testing tools compared lines up a dozen of them.

Conclusion

Setting up playwright with gemini cli in 2026 comes down to five decisions: an auth path that still serves requests, a Playwright MCP server with headless and testing flags, a trusted folder, a short GEMINI.md, and a reporter that shows how the generated tests behave over weeks rather than minutes.

Key takeaways:

• Check your tier first. Free, Pro, and Ultra accounts moved to Antigravity CLI on June 18, 2026. Paid API keys, Vertex AI, and Code Assist licenses keep Gemini CLI.
• Trust the folder or nothing connects. The fail-closed model disables MCP servers, env files, and project settings until you approve the workspace.
• Rules beat prompts. A seven-line GEMINI.md plus the Playwright skill pack removes CSS selectors and fixed waits from generated output far more reliably than any prompt wording.
• Measure the agent's tests separately. Tag them, stream them to TestDino, and let the flake history decide whether the rules are working.

The broader picture of MCP servers, built-in agents, and self-healing tests is in the Playwright AI ecosystem, and how to write Playwright tests with AI covers the prompting side in more depth.

FAQs