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

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

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

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

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

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

目次

  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

はじめに設定ファイルを置く

探し始めるポートは _secrets/test-server.json から読む。無ければ立たない (終了コード 2)。

{
    "firstPort": 8000
}

番号はここには書かない。上は形を示すための値である。このリポジトリは公開しているので、他プロジェクトへ案内していない値を公開する側に置かない。実際の番号は置いてあるファイルを見ること。

本番のポートとは離れた番号にする。字面が近いと、打ち間違いがそのまま本番に飛ぶ。

先頭 _ のフォルダなので Git 管理外になる。環境を移したら作り直す。

個別に立てる・止める

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

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

テスト用サーバーを立てました。
  ポート  <テスト用のポート>
  置き場  .\tmp\_data
  環境    test
  pid     12345
  画面    http://localhost:<テスト用のポート>/?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 --test

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

置き場を書き忘れると断られる。--test か --production のどちらかが要る (exit 2 で止まる)。既定は無い。どちらを相手にするかを毎回書かせることで、本番を消す操作が黙って通らないようにしている。

ダブルクリックで起動したときも同じで、引数が無いので断られる。引数を渡して呼ぶ。

困ったとき

ポートが空かない

設定した番号から 10 個下げても空きが無いと止まる。前のテストサーバーが残っていることが多い。エラーには実際の番号が出る。

Get-NetTCPConnection -LocalPort <テスト用のポート> -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 --test を手で叩く。止めれば置き場ごと消えるので、ふだんは気にしなくてよい。

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

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

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