Cypressとは｜使い方・コマンド早見表・エラーの直し方【v16対応】

Cypress は、テストを書いた spec ファイルを Cypress App が読み込み、本物のブラウザの中でアプリと一緒に動かします。通信は Cypress が見張っていて、cy.intercept() で差し替えられます。

flowchart TD
    A[spec ファイル<br>cy.visit・cy.get] --> B[Cypress App<br>Node.js の本体]
    B --> C[ブラウザ<br>Chrome・Firefox]
    B --> E[intercept<br>通信の差し替え]
    C --> D[テストとアプリが<br>同じ画面で動く]
    D --> F[結果・画像<br>終了コード]

急いでいる人向けに、よく調べられることの答えを先にまとめます。

やりたいこと	書き方	詳しい節
入れる	npm install cypress --save-dev	インストール
画面を開いて書く	npx cypress open	最初のテスト
CI で全部流す	npx cypress run --browser chrome	CI
ページを開く	cy.visit('/')	コマンド早見表
要素を探す	cy.get('[data-cy=submit]')	セレクター
文字で探して押す	cy.contains('追加').click()	コマンド早見表
待つ	cy.wait(1000) ではなく should で条件を書く	待ち方
API を差し替える	cy.intercept('GET', '/api/x', { fixture: 'x.json' })	intercept
秘密の値を読む	cy.env(['password'])（16 で Cypress.env() は削除）	16 の変更点

確認環境：Ubuntu 24.04.4 LTS・Node.js 22.22.2。Cypress 16.2.0 の npm パッケージ（CLI と型定義）を CYPRESS_INSTALL_BINARY=0 で npm 10.9.7 と npm 12.2.1 から入れ、CLI（--version・--help・run --help・verify・cache）の出力、npm 12 のインストールスクリプトの許可の動き、この記事の spec・設定ファイル・コンポーネントテストを TypeScript 7.0.2（React 19.3.1 の型）で型チェックした結果を記録しました。テスト対象の ToDo ページは、記事の spec と同じ3つの場面（フィクスチャ・201・500 の擬似応答）を Chromium 141.0.7390.37 で再現し、表示が spec の期待どおりになることを確かめています。テストの実行画面と実行時の動きは docs.cypress.io の公式ドキュメント（Install・Writing Your First E2E Test・Retry-ability・intercept・fixture・env・expose・session・getByRole・Configuration・Command Line・Launching Browsers・Component Testing・Error Messages・Trade-offs・Changelog）、エラーの文言は GitHub の cypress-io/cypress のソース（error_messages.ts・chai.ts）、CI は cypress-io/github-action の README、料金は cypress.io/pricing、比較は playwright.dev と selenium.dev、npm 12 の変更は npm/cli のリリースノートで確かめました（確認日 2026年10月23日）。

Cypressとは（読み方・できること・無料か）

この節では、Cypress が何で、何ができて、お金がかかるのはどこかが分かります。

Cypress（サイプレス）は、Web アプリを本物のブラウザで動かし、「画面を開く → 入力する → 押す → 結果を確かめる」を自動で行うテストツールです。 テストは JavaScript か TypeScript で書きます。テストの書き方は、テストの枠組みの Mocha（describe・it）と、確かめる書き方の Chai（expect・should）を使います。

無料の部分と有料の部分

名前	何か	料金
Cypress App	テストを書いて動かす本体（npm の cypress）	無料・MIT ライセンス
Cypress Cloud	結果の記録・並列実行の振り分け・不安定なテストの分析	無料プランあり。上は有料
UI Coverage・Cypress Accessibility	画面の網羅率・アクセシビリティの分析	Cloud の有料の追加機能

npm の cypress パッケージの license は MIT で、料金ページにも Cypress App は MIT ライセンスで提供されると書かれています。テストを書いて手元や CI で動かすだけなら、お金はかかりません。Cloud の料金は後の節にまとめました。

最新版は 16.2.0

2026年10月23日時点の npm の最新版は 16.2.0（公式の変更履歴の日付は 2026年10月13日）です。16.0.0（2026年9月1日）は大きな版の変更で、Cypress.env()・cy.exec()・cy.end() が消えました。以前の記事のコードを動かすときに引っかかりやすいので、「15 から 16 への変更点」の節で直し方をまとめています。

E2Eテストとコンポーネントテストの違い

この節では、Cypress の2つのテストの種類と、どちらから書くかが分かります。

