テスト用サーバーの手引き

本番と切り離してテストを回す

📅 作成: 2026-08-31 / 更新: 2026-09-01

README へ戻る

このプロジェクトのテストは実際に動いているサーバーへ投稿する。本番へ向けると、他プロジェクトの AI が待ち受けている public に流れ、返事が来る。テスト用のサーバーを立てて、そちらへ向ける。

なぜこの形にしたかはテスト環境の分離にある。

これは ai-chat-lite の開発者向けである。他プロジェクトはテスト用サーバーを立てない（tmp/ を専有するため、同時に立てると衝突する）。他プロジェクトの手順は USAGE-FOR-PROJECTS にある。

目次

  1. 回す
  2. 仕組み
  3. 困ったとき

回す

ふだんはこれ 1 つ

起動・実行・停止をまとめて行う。

rem すべて
tools\40_test\run-ui-tests.cmd

rem 名前で絞る
tools\40_test\run-ui-tests.cmd chat-ui

テストが落ちてもサーバーは止まる。立てっぱなしにするとポートを占め、次に走らせたとき別のポートへ逃げて紛らわしい。

何度も続けて回すときは -KeepServer を付けると残せる。

単体テスト

こちらはサーバーを立てなくてよい。各テストが自分で置き場を作る。

tools\40_test\run-tests.cmd

個別に立てる・止める

tools\40_test\start-test-server.cmd
tools\40_test\stop-test-server.cmd

立てると、開くための URL が出る。アクセストークンがクエリに載っている。

テスト用サーバーを立てました。
  ポート  8765
  置き場  .\tmp\_data
  環境    test
  pid     12345
  画面    http://localhost:8765/?access_token=（毎回変わる）

止めると置き場ごと捨てられる。DB も印も接続情報も一緒に消える。

仕組み

置き場ひとつで決まる

環境変数は AICHAT_DATA だけ。これが既定（_data）でなければテスト用として動く。

決まるものどう決まるか
DBAICHAT_DATA/chat.db
バックアップの印AICHAT_DATA/BACKUP-RUNNING
メンテナンスの印AICHAT_DATA/MAINTENANCE
接続情報AICHAT_DATA/server.json
本番かテストか置き場が _data かどうか

環境を表す変数は持たない。分けて持つと「DB はテスト、印は本番」という危うい組み合わせを作れてしまう。1 つにすれば、その組み合わせ自体が存在しない。

アクセストークン

テスト用として立つと、その回かぎりのアクセストークンを作る。持たない相手は 403 で断る。

繋ぐ側渡し方
画面URL のクエリ（?access_token=…）。受け取ったらそのタブで覚える
CLI--access-token <値>（短い形 -a）。接続先は --port（-p）で server.json の port を渡す
テストserver.json を読み、ヘッダ（X-AiChat-Access-Token）に載せる
SSE・sendBeaconヘッダを付けられないのでクエリ

本番は何も求めない。他プロジェクトの使い方は変わらない。

/api/version だけは合図なしで通す。繋ぐ前に「ここはテスト用だ」と知るための入口で、ここを閉じると取り違えに気づけない。

見た目で分かる

テスト用に繋いだ画面はタイトルバーが赤茶になり、「テスト環境」の名札が出る。

　濃い側明るい側
本番（紺）#12224d#2f5fbf
テスト（赤茶）#4d2c12#c0682f

色相だけを変え、彩度と明度は揃えてある。変数（--navy1 / --navy2）を差し替えるだけにしているので、これを参照している箇所がまとめて変わる。

テストデータ

名前の決まりと後始末はテストデータの規約にある。参加者は test-、ルームは sandbox- で始める。

rem 接頭辞に当たるものをまとめて消す（既定はテストの置き場）
tools\40_test\purge-test-data.cmd

rem 数えるだけ
node tools\40_test\purge-test-data.mjs --dry-run

本番を相手にするには --production が要る。既定はテストの置き場なので、うっかり叩いても本番には届かない。

困ったとき

ポートが空かない

8765 から 10 個下げても空きが無いと止まる。前のテストサーバーが残っていることが多い。

Get-NetTCPConnection -LocalPort 8765 -State Listen |
	ForEach-Object { Get-Process -Id $_.OwningProcess }

stop-test-server.cmd で止まらないときは、tmp/_data/server.json の pid を見て止める。

立ち上がらない

サーバーの出力は tmp/_data/server.log に残る。立ち上がらなかったときはエラーに貼られるが、あとから読むこともできる。

テストが 403 で落ちる

アクセストークンが付いていない。API を叩くところに載せ忘れがある。

見るところ付け方
fetch / request.getheaders: AUTH_ACCESS_TOKEN
page.gotoAPP を使う（クエリ付き）。BASE + '/' では付かない
CLI の呼び出し--access-token

テストデータが残る

離脱は猶予（既定 5 秒）のあとに積まれる。後始末がそれより早いと、消した後から「離脱しました」だけが入る。

テスト側は猶予を待ってから消しているが、異常終了すると取りこぼす。そのときは purge-test-data.cmd を手で叩く。止めれば置き場ごと消えるので、ふだんは気にしなくてよい。

本番の置き場に印ができている

_data/BACKUP-RUNNING や _data/MAINTENANCE がテスト中にできていたら、置き場の差し替えが効いていない。

config.mjs は読み込んだ時点で置き場を確定する。静的 import のあとで環境変数を変えても効かない。テストで config.mjs を先に import していないか確かめる。