| name | e2e-tests |
| description | Run / debug Bookwall の Playwright e2e テスト。dev 環境ではなく test 環境を立ててブラウザ経由で動作検証する手順。 |
| allowed-tools | Bash(npx:*) Bash(npm:*) Bash(bundle:*) Bash(playwright-cli:*) Bash(curl:*) |
Bookwall e2e テストの実行フロー
UI / API レベルの動作検証は dev 環境ではなく e2e 専用の test_e2e 環境 で実施する。
dev は普段の手作業用、 e2e は隔離 DB + reset エンドポイント付きで毎テスト前にクリーンになる。
test_e2e は test を母体にした専用 environment で、DB は storage/test_e2e.sqlite3、
Active Storage は tmp/storage_e2e を参照する。これにより rspec が使う test
(storage/test.sqlite3 / tmp/storage) と永続データが完全に分離され、e2e の残骸が
rspec を汚すことがない (rspec は常に RAILS_ENV=test)。
構成
| プロセス | ポート | 役割 |
|---|
| Rails (Falcon) | 3001 | RAILS_ENV=test_e2e + BOOKWALL_E2E_RESET=1 起動 |
| Vite | 5174 | BOOKWALL_API_TARGET=http://127.0.0.1:3001 で proxy |
両者は client/playwright.config.ts の webServer 設定で npx playwright test 実行時に自動起動 する。手動で立てる必要は基本ない (reuseExistingServer: !CI なので既に立っていれば再利用)。
bind は 127.0.0.1 — localhost を ::1 だけにマップしている環境を踏まないため。
重要な前提
- 個別テストは
tests/e2e/helpers/test-base.ts の resetDb fixture で毎テスト最初に POST /api/test_support/reset を投げる。これはルートが BOOKWALL_E2E_RESET=1 の時にだけマウントされるエンドポイント (server/app/controllers/api/test_support_controller.rb)
- 既存 user / session / library / book / Active Storage attachment / blob / variant_record / 等を全削除する。 ActiveStorage は VariantRecord → Blob の順で消す必要があるので、新規にテーブルを足したら reset 順序にも追加すること
よく使うコマンド
すべて client/ ディレクトリで実行 (cwd を間違えない)。
cd client
npm run test:e2e
npx playwright test --project=desktop-chromium
npx playwright test tests/e2e/smoke.spec.ts
npm run test:e2e:ui
npx playwright show-trace test-results/<name>/trace.zip
npx playwright show-report
初回 / 壊れた時の test_e2e DB セットアップ
playwright が自動で bin/rails db:prepare を呼ぶので普段は不要。手動で立て直すときは:
cd server
RAILS_ENV=test_e2e bundle exec rails db:prepare
DB がスキーマ不整合で起動できない時:
cd server
RAILS_ENV=test_e2e bundle exec rails db:drop db:prepare
スキャナや model レベルの動作確認 (Playwright を使わず rails runner で完結)
UI を立ち上げる前にロジックだけ確認したい場合は rails runner で RAILS_ENV=test_e2e を指定する:
cd server
RAILS_ENV=test_e2e BOOKWALL_E2E_RESET=1 bundle exec rails runner '
library = Library.create!(name: "Smoke", path: Rails.root.join("spec/fixtures/files").to_s)
log = Scanners::LibraryScanner.new(library).call
puts({status: log.status, books: library.books.count}.inspect)
'
ポイント:
BOOKWALL_E2E_RESET=1 を付けておく — /api/test_support/reset が必要な後続テストでルートマウントが効くようにするため (起動した rails runner 自体には不要だが、playwright が後で立てる server で必要)- runner 実行後に
Library.delete_all などで掃除しないと、その後 playwright が走ったときに test_support#reset が壊れたデータで FK 違反する場合がある。怪しい時は次節の手動 reset を使う
残骸を強制的に掃除する
test_support#reset がエラーを返す / playwright の最初のテストが reset failed: HTTP 500 で死ぬ時:
cd server
RAILS_ENV=test_e2e bundle exec rails runner '
ActiveRecord::Base.connection.execute("PRAGMA foreign_keys = OFF")
ActiveStorage::Attachment.delete_all
ActiveStorage::VariantRecord.delete_all
ActiveStorage::Blob.delete_all
Library.delete_all
Book.delete_all
ActiveRecord::Base.connection.execute("PRAGMA foreign_keys = ON")
puts "cleaned"
'
または RAILS_ENV=test_e2e bundle exec rails db:drop db:prepare で完全リセット。
test fixture
書籍メタやリーダーの実 file が必要なテストでは server/spec/fixtures/files/ を library のパスとして使える:
| ファイル | 用途 |
|---|
sample.cbz | CBZ scanner |
sample.epub | EPUB scanner |
sample_vertical_jp.epub | 縦書き writing-mode |
sample.pdf | PDF scanner |
sample_image_dir/ | image_dir scanner |
デバッグ
BOOKWALL_E2E_RESET が未設定 → reset failed: HTTP 404 を踏む。 playwright.config.ts の webServer command に必ず付けるlocalhost vs 127.0.0.1 を混ぜると Node の health check が失敗する。 config の RAILS_HOST / VITE_HOST がどちらも 127.0.0.1 固定なのを変えない- 失敗テストの DOM は
test-results/<test-id>/error-context.md に snapshot がある
webServer: reuseExistingServer: !CI なので、開発中に手動で RAILS_ENV=test_e2e bin/rails s -p 3001 を起動しておくと playwright がそれを使う
ローカルで playwright-cli 単発操作したい時
playwright-cli open http://127.0.0.1:5174/ui/ で繋げば dev 環境ではなく test 環境のフロント に対して手で触れる。 e2e test 環境の状態はテスト毎リセットされるが、 playwright-cli はリセットしないので、状態を作りたければ playwright-cli の前に手動で curl の POST /api/test_support/reset してから signup → 操作、という流れになる。