比べること	E2E テスト	コンポーネントテスト
開くもの	cy.visit() で URL を開く	cy.mount() で部品を表示する
要るもの	起動したアプリ（開発サーバーなど）	Vite・Webpack の設定（Cypress が使う）
spec の場所（既定）	cypress/e2e/**/*.cy.{js,jsx,ts,tsx}	**/*.cy.{js,jsx,ts,tsx}
起動	cypress open --e2e・run --e2e	cypress open --component・run --component

spec の場所の既定値は、公式の Configuration のページと 16.2.0 の型定義で確かめました。E2E テスト（End to End テスト）は、画面の端から端まで、つまり利用者の操作からサーバーまでを通して確かめるテストです。

Cypressのインストール（npm・必要な環境）

この節では、Cypress を入れる手順、必要な環境、npm 12 で起きるつまずきが分かります。

必要な環境

項目	2026年10月23日時点の公式の要件
Node.js	22.x・24.x・26 以降（16.0.0 で 20 と 25 は対象外に）
OS	macOS 13.5 以降、Windows 10・11（x64）、Ubuntu 22.04 以降、Debian 12 以降 など
パッケージマネージャー	npm 10.1.0 以降、Yarn 1.22.22 以降、pnpm 8 以降、Bun 1.2.22 以降
CI のマシン	2 CPU・メモリ 4GB 以上（長い実行や動画の記録は 8GB 以上）

16.2.0 の package.json の engines も ^22.0.0 || ^24.0.0 || >=26.0.0 でした。

インストールの手順

npm install cypress --save-dev
npx cypress open

Ubuntu 24.04 以降で公式が挙げているライブラリです。

sudo apt-get install libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb

Ubuntu 22.04 と Debian では、libgtk-3-0t64 が libgtk-3-0、libasound2t64 が libasound2 になります。

npm パッケージと本体（バイナリ）は別に入る

npm install cypress で入るのは CLI と型定義などの npm パッケージ（16.2.0 は 7.4MB）で、テストを動かす本体は、そのあとのインストールスクリプト（postinstall）がダウンロードしてキャッシュに置きます。本体が無いときの cypress --version の出力です。

$ npx cypress --version
Cypress package version: 16.2.0
Cypress binary version: not installed
Electron version: not found
Bundled Node version: not found

環境変数	意味（公式の Advanced Installation）
CYPRESS_INSTALL_BINARY	入れる本体の版・URL・ファイル。0 でダウンロードしない
CYPRESS_CACHE_FOLDER	本体のキャッシュの場所を変える
CYPRESS_DOWNLOAD_MIRROR	社内のミラーサーバーから本体を取る
CYPRESS_RUN_BINARY	実行時に使う本体のパス
CYPRESS_VERIFY_TIMEOUT	verify の待ち時間（既定 30000 ミリ秒）

キャッシュの既定の場所は、Linux が ~/.cache/Cypress、macOS が ~/Library/Caches/Cypress、Windows が AppData/Local/Cypress/Cache です。npx cypress cache list で入っている版、npx cypress cache prune で使っていない版の削除ができます。本体のダウンロードは、https_proxy などのプロキシの環境変数に従います。

npm 12 では本体がダウンロードされない（許可が要る）

npm 12.0.0 のリリースノートには「Dependency lifecycle scripts are now blocked by default unless allowed by the root package's allowScripts policy.」とあり、依存パッケージのインストールスクリプトが既定で止まります。npm 12.2.1 で入れた結果です。

$ npm install --save-dev cypress@16.2.0
added 171 packages, and audited 172 packages in 3s
npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts:
npm warn install-scripts   cypress@16.2.0 (postinstall: node dist/index.js --exec install)
npm warn install-scripts
npm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.

この状態では本体が入らず、cypress open は後の節の「No version of Cypress is installed」で止まります。 許可して、スクリプトを流し直します。

npm install-scripts approve cypress
npm rebuild cypress

$ npm install-scripts approve cypress
Approved cypress:
  added cypress@16.2.0

許可は package.json に書き込まれました。

"allowScripts": {
  "cypress@16.2.0": true
}

この形のまま cypress@16.1.1 に入れ替えると、また「install scripts blocked」の警告が出ました。版を上げるたびに許可し直すことになるので、版を付けずに "cypress": true と書き換えて 16.2.0 を入れ直すと、警告は出ずにインストールスクリプトが動きました。pnpm 10 以降でも許可が要り、公式は pnpm --allow-build=cypress add --save-dev cypress（pnpm 10.4.0 以降）を案内しています。

最初のテストを書く（フォルダ構成とcypress.config）

この節では、作られるファイルの役割と、そのまま使える最初の spec が分かります。

フォルダ構成

プロジェクト/
├── cypress.config.ts        … 設定（baseUrl など）
└── cypress/
    ├── e2e/                 … E2E の spec（*.cy.ts）
    ├── fixtures/            … 差し替え用のデータ（todos.json など）
    ├── support/
    │   ├── e2e.ts           … 毎回最初に読まれる。commands を読み込む
    │   └── commands.ts      … カスタムコマンド
    ├── screenshots/         … 失敗したときの画面（cypress run）
    └── downloads/

フォルダ名の既定値（fixturesFolder が cypress/fixtures、screenshotsFolder が cypress/screenshots など）は、16.2.0 の型定義のコメントで確かめました。以前の版（9 まで）の cypress.json と cypress/integration は、10 から cypress.config.js と cypress/e2e に変わっています。

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000', // cy.visit('/') の基準になる
    setupNodeEvents(on, config) {
      on('task', {
        resetDb() {
          // テスト用 DB を初期化する処理（Node.js で動く）
          return null
        },
      })
      return config
    },
  },
})

公式のベストプラクティスでは、baseUrl を設定し、cy.visit() には相対パスを書くことが勧められています。

最初の spec（公式の手順）

公式の「Writing Your First E2E Test」の最後の形です。公式のサンプルサイトを開き、リンクを押して、入力した値を確かめます。

describe('My First Test', () => {
  it('Gets, types and asserts', () => {
    cy.visit('https://example.cypress.io')
    cy.contains('type').click()
    cy.url().should('include', '/commands/actions')
    cy.get('.action-email').type('fake@email.com')
    cy.get('.action-email').should('have.value', 'fake@email.com')
  })
})

公式は、よいテストは「状態を用意する → 操作する → 結果を確かめる」（Arrange・Act・Assert）の3段になると説明しています。

自分のアプリのテスト（ToDo の例）

この記事では、次の小さな ToDo ページをテストします。一覧を /api/todos から読み、フォームで追加します。テストで使う要素には data-cy 属性を付けています。

<form id="form">
  <input data-cy="new-todo" aria-label="やること" required>
  <button type="submit">追加</button>
</form>
<p data-cy="error" hidden>保存できませんでした</p>
<ul id="list"></ul>
<script>
  const list = document.getElementById('list');
  const error = document.querySelector('[data-cy=error]');
  const render = (todo) => {
    const li = document.createElement('li');
    li.dataset.cy = 'todo-item';
    li.textContent = todo.title;
    list.append(li);
  };
  fetch('/api/todos').then((r) => r.json()).then((todos) => todos.forEach(render));
  document.getElementById('form').addEventListener('submit', async (e) => {
    e.preventDefault();
    const input = document.querySelector('[data-cy=new-todo]');
    const res = await fetch('/api/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ title: input.value }),
    });
    if (!res.ok) { error.hidden = false; return; }
    render(await res.json());
    input.value = '';
  });
</script>

このページに対する spec は、cy.intercept の節に完成形を載せています。

よく使うコマンド早見表（cy.visit・get・contains・click・type・should）

この節では、よく使うコマンドの意味と、探し直す（リトライする）かどうかが一覧で分かります。

コマンド	意味	探し直すか
cy.visit('/login')	ページを開く（baseUrl からの相対）	読み込みを待つ
cy.get('[data-cy=email]')	CSS セレクターで要素を探す	する
cy.contains('ログイン')	文字を含む要素を探す	する
cy.contains('button', '追加')	button の中から文字で探す	する
cy.getByRole('button', { name: '追加' })	役割と名前で探す（16.2.0 で追加）	する
.find('li')	前の要素の中から探す	する
.first()・.last()・.eq(2)	何番目かを選ぶ	する
.within(() => {...})	その要素の中だけで続きを書く	―
.click()	押す	しない（1回）
.type('abc{enter}')	入力する。{enter} などの特殊キー	しない
.clear()	入力欄を空にする	しない
.check()・.select('東京')	チェックを入れる・選ぶ	しない
.should('be.visible')	条件を満たすか確かめる	する
.and('contain', '完了')	should の続き	する
cy.url().should('include', '/done')	今の URL を確かめる	する
cy.intercept()	通信を見張る・差し替える	―
cy.wait('@alias')	見張った通信が起きるまで待つ	待つ
cy.fixture('user.json')	フィクスチャを読む	―
cy.request('/api/me')	テストから直接 HTTP を送る	しない
cy.session(id, setup)	ログイン状態を保存して使い回す	―
cy.task('resetDb')	Node.js 側の処理を呼ぶ	しない
.as('name')	別名を付け、@name で使う	―

よく使う should の書き方です。have.length などは jQuery の要素向けの確かめ方（chai-jquery）で、Cypress に入っています。

書き方	確かめること
should('exist')・should('not.exist')	ある・ない
should('be.visible')	見えている
should('have.text', '5')	文字が完全に一致
should('contain', '牛乳')	文字を含む
should('have.value', 'abc')	入力欄の値
should('have.length', 3)	要素の数
should('have.class', 'active')	class がある
should('have.attr', 'href', '/top')	属性の値
should('be.disabled')	無効になっている

待ち方：自動リトライとタイムアウト

この節では、Cypress がどう待つか、cy.wait(1000) を書かない理由、タイムアウトの延ばし方が分かります。

Cypress のコマンドは「探す・確かめる（クエリ）」と「操作する」に分かれます。クエリと should は、条件を満たすまで最大4秒、ページを探し直します。click・type などの操作は1回だけ動きます。

flowchart TD
    A[cy.get で探す] --> B{should の<br>条件を満たす}
    B -->|はい| C[次のコマンドへ]
    B -->|いいえ| D{4秒たった}
    D -->|まだ| A
    D -->|たった| E[Timed out retrying<br>で失敗]

既定の待ち時間（16.2.0）

値は 16.2.0 の型定義のコメント（@default）で確かめました。cy.wait('@alias') は、通信が出るまでを requestTimeout、応答までを responseTimeout で待ちます。

cy.wait(数値) を書かない

// 時間で待つ（公式のベストプラクティスで避ける書き方）
cy.get('[data-cy=save]').click()
cy.wait(3000)

// 条件で待つ
cy.get('[data-cy=save]').click()
cy.contains('保存しました').should('be.visible')

// 通信で待つ
cy.intercept('POST', '/api/todos').as('save')
cy.get('[data-cy=save]').click()
cy.wait('@save').its('response.statusCode').should('eq', 201)

遅い場所だけタイムアウトを延ばす

公式は、全体の defaultCommandTimeout を延ばすことは勧めず、遅いコマンドにだけ timeout を付ける書き方を示しています。

cy.get('[data-cy=report]', { timeout: 10000 }).should('be.visible')

{ timeout: 0 } にすると、探し直さずに1回だけ確かめます。

then の中は探し直されない

.then() は、そこでクエリの連なりを切ります。値を取り出して確かめるときは、should にコールバックを渡すと、条件を満たすまで丸ごと探し直されます。

// 探し直されない
cy.get('[data-cy=total]').then(($el) => {
  expect(Number($el.text())).to.be.gte(1000)
})

// 探し直される
cy.get('[data-cy=total]').should(($el) => {
  expect(Number($el.text())).to.be.gte(1000)
})

操作の後ろにつなげない

click() のあとに .should() などをつなげると、画面が描き直されたときに「the page updated」のエラーになります（エラーの節で原文を載せています）。公式は「Actions should be at the end of chains, not the middle.」として、別名を付けて分ける書き方を示しています。

cy.get('[data-cy=new-todo]').as('input')
cy.get('@input').type('本を返す{enter}')
cy.get('@input').should('have.value', '')

セレクターの選び方（data-cy・getByRole）

この節では、要素の探し方のうち、どれが壊れにくいかが分かります。

公式のベストプラクティスの表を、日本語にまとめました。

書き方	公式の勧め	理由
cy.get('button')	使わない	広すぎて、どのボタンか分からない
cy.get('.btn.btn-large')	使わない	見た目の class が変わると壊れる
cy.get('#main')	控えめに	見た目や JS の都合と結びつく
cy.get('[name="submission"]')	控えめに	name 属性の意味と結びつく
cy.contains('Submit')	場合による	文言が変わると壊れる
cy.getByRole('button', { name: 'Submit' })	場合による	役割と読み上げ名の両方に結びつく
cy.get('[data-cy="submit"]')	常に	テスト専用なので、ほかの変更の影響を受けない

cy.getByRole（16.2.0 で追加）

cy.getByRole() は、ボタン・リンク・見出しなどの役割（ARIA のロール）と、読み上げられる名前で要素を探します。公式の説明では、これまでプラグインの Cypress Testing Library の findByRole() と findAllByRole() で行っていたことを、プラグインなしでできるコマンドです。

cy.getByRole('button', { name: '追加' }).click()
cy.getByRole('link', { name: /^ヘルプ/ })          // 正規表現で前方一致
cy.get('nav').getByRole('link')                      // nav の中だけ
cy.getByRole('tab').filter('[aria-selected="true"]') // 状態はfilterで絞る

• name に文字列を渡すと、名前全体と大文字・小文字まで一致したものだけに当たります。一部一致は正規表現で書きます。
• 既定（native: true）では、HTML の要素そのものが役割を持つもの（<button> など）だけに当たります。role="button" を付けた span などの要素も探すなら native: false を付けます。
• 見つかった要素は全部返ります（findAllByRole() と同じ）。1つに絞るなら .first() などを付けます。

getByRole で探せるページは、スクリーンリーダーでも操作しやすいページです。文言が変わる画面では data-cy を、読み上げの名前も確かめたい画面では getByRole を、と使い分けられます。

cy.interceptでAPIをスタブする（フィクスチャ）

この節では、API の応答を差し替える書き方と、フィクスチャ（差し替え用のデータファイル）の使い方が分かります。

書き方の早見表

やりたいこと	書き方
見張るだけ（本物に送る）	cy.intercept('GET', '/api/todos').as('get')
フィクスチャで返す	cy.intercept('GET', '/api/todos', { fixture: 'todos.json' })
中身を直接書いて返す	cy.intercept('GET', '/api/x', { body: [{ id: 1 }] })
エラーを返す	cy.intercept('POST', '/api/x', { statusCode: 500 })
遅らせる	{ fixture: 'x.json', delay: 2000 }
通信そのものを失敗させる	{ forceNetworkError: true }
1回目だけ差し替える	cy.intercept({ url: '/api/x', times: 1 }, {...})
送った中身を確かめる	cy.wait('@a').its('request.body')
本物の応答を書き換える	req.continue((res) => { ... })

URL には ** などのワイルドカードが使えます。同じ URL に複数の intercept があるときは、後に書いたものから順に当てはめられます。

フィクスチャ（cypress/fixtures/todos.json）

[
  { "id": 1, "title": "牛乳を買う", "done": false },
  { "id": 2, "title": "請求書を送る", "done": true }
]

ToDo ページの spec（完成形）

// cypress/e2e/todo.cy.ts
describe('ToDo アプリ', () => {
  beforeEach(() => {
    cy.intercept('GET', '/api/todos', { fixture: 'todos.json' }).as('getTodos')
    cy.visit('/')
    cy.wait('@getTodos')
  })

  it('一覧にフィクスチャの2件が出る', () => {
    cy.get('[data-cy=todo-item]').should('have.length', 2)
    cy.get('[data-cy=todo-item]').first().should('contain', '牛乳を買う')
  })

  it('入力して追加すると3件になる', () => {
    cy.intercept('POST', '/api/todos', {
      statusCode: 201,
      body: { id: 3, title: '本を返す', done: false },
    }).as('addTodo')

    cy.get('[data-cy=new-todo]').type('本を返す')
    cy.getByRole('button', { name: '追加' }).click()

    cy.wait('@addTodo').its('request.body').should('deep.equal', { title: '本を返す' })
    cy.get('[data-cy=todo-item]').should('have.length', 3)
  })

  it('サーバーが 500 を返したらエラーを出す', () => {
    cy.intercept('POST', '/api/todos', { statusCode: 500 }).as('addTodo')
    cy.get('[data-cy=new-todo]').type('失敗する{enter}')
    cy.wait('@addTodo')
    cy.contains('保存できませんでした').should('be.visible')
  })
})

この spec を TypeScript 7.0.2 と Cypress 16.2.0 の型定義で型チェックすると、エラーは0件でした。同じ3つの場面（GET にフィクスチャの2件、POST に 201、POST に 500）を Chromium で擬似応答にして ToDo ページを動かすと、次の結果になり、spec の期待と一致しました。

場面1 一覧の表示   : ['牛乳を買う', '請求書を送る']（2件）
場面2 追加         : 送った本文 {'title': '本を返す'} / 一覧は3件
場面3 500 のとき   : 「保存できませんでした」が表示された
差し替えなし       : 本物のサーバーの1件が表示された

差し替えると、サーバーのデータに関係なく同じ結果になります。 本物の API とつないだテストも少し残すと、API の変更にも気づけます。

型チェックでは気づけない書き間違い

次の3つの書き間違いを型チェックにかけると、エラーになったのは3行目の timeout だけでした。

it('typo', () => {
  cy.get('li').should('have.lenght', 2)                         // length の綴り違い
  cy.visit('/', { timeout: '10000' })                            // 数値でなく文字列
  cy.intercept('GET', '/api/todos', { fixtures: 'todos.json' })  // fixture に s
})

cypress/e2e/typo.cy.ts(3,19): error TS2322: Type 'string' is not assignable to type 'number'.

should の1つ目は任意の文字列を受け取る型で、cy.intercept の3つ目の引数の型（RouteHandler）は object も受け取るので、どちらも型では止まりません。fixture の綴りと should の書き方は、テストがわざと失敗するか（期待を逆にして赤くなるか）で一度確かめます。

フィクスチャのキャッシュ

公式の説明では、cy.fixture() は最初に読んだ中身をキャッシュし、同じパスで呼ぶと、ディスクのファイルを書き換えていてもキャッシュの中身が返ります。返る値はコピーなので、受け取ったオブジェクトを書き換えても次の cy.fixture() には影響しません。一部だけ変えて返すときは、読んでから書き換えます。

cy.fixture('todos.json').then((todos) => {
  todos[0].done = true
  cy.intercept('GET', '/api/todos', todos)
})

API のモックをブラウザとテスト全体で共有する方法は、関連記事「MSWの使い方｜v3対応のハンドラ一覧とVitest・ブラウザ設定」で扱っています。

ログインの共通化と環境変数（cy.session・cy.env・Cypress.expose）

この節では、毎回のログインを短くする方法と、パスワードなどの値の渡し方が分かります。

cy.session とカスタムコマンド

公式は、ログインは画面の操作ではなく cy.request() などで行い、cy.session() で保存して使い回すことを勧めています。cy.session() は、最初の1回だけ setup を動かし、Cookie・localStorage・sessionStorage を保存して、2回目からは復元します。

// cypress/support/commands.ts
declare global {
  namespace Cypress {
    interface Chainable {
      login(email: string): Chainable<void>
    }
  }
}

Cypress.Commands.add('login', (email: string) => {
  cy.session(email, () => {
    cy.env(['password']).then(({ password }) => {
      cy.request({
        method: 'POST',
        url: '/api/login',
        body: { email, password },
        log: false,
      })
    })
  }, {
    validate() {
      cy.request('/api/me').its('status').should('eq', 200)
    },
  })
})

export {}

// cypress/support/e2e.ts
import './commands'

spec では beforeEach(() => { cy.login('a@example.com') }) と書きます。validate は、復元したログインがまだ有効かを確かめる処理で、失敗すると setup からやり直されます。このコマンドの型宣言も、型チェックでエラー0件でした。

cy.env と Cypress.expose の使い分け（16 から）

// cypress.config.ts
export default defineConfig({
  expose: { appEnv: 'local' },   // Cypress.expose('appEnv') で読む
})

# パスワードは OS の環境変数で渡す（cy.env(['password']) で読める）
CYPRESS_password='********' npx cypress run

公式の説明では、cy.env() はコマンドのログにキーの名前だけを出し、値は出しません。ただし受け取った値を should で確かめたり、log: false を付けずに type() に渡したりすると、値がログに出ることがあります。--env で渡した値は CI のログに残ることがある、とも書かれています。

コンポーネントテストの書き方（React）

この節では、部品1つをブラウザに表示して確かめる書き方と、対応しているフレームワークが分かります。

対応するフレームワーク（2026年10月23日時点の公式の表）

フレームワーク	UI ライブラリ	バンドラー
React（Vite・Webpack）	React 18・19	Vite 8・Webpack 5
Next.js 15・16	React 18・19	Webpack 5
Vue（Vite・Webpack）	Vue 3	Vite 8・Webpack 5
Angular	Angular 21・22	Webpack 5
Svelte（Alpha）	Svelte 5	Vite 8・Webpack 5

16.0.0 で、Vite 5〜7、Next.js 14、Angular 18〜20 は対象から外れました。

設定と spec

// cypress.config.ts に足す
component: {
  devServer: {
    framework: 'react',
    bundler: 'vite',
  },
},

// src/Counter.tsx
import { useState } from 'react'

export function Counter({ initial = 0, onChange }: { initial?: number; onChange?: (n: number) => void }) {
  const [count, setCount] = useState(initial)
  return (
    <>
      <span data-cy="count">{count}</span>
      <button onClick={() => { setCount(count + 1); onChange?.(count + 1) }}>増やす</button>
    </>
  )
}

// cypress/component/Counter.cy.tsx
import { mount } from 'cypress/react'
import { Counter } from '../../src/Counter'

describe('<Counter />', () => {
  it('ボタンで1増え、onChange が呼ばれる', () => {
    const onChange = cy.spy().as('onChange')
    mount(<Counter initial={5} onChange={onChange} />)
    cy.get('[data-cy=count]').should('have.text', '5')
    cy.contains('button', '増やす').click()
    cy.get('[data-cy=count]').should('have.text', '6')
    cy.get('@onChange').should('have.been.calledWith', 6)
  })
})

cy.spy() で作った関数を props に渡すと、呼ばれた回数と引数を should('have.been.calledWith', 6) で確かめられます。spy・stub の違いは、関連記事「テストダブルとは｜スタブ・モック・スパイ・フェイクの違いと使い分け」で扱っています。公式の手順では、cypress open で Component Testing を選ぶと、support の component ファイルに cy.mount のコマンドが作られ、spec で cy.mount(...) と書けるようになります。

npx cypress open --component   # 画面で選んで動かす
npx cypress run --component    # まとめて動かす

cypress runとCI（GitHub Actions・終了コード）

この節では、画面なしでまとめて動かす方法、CI の設定、失敗の数が終了コードになる決まりが分かります。

cypress open と cypress run

比べること	cypress open	cypress run
使う場面	テストを書く・直す	CI・まとめて流す
ブラウザ	画面に出る	既定は画面なし（headless）
結果	画面で1コマンドずつ戻って見られる	端末に表示・スクリーンショット
終了コード	―	失敗したテストの数

cypress run のよく使うオプション（16.2.0 の --help から）

オプション	意味
-b, --browser chrome	ブラウザを選ぶ。パスも渡せる
-s, --spec "cypress/e2e/todo.cy.ts"	流す spec を絞る（glob も可）
--e2e・--component	テストの種類を選ぶ
-c, --config baseUrl=http://localhost:3000	設定を上書きする
-e, --env・-x, --expose	cy.env・Cypress.expose の値を渡す
--headed	ブラウザを画面に出す
--record --key <キー>	Cypress Cloud に記録する
--parallel	Cloud の振り分けで複数台で流す
--posix-exit-codes	失敗を 1、成功を 0 で返す
--pass-with-no-tests	spec が無くても成功にする

公式の Command Line のページでは、既定の終了コードは失敗したテストの数です。--posix-exit-codes を付けると、失敗は 1、Cloud への接続の失敗は 112 になります。

ブラウザを指定する（Electron は非推奨）

16.0.0 で、テスト用のブラウザとしての Electron が非推奨になりました。それでも、--browser も設定の defaultBrowser も無いときは、同梱の Electron が使われます。CI では --browser chrome か defaultBrowser を書いておきます。 対応ブラウザは Chrome（Beta・Canary・Chrome for Testing・Chromium も）、Edge、Firefox で、WebKit は試験的な対応です。

GitHub Actions の設定

公式の cypress-io/github-action（v7）を使う形です。start でアプリを起動し、wait-on で URL が応答するまで待ってからテストを流します。

# .github/workflows/e2e.yml
name: E2E
on: [push, pull_request]
jobs:
  cypress-run:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Cypress run
        uses: cypress-io/github-action@v7
        with:
          build: npm run build
          start: npm start
          wait-on: 'http://localhost:3000'
          browser: chrome
        env:
          CYPRESS_password: ${{ secrets.E2E_PASSWORD }}
      - name: Upload screenshots
        if: failure()
        uses: actions/upload-artifact@v7
        with:
          name: cypress-screenshots
          path: cypress/screenshots
          if-no-files-found: ignore

• このアクションは依存のインストール（キャッシュ付き）も行います。wait-on-timeout の既定は 60 秒です。
• README では、アクションの env の入力は 15.10.0 より前の Cypress 向けとされ、値は手順の env に CYPRESS_ を付けて渡す方法も示されています。上の例は cy.env(['password']) で読む形です。
• 失敗したときの画面は cypress/screenshots に保存されるので、if: failure() でアーティファクトに残します。

GitHub Actions の基本は、関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」で扱っています。

不安定なテストを再実行する（retries）

設定の retries は、既定で cypress run も cypress open も 0 回です。CI だけ再実行するなら次のように書きます。

export default defineConfig({
  retries: { runMode: 2, openMode: 0 },
})

再実行で通るテストは、待ち方やデータの準備に原因が残っていることが多くあります。原因の探し方は、関連記事「フレーキーテストの原因と対策｜不安定なテストの見つけ方と直し方」で扱っています。

Cypress Cloudの料金

この節では、Cypress Cloud のプランと、何に数えられて料金が決まるかが分かります。

2026年10月23日時点の公式の料金ページの内容です（年払いの金額。月額の表示は年額を12で割ったもの）。

プラン	料金	テスト結果の数	人数
Starter（無料）	0ドル	月500件	10人
Team	年799ドル（月あたり67ドル〜）	年12万件	50人
Business	年3,199ドル（月あたり267ドル〜）	年12万件	50人
Enterprise	個別見積もり	年180万件	上限なし

• テスト結果は、記録した it() 1回の実行で1件と数えられます。--record で Cloud に送ったものだけが数えられ、再実行したテストは1件です。
• 並列実行の振り分けと Test Replay（実行の記録を後から見る機能）は全プランに含まれます。不安定なテストの検出・分析は Team 以上、自動の打ち切りや spec の優先順位付けは Business 以上です。
• 記録が残る期間は、Starter が30日、Team と Business が90日、Enterprise が180日です。
• cy.prompt（自然文で書いた手順を Cypress のコマンドにする機能）の実行回数もプランごとに決まっていて、Starter は月100回です。

Cloud を使わなくても、cypress run で CI に並べて流し、結果は終了コードとスクリーンショットで見る使い方ができます。

Cypress 15から16への変更点（Cypress.env・cy.execの削除）

この節では、以前の書き方が 16 でどうなるかと、直し方が分かります。

以前の書き方の spec を 16.2.0 の型定義で型チェックすると、3つともエラーになりました。

it('15 以前の書き方', () => {
  const password = Cypress.env('password')
  cy.exec('npm run db:reset')
  cy.get('[data-cy=email]').type('a@example.com').end()
})

cypress/e2e/old.cy.ts(2,28): error TS2339: Property 'env' does not exist on type 'Cypress & CyEventEmitter'.
cypress/e2e/old.cy.ts(3,6): error TS2339: Property 'exec' does not exist on type 'cy & CyEventEmitter'.
cypress/e2e/old.cy.ts(4,51): error TS2339: Property 'end' does not exist on type 'Chainable<JQuery<HTMLElement>>'.

以前	16 での書き方	変わった版
Cypress.env('password')	cy.env(['password'])（秘密）・Cypress.expose()（公開）	16.0.0 で削除
cy.exec('npm run db:reset')	cy.task() で Node.js 側の処理を呼ぶ	16.0.0 で削除
.end()	新しい cy. から書き始める	16.0.0 で削除
type() の1文字ごとの待ち 10ms	既定は 0ms（keystrokeDelay）	16.0.0
Node.js 20	Node.js 22・24・26 以降	16.0.0
Chrome の通信は Cypress を経由	Chrome・Edge はブラウザの通信の仕組みで見張る	16.0.0
cypress.json・cypress/integration	cypress.config.js・cypress/e2e	10.0.0

cy.exec() の代わりの cy.task() の例です。コマンドの実行は Node.js 側（設定ファイル）に書きます。

// cypress.config.ts
import { execSync } from 'node:child_process'

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on('task', {
        resetDb() {
          execSync('npm run db:reset', { stdio: 'inherit' })
          return null
        },
      })
    },
  },
})

// spec
cy.task('resetDb')

cy.task は値を返す必要があり、何も返さないときは null を返します。ほかに 16.0.0 では、experimentalMemoryManagement が manageBrowserMemory（既定 true）に、experimentalFastVisibility が visibilityStrategy（既定 'modern'）に変わりました。Firefox・WebKit・Electron は、以前と同じ Cypress を経由する通信の仕組みのままです。

CypressとPlaywright・Seleniumの違い

この節では、3つのツールの違いを事実で比べ、どれが合うかの判断の材料が分かります。

比べること	Cypress 16	Playwright 1.64	Selenium 4
テストが動く場所	ブラウザの中（アプリと一緒）	ブラウザの外から操作	ブラウザの外から WebDriver で操作
書ける言語	JavaScript・TypeScript	JS・TS・Python・Java・.NET	Java・Python・C#・Ruby・JS・Kotlin
ブラウザ	Chrome系・Edge・Firefox・WebKit（試験的）	Chromium・Firefox・WebKit	各ブラウザのドライバー
並列実行	Cloud で複数台に振り分け	既定で並列（workers）	Selenium Grid
複数タブ	@cypress/puppeteer プラグインで	標準で扱える	標準で扱える
ライセンス	MIT	Apache-2.0	Apache-2.0

• Cypress の公式の Trade-offs には、Cypress はブラウザの中でコマンドを動かすこと、2つのブラウザを同時に動かせないこと、1つのテストは1つのドメイン（別のドメインは cy.origin で）に結びつくことが、設計上の決まりとして書かれています。
• Playwright の公式の Getting started には、テストは既定で Chromium・Firefox・WebKit に対して、画面なしで並列に流れると書かれています。
• Selenium は WebDriver を中心に、記録して再生する IDE と、複数台で流す Grid からなるプロジェクトです。
• ライセンスと版は、npm の cypress 16.2.0（MIT）、@playwright/test 1.64.1（Apache-2.0）、selenium-webdriver 4.51.0（Apache-2.0）で確かめました。

こういうとき	合いやすいもの
フロントエンドを JS・TS で書いていて、画面で1コマンドずつ戻って見たい	Cypress
部品のテストと E2E を同じツールでそろえたい	Cypress
Safari（WebKit）や複数タブ・複数ブラウザを1つのテストで扱いたい	Playwright
Python・Java など JS 以外でテストを書きたい	Playwright・Selenium
実機やさまざまなブラウザを Grid で並べたい	Selenium

Playwright の書き方と CI での実行は関連記事「Playwright入門｜E2Eテストの書き方とCI実行まで実行結果つきで解説」、Selenium は関連記事「Selenium Pythonの使い方｜要素取得の全パターンと待機処理」で扱っています。

Cypressのよくあるエラーと直し方

この節では、よく出るエラーの原文から、原因と直し方を探せます。

まず確かめること

• 1本体（バイナリ）が入っているかnpx cypress --version で binary version が not installed なら入っていない
• 2アプリが起動していて baseUrl と合っているかCI では start と wait-on で起動を待つ
• 3セレクターがブラウザで当たるかDevTools の Console で document.querySelectorAll を試す
• 4操作の後ろにコマンドをつなげていないかclick の後は新しい cy.get から書く
• 516 で消えた API を使っていないかCypress.env・cy.exec・end は型チェックで見つかる

エラーの原文と直し方

エラーの原文（先頭）	原因	直し方
Timed out retrying after 4000ms: Expected to find element: ...	4秒探しても見つからない	セレクター・表示の条件・timeout
failed because the page updated as a result of this command	操作の後に描き直された要素につなげた	別名を付けて新しい cy.get から
failed because this element: ... is being covered by another element	モーダルなどが上に重なる	重なりを閉じる。force は最後の手段
failed because this element is not visible	非表示・大きさ0	表示する操作を先に行う
failed because this element is `disabled`	ボタンが無効	有効になる条件を満たす
cy.type() failed because it requires a valid typeable element.	入力できない要素に type	input・textarea を指す
cy.wait() timed out waiting 5000ms for the 1st request to the route: addTodo. No request ever occurred.	通信が起きない・intercept の URL やメソッドが合わない	intercept を visit・操作の前に書く
cy.visit() failed trying to load:	アプリが起動していない・URL 違い	起動と baseUrl を確かめる
The following error originated from your application code, not from Cypress.	アプリで例外が出た	アプリを直す。無視は条件付きで
No version of Cypress is installed in: ...	本体が入っていない	cypress install（npm 12 は許可）

エラーの文言は、GitHub の cypress-io/cypress のソース（error_messages.ts・chai.ts）の文で確かめました。... の部分には、セレクターや要素が入ります。

Timed out retrying（要素が見つからない）

ソースでは「Timed out retrying after {ms}ms: 」に「Expected to find element: {セレクター}, but never found it.」が続きます。

• ブラウザの DevTools の Console で document.querySelectorAll('[data-cy=submit]') を試し、要素があるか、data-cy の綴りが合うかを確かめます。
• 画面に見えているのに見つからない場合について、公式は、HTML の書き間違い（閉じタグの漏れなど）があると、その後ろの要素を querySelector で探せないことがある、と説明しています。
• データの読み込みが遅いだけなら、その cy.get に { timeout: 10000 } を付けます。

detached from the DOM（the page updated）

12 以降のメッセージは次の形です（ソースの文言）。

cy.click() failed because the page updated as a result of this command, but you tried to continue the command chain. The subject is no longer attached to the DOM, and Cypress cannot requery the page after commands such as cy.click().

メッセージの中で、cy.get('button').click().should('have.class', 'active') を、cy.get('button').as('btn').click() と cy.get('@btn').should('have.class', 'active') の2行に分ける直し方が示されています。React などが要素を描き直すと、つなげた先の要素はもう画面に無いので、別名から探し直させます。

アプリの例外でテストが落ちる

アプリが捕まえていない例外（unhandledrejection も含む）を出すと、Cypress はテストを失敗にします。直すのはアプリ側が先です。外部のスクリプトなど、テストと関係の無い例外だけを無視するときは、uncaught:exception のイベントで条件を付けて false を返します。

// cypress/support/e2e.ts
Cypress.on('uncaught:exception', (err) => {
  if (err.message.includes('ResizeObserver loop')) {
    return false // この例外だけテストを失敗にしない
  }
})

No version of Cypress is installed（本体が無い）

npm パッケージだけがあり、本体が無いときに npx cypress verify を流した出力です（ホームのパスは ~ に置き換えています）。終了コードは 1 でした。

No version of Cypress is installed in: ~/.cache/Cypress/16.2.0/Cypress

Please reinstall Cypress by running: cypress install

----------

Cypress executable not found at: ~/.cache/Cypress/16.2.0/Cypress/Cypress

----------

Platform: linux-x64 (Ubuntu - 24.04.4 LTS)
Cypress Version: 16.2.0

起きる場面	直し方
npm 12 で入れた	npm install-scripts approve cypress と npm rebuild cypress
CI で node_modules だけキャッシュした	~/.cache/Cypress もキャッシュするか、npx cypress install
CYPRESS_INSTALL_BINARY=0 が残っている	環境変数を外して npx cypress install
社内のプロキシ・ネットワークで止まる	https_proxy を設定するか CYPRESS_DOWNLOAD_MIRROR

ダウンロードで失敗したときは、ソースに「The Cypress App could not be downloaded.」という文言があります。公式は、DEBUG=cypress:cli* npx cypress install で詳しいログを出して原因を見る方法を案内しています。

よくある質問

Q. Cypressの読み方は？ A. サイプレスです。英語の cypress は、木の糸杉のことです。

Q. Cypressは無料ですか？ A. テストを書いて動かす Cypress App は無料で、MIT ライセンスです。結果の記録や並列実行の振り分けを行う Cypress Cloud には、無料の Starter（月500件）と有料のプランがあります。

Q. CypressのテストはPythonやJavaで書けますか？ A. 書けません。テストは JavaScript か TypeScript で書きます。Python・Java で書くなら Playwright か Selenium が対象になります。

Q. cypress.jsonが見つかりません。 A. 10.0.0 から設定ファイルは cypress.config.js（TypeScript なら cypress.config.ts。.mjs・.cjs も可）になり、spec の場所も cypress/integration から cypress/e2e に変わりました。

Q. Cypress.env is not a function・Cypress.envが使えないのはなぜ？ A. 16.0.0 で Cypress.env() が削除されたためです。パスワードなどは cy.env(['キー'])、公開してよい値は Cypress.expose('キー') で読みます。

Q. cy.waitで何秒待てばいいですか？ A. 秒数で待たず、should で条件を書くか、cy.intercept に別名を付けて cy.wait('@別名') で通信を待ちます。クエリと should は既定で最大4秒、自動で探し直します。

Q. ヘッドレスで動かすには？ A. npx cypress run は既定で画面なし（headless）です。ブラウザを画面に出すなら --headed を付けます。

Q. SafariやiPhoneでテストできますか？ A. Safari のエンジンの WebKit には試験的に対応しています（experimentalWebKitSupport: true と playwright-webkit を入れる）。公式の Trade-offs には、ネイティブやモバイルのイベントには対応していないと書かれています。

Q. 新しいタブで開くリンクはテストできますか？ A. Cypress は1つのブラウザを操作する作りで、公式は複数のタブを試すなら @cypress/puppeteer プラグインを使う方法を案内しています。リンク先の URL を確かめるだけなら、should('have.attr', 'href', '/help') で足りる場面もあります。

Q. CypressとPlaywrightはどちらを選べばいいですか？ A. JS・TS のフロントエンドで、コンポーネントテストもそろえたいなら Cypress、WebKit・複数タブ・JS 以外の言語が要るなら Playwright が合います。違いは「Playwright・Seleniumの違い」の表にまとめました。

まとめ

• Cypress はブラウザの中でアプリを操作して確かめる、JS・TS の E2E とコンポーネントテストのツール。App は無料（MIT）、Cloud は無料枠と有料プランがある。最新は 16.2.0。
• npm install cypress --save-dev で入り、本体はインストールスクリプトがダウンロードする。npm 12 では npm install-scripts approve cypress で許可が要る。
• クエリと should は最大4秒探し直す。cy.wait(数値) ではなく、条件か cy.wait('@alias') で待つ。操作の後ろにはつなげない。
• セレクターは data-cy がいちばん壊れにくい。16.2.0 から cy.getByRole() も使える。
• API は cy.intercept とフィクスチャで差し替える。fixture の綴り違いは型チェックで止まらない。
• 16.0.0 で Cypress.env()・cy.exec()・.end() が消えた。cy.env()・Cypress.expose()・cy.task() に直す。
• CI は cypress-io/github-action の v7 で、--browser chrome を指定する。終了コードは失敗したテストの数。

参考・出典

確認日はいずれも 2026年10月23日です。

• Cypress「Install Cypress」：https://docs.cypress.io/app/get-started/install-cypress
• Cypress「Advanced Installation」：https://docs.cypress.io/app/references/advanced-installation
• Cypress「Writing Your First End-to-End Test」：https://docs.cypress.io/app/end-to-end-testing/writing-your-first-end-to-end-test
• Cypress「Retry-ability」：https://docs.cypress.io/app/core-concepts/retry-ability
• Cypress「Best Practices」：https://docs.cypress.io/app/core-concepts/best-practices
• Cypress「intercept」：https://docs.cypress.io/api/commands/intercept
• Cypress「fixture」：https://docs.cypress.io/api/commands/fixture
• Cypress「session」：https://docs.cypress.io/api/commands/session
• Cypress「getByRole」：https://docs.cypress.io/api/commands/getbyrole
• Cypress「env」：https://docs.cypress.io/api/commands/env
• Cypress「Cypress.expose」：https://docs.cypress.io/api/cypress-api/expose
• Cypress「Configuration」：https://docs.cypress.io/app/references/configuration
• Cypress「Command Line」：https://docs.cypress.io/app/references/command-line
• Cypress「Launching Browsers」：https://docs.cypress.io/app/references/launching-browsers
• Cypress「Component Testing」：https://docs.cypress.io/app/component-testing/get-started
• Cypress「Error Messages」：https://docs.cypress.io/app/references/error-messages
• Cypress「Trade-offs」：https://docs.cypress.io/app/references/trade-offs
• Cypress「Changelog」：https://docs.cypress.io/app/references/changelog
• Cypress「Pricing」：https://www.cypress.io/pricing
• GitHub「cypress-io/github-action」：https://github.com/cypress-io/github-action
• GitHub「cypress-io/cypress」：https://github.com/cypress-io/cypress
• GitHub「npm/cli Release v12.0.0」：https://github.com/npm/cli/releases/tag/v12.0.0
• Playwright「Installation」：https://playwright.dev/docs/intro
• Selenium「Documentation」：https://www.selenium.dev/documentation/

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。