古い管理画面が、ルールと自動検査のレールを通ってモダンな画面に生まれ変わる概念イラスト

2年目サーバーエンジニアがPHP製の社内管理画面をほぼ全自動でReactにリプレイスした

はじめに こんにちは。and factory でサーバーエンジニアをしている松ヶ浦です。 弊社では、自社アプリの広告関連の売上やKPIを管理する社内システムを内製しています。この管理画面はPHP(CodeIgniter 3)で作られていて、いわゆるレガシーな構成のまま運用されていました。PHPのバージョンは2022年11月にサポートが終わった7.4のままで、本来はバックエンドで守るべき権限の制御も画面側のコードで守っているような状態でした。それでも社内専用ということもあって、対応はずっと先送りにされていました。なお、今回のリプレイスでPHPの画面は停止して撤去し、権限の制御もバックエンド側で守るようにしています。 ただ、ここ最近でAIが十分に賢くなり、ハーネスエンジニアリングやソフトウェアファクトリーといった考え方も出てきました。そこで、今ならほぼ全自動でリプレイスできるのではないかと考え、React(Next.js)で作り直すことにしました。 僕はサーバーエンジニアで、フロントエンドを本格的に書いた経験はほとんどありません。そのため、実装はほぼすべてClaude Codeに任せると決めて、進め方の決まりと自動検査の仕組みを「ハーネス」として構築しました。 結果として、予定していた9画面の移植は、実装上のバグを出さずに終えられました。この記事では、作ったハーネスの構成と、実際に運用してみて見えてきた課題を紹介します。 プロジェクトの前提条件と技術スタック 対象は、エンドユーザーが触れない社内専用の管理画面です。売上の集計、KPIのダッシュボード、各種マスタ、管理ユーザーの管理などがあります。ほとんどがシンプルなCRUDで、バックエンドからフロントエンドまで、サーバーエンジニア1〜2名で開発、運用しています。 元のPHP版は、PHP 7.4とCodeIgniter 3.1でサーバー側がHTMLを組み立てる構成で、画面はjQuery、Bootstrap、DataTablesで作られていました。もともとPHPの画面がGoのバックエンドをgRPCで呼ぶ、PHPとGoのハイブリッド構成です。リプレイスに備えて、PHP側にあった集計などの処理はあらかじめGoに移植してありました。そのため、今回はREST APIを使うフロントエンドだけを、次の構成で作り直しています。 用途 採用技術 フレームワーク Next.js 16(App Router)、React 19、TypeScript データ取得 TanStack Query v5 フォーム周り react-hook-form、Zod UIスタイリング Tailwind CSS v4、shadcn/ui APIクライアント orval(OpenAPIからhooks・型・Zodスキーマを自動生成) テスト Vitest、Testing Library、Playwright、MSW CI GitHub Actions 実行環境 Node.js 24、pnpm なぜ「ハーネス」が必要だったのか チームにはフロントエンドの専任者がいないので、AIが生成したコードを人間が1行ずつ読んでレビューするのは難しいと考えました。かといって、チャット感覚でその都度AIに指示を出すと、出来上がりにブレが出そうです。既存のPHP版と挙動が変わったり、UIの崩れに気づけなかったりすることも心配でした。 そこで、人間がやることを次の3つに絞る仕組み(ハーネス)を作りました。 AIへ指示を出す(skillの実行) AIが作った実装計画のレビュー 最終的な画面の確認とマージ コードの実装、テストの追加、画面キャプチャの撮影までは、Claude Codeと自動検査(CI)に任せます。その代わり、任せた部分が勝手に崩れないよう、いくつかルールを決めました。 決めたことは、設計判断(ADR)や仕様書としてリポジトリに残し、口頭やチャットでの合意は仕様として扱いません。品質の合否は、コマンドで再現できる自動検査だけで判断し、手で埋めたチェックリストは根拠にしません。仕様も、実装しながら固めるのではなく、実装を始める前に画面仕様書で決めておきます。 さらに、Claude Code自身にも次のルールを守らせています。 実行していないテストを「合格」と書かない 失敗したテストをskipやリトライで無理やり通さない 承認された実装計画から勝手に外れない CIが落ちたときは専用のサブエージェントが直し、2往復しても直らなければ人間に戻す ハーネスの構成(3つのリポジトリとCI) ここで紹介するのは、運用しながら直したあとの形です。ハーネスは、役割ごとに3つのリポジトリに分けています。 1. リポジトリの役割分担 リポジトリ 役割・置いているもの docs 設計判断(ADR)、画面ごとの仕様、承認済みの実装計画、不変条件 skill Claude Codeを動かすためのskill(計画用skill、実装用skill) フロントエンド アプリケーションのコード、E2Eテスト、CIの定義 docs にある不変条件は、システムとして壊してはいけない性質をまとめたもので、全部で8件あります。たとえば「未ログインでは画面を見られない」「アクセス権のないデータは画面とCSVのどちらにも出さない」「自分自身は削除できず、権限の昇格もできない」といったものです。Claude Codeは、実装計画を立てる前に必ずこれを読み込みます。 ...

2026年11月18日 · 読了時間: 1分 · 松ヶ浦健
ログインを1回実行してstorageStateに保存し、複数のテストで再利用する構成図

ログインは1回だけ — Playwrightの globalSetup × storageState でE2Eテストを高速化する

本記事では、PlaywrightのE2Eテストで globalSetup と storageState を使い、ログイン状態を一度だけ取得して各テストで再利用する仕組みを解説します。 この方式により、ログインが必要なページのテストでも毎回ログイン操作を繰り返さずに済み、テスト全体を高速かつ安定的に実行できます。 この記事で得られること globalSetup+storageStateでログインを1回だけ実行し、全テストで再利用する実装 httpOnly Cookieを含むログイン状態が保存・注入されるしくみ 実際にログインするテストとログイン済み状態から開始するテストの使い分け globalSetup内で成功・失敗それぞれのトレースを記録するデバッグ手法 背景と課題 これまで、ログインが必要な画面のリグレッション確認を、リリースのたびに手動で実施していました。 対象画面が十数件にのぼり、毎回30分以上の確認工数がかかっていたうえ、ログインを伴う操作フローは手動では見落としが起きやすく、リリース後に不具合に気づくケースもありました。 機能追加のペースが上がり、確認対象もさらに増えてきたことをきっかけに、これらの確認をE2Eテストで自動化し、リグレッションを継続的に担保することにしました。 E2Eテストを導入するうえで課題になるのが認証の扱いです。 テストごとにログイン操作を繰り返すと、テスト数に比例して実行時間が増え、さらにログイン処理自体の不安定さがテスト全体の信頼性を下げます。 そこで、ログインを一度だけ実行してセッション情報を保存し、各テストで再利用する仕組みを globalSetup と storageState で構築しました。本記事はその構成と運用方法をまとめたものです。 前提環境 本記事は以下の環境で動作を確認しています。お使いの環境に合わせて読み替えてください。 ツール バージョン Node.js 20.18.0 (LTS) @playwright/test 1.49.1 Nuxt 3.14.0 TypeScript 5.6.3 実行OS macOS 14 / Ubuntu 22.04 (CI) ファイル構成 E2E専用の構成として、関連ファイルは次のように配置します。 1 2 3 4 5 6 7 8 9 10 11 src/ ├── package.json # test:e2e スクリプトを追加 ├── playwright.e2e.config.ts # E2E専用Playwright設定 ├── .env.e2e # 認証情報(gitignore済み・各自作成) ├── playwright/ │ └── .auth/ │ └── user.json # ログイン済みCookie(gitignore対象・テスト実行時に自動生成) └── tests/ └── e2e/ ├── global-setup.ts # ログイン・storageState保存 └── auth.spec.ts # 認証フローのテスト E2E専用の設定ファイルを分ける理由 E2Eテストは実APIを呼び出し、実際にログインしてセッションを取得します。スナップショット比較やユニットテストなど他の種類のテストとは、API・認証・実行タイミングの要件が異なります。 ...

2026年6月3日 · 読了時間: 7分 · 渡邊尚人
frontend testing

QA フェーズを起点に、Next.js のテスト基盤をゼロから設計した話 — Playwright × Vitest × Sentry

QAフェーズへの移行を機に、後回しにしていたテスト基盤を一気に整備した記録です。 同じドメインで連携する3つのNext.jsサイト(利用者向け/提供者向け/社内管理画面)を並行開発し、リリース前のQAに突入したものの、モンキーテストで予想を超えるバグが多発しました。 修正のたびに3サイト全画面を手動で再確認することになり、1サイクルあたり30分〜1時間かかりました。本来テストシナリオ作成に充てるはずだった1週間がバグ修正で埋まりました。 そこでE2Eテスト(Playwright)・コンポーネントテスト(Vitest)・本番エラー監視(Sentry)を 半日で一気に導入 しました。 この記事では、Next.js App Router + TanStack Query + MSW という構成で、ツール選定から実装・CI統合までの過程を解説します。あわせて、SSR / Turbopack固有のハマりポイントと、AIでテストを量産する際の落とし穴も共有します。 この記事で得られること Next.js App Routerで Playwright + MSW を動かすためのSSR対応パターン MSW ハンドラーを E2E と Vitest で共有する設計(モックの二重管理を防ぐ) E2E / Vitest / 手動テストの 仕分け基準(テストピラミッドの設計) Sentryを Next.js 16 + Turbopack で動かす際のハマりポイントと解決策 Sentryの 3層防御マスキング設計(SDKフック / Server-side Scrubber / Generative AI機能停止) ソースマップを Sentry にアップロードしない という運用選択肢とそのトレードオフ AIでテストを量産する際の「成功するテストしか作らない」問題と対策 動作確認環境 種別 バージョン OS macOS 15.x Node.js 24.x パッケージマネージャー pnpm 10.x Next.js 16.x(Turbopack) React 19.x @playwright/test 1.58.x vitest 4.x msw 2.x @sentry/nextjs 10.x @tanstack/react-query 5.x 1. 背景: 手動テストだけでは回らなくなった瞬間 3つのNext.jsサイト(利用者向けサイト/提供者向けサイト/社内管理画面)を約10名のチームで半年かけて並行開発しました。 ...

2026年5月12日 · 読了時間: 12分 · 福士宗介