テストを書く
cybertrain new が test/test_helper.rb を書き出します。Rails と同じく、どのテストファイルも最初にこれを読み込みます:
ENV["CYBERTRAIN_ENV"] ||= "test"
require_relative "../config/app"
require "cybertrain/test_help"
class ActiveSupport::TestCase
fixtures :all
# すべてのテストで使うヘルパーメソッドはここに書く。
end
require "test_helper"
class ArticleTest < ActiveSupport::TestCase
test "title must be present" do
article = Article.new(body: "a body long enough to pass length")
assert_not article.save
assert_includes article.errors.full_messages, "Title can't be blank"
end
end
require "test_helper"
class ArticlesControllerTest < ActionDispatch::IntegrationTest
setup do
@article = articles(:one)
end
test "shows an article" do
get article_path(@article)
assert_response :success
assert_select "h1", text: @article.title
end
test "creates an article" do
assert_difference -> { Article.count }, 1 do
post articles_path, params: { article: { title: "New", body: "A body long enough" } }
end
assert_redirected_to article_path(Article.last)
end
end
基底クラスは Rails と同じ 3 つです:ActiveSupport::TestCase(モデル、ジョブ、メーラーなど、リクエストを伴わないもの)、ActionDispatch::IntegrationTest(リクエスト。統合テスト)、ViewComponent::TestCase(render_inline。ストリームとコンポーネントのテスト)。アプリケーションは自分の基底クラスを test/test_helper.rb か test/support/ に置き、それを継承できます。ヘルパーメソッド、定数、private は Rails と同じくクラス本体に書きます。各テストは新しいインスタンスの上で動くので、setup で設定したインスタンス変数はそのテストのものです。fixtures :all と require "test_helper" は受け付けられますが、それ自体は何もしません:フィクスチャはどのテストにもすべて読み込まれます。
各テストは次の順序で動きます:
- すべてのテーブルが空になり(ジョブ、キャッシュ、Turbo のメッセージ、スケジュール、フィード、リースといったフレームワークのテーブルも含む)、id は 1 から振り直されます。
- フィクスチャが挿入されます(フィクスチャ)。
Mailer.deliveries、レート制限のカウンター、I18n.localeがリセットされ、タイムゾーンはconfig/app.rbで設定したものに戻ります。setup(スーパークラスのものが先。複数のsetup doブロックは順番に)。- テストの本体。それまでに何も失敗していなければ。
teardown。必ず実行されます:アサーションの失敗、例外、setup の失敗のあとでも(複数のteardown doブロックは逆順に、そのあとスーパークラスのもの)。- 時計が実時間に戻り、テストが起動した受信者はすべて止められます。
Rails は代わりに各テストをトランザクションでロールバックします。ここではそれが合いません:このフレームワークの SQLite にはセーブポイントがないので、テスト自身の transaction が外側のトランザクションを終わらせてしまいます。また、ジョブのスレッドは別の接続を使うので、テストの行が見えません。
テストを実行する
cybertrain test # すべてのテスト
cybertrain test test/controllers # あるディレクトリ以下のファイル
cybertrain test test/models/article_test.rb # 1 つのファイル
cybertrain test -n "creates an article" # 名前で 1 つのテスト
cybertrain test -n test_creates_an_article # またはメソッド名で
cybertrain test -n /article/ # 名前に "article" を含むテスト
cybertrain test は SPIN_DEBUG=1 spin run gen を実行します(CLI のどのコマンドとも同じく、gen は spin のデバッグモードでビルドされます)。これが gen/tests.rb(プログラム)と、gen/test/ 以下に各テストクラスを書き換えたコピーを書き出します。どちらも gen/ のほかの部分と一緒にコミットします。次に、いずれかの入力がバイナリより新しければ gen/tests.rb を build/test/tests にコンパイルし(リリースビルド)、実行します。test/**/*_test.rb のすべてと、test/test_helper.rb 以外の test/*.rb のすべてがこれに入ります。test/support/(ヘルパーが読み込む)と test/fixtures/ にはテストはありません。プログラムは最初のテストの前に storage/test.sqlite3 を削除し、新しいデータベースをマイグレートして、その上でアプリケーションを起動します(ジョブ、スケジューラー、フィードのスレッドはなし:ジョブはテストが自分で実行します)。CYBERTRAIN_TEST_DATABASE を設定すると代わりに別のファイルを使います。プログラムはテストに使うファイルを削除するので、自分が作るデータベースすべてに印を付け(PRAGMA application_id、専用の値)、既存のファイルを削除したり空にしたりするのは、その印があるとき、このアプリケーション自身の storage/test.sqlite3(パスの書き方は問いません)であるとき、空のファイルであるときだけです。それ以外は終了ステータス 2 で何も削除せずに拒否します:cybertrain test refuses to delete <path>: not a database cybertrain test created; delete it yourself or name another file。development.sqlite3 や production.sqlite3 という名前のファイル(大文字小文字は問いません)、または storage/development.sqlite3 や storage/production.sqlite3 と同じファイルは、cybertrain test refuses to delete <path>: it is the development database(または production)で拒否されます。名前はファイルのパスでなければなりません::memory: と file: の URI は拒否されます(cybertrain test refuses CYBERTRAIN_TEST_DATABASE ":memory:": name the test database by its file path (not :memory: or a file: URI))。アップグレードのあと、以前 CYBERTRAIN_TEST_DATABASE で指定していたファイルには印がないので一度拒否されます:そのファイルを(-wal と -shm も)削除すれば、cybertrain test が印の付いたものを作ります。既定の storage/test.sqlite3 は何もしなくてかまいません。データベースを作っている間にシンボリックリンクに変わったパスは、終了ステータス 2 で拒否されます:cybertrain test refuses <path>: it became a symlink while the test database was created (nothing was marked or migrated); remove it and run again。各テストの前に空にするのはメインのデータベースのテーブルだけで、同じ名前の TEMP のテーブルや attach されたテーブルには触れません。既知の制限:印はテスト用データベースを cp しても残るので、テスト用データベースの名前を付けたコピー(またはテストが接続したもの)は空にされます。ファイルを作ってから印を付けるまでの間に止められた実行は、指定したパスに印のないファイルを残し、次は拒否されます(削除してください)。storage/test.sqlite3 がディレクトリだと、プログラムが削除するときに例外になります。
プログラムは、config/app.rb が自分で同じことを設定していない限り、Rails と同じようにテスト環境を整えます:リクエスト偽造対策は無効、リクエストのログは出さず(レベル :none。エラーの行は出ます)、ログの行はテキスト(エクスポートされた CYBERTRAIN_LOG_FORMAT は読みません)、エラー報告は Sentry に送らず(エクスポートされた CYBERTRAIN_SENTRY_DSN は空にします)、メールは Mailer.deliveries に保持し(:test)、force_ssl は無効(テストでは変数 CYBERTRAIN_MAIL_DELIVERY_METHOD と CYBERTRAIN_FORCE_SSL は、不正な値でも読まれません)、アップロードは tmp/test_uploads/ に書かれて実行のたびに空になり、ホストの検査は行いません(CYBERTRAIN_HOSTS を export しても有効になりません)。*_url ヘルパーのホストである www.example.com は常に許可されたホストです。
test/controllers/articles_controller_test.rb
ok ArticlesControllerTest: shows an article
FAIL ArticlesControllerTest: creates an article (test/controllers/articles_controller_test.rb:14)
Expected change of 1, got 0 (from 2 to 2)
test/models/article_test.rb
ok ArticleTest: title must be present
3 tests, 6 assertions, 1 failure
ファイルごとに見出し、テストごとに 1 行、最後に合計を出し、所要時間は出しません。示される行はテストの test "..." の行です:コンパイル済みのプログラムにはバックトレースがないので、失敗したアサーションの行はわかりません。終了ステータスは、失敗したテストがあれば 1、なければ 0、受け付けない引数には 2 です。テスト対象のコードが自分で出力したもの(コマンドの出力行など)は、テストの行の間に出ます。テスト、setup、teardown、フックが NotImplementedError、ほかの ScriptError、SystemStackError を発生させても、ほかの例外と同じく ERR になり、実行は続きます。実行を終わらせるのは Interrupt、SystemExit、NoMemoryError だけです。Spinel では、本当のスタックオーバーフローは今もセグメンテーション違反でプロセスを終わらせます:ランナーに届くのは、コード自身が発生させた SystemStackError だけです。
引数:-n NAME はその名前またはメソッド名のテストを残し、-n /TEXT/ は名前またはメソッド名に TEXT を素の文字列として含むテストを残します(.、?、() は文字そのものです)。^ $ \ * + [ ] { } | のどれかを含む TEXT は正規表現ではないので、終了ステータス 2 で拒否されます:-n /^test_create/: the text between the slashes is a plain substring of the test name, not a regexp (^ would be looked for as itself); write the text to look for (-n /test_create/)。ファイルやディレクトリはそのテストを残します。FILE:LINE は拒否され(line filters are not supported; give the file, and -n for the name)、-- でオプションが終わります。どのテストも残らない絞り込みは、合計の前に no test matched the filter を出して 0 で終わります。test/ 以下のファイルを加えたり消したりすると、プログラムはコンパイルし直されます。
変更にかかる手間。 ファイルの引数と -n は、どのテストを実行するかを選ぶもので、何をコンパイルするかは変えません。プログラムは常にすべてのテストを含むので、絞り込みを変えてもバイナリはそのまま使われます。一方、どれか 1 つのテスト(あるいはプログラムを作るほかの何か)を編集すると、先に bin/gen をビルドし直したうえで、プログラム全体をコンパイルし直します。2026-11-12 と 2026-11-13 に、共有の 4 vCPU のクラウドマシンで測った値です(手元のマシンでは違います):examples/blog の 21 ファイル 149 テストは、初回のコンパイルに約 527 秒かかり(初回の実行全体で 656 秒、バイナリは 10.2 MB)、そのあと何も変えずに cybertrain test test/controllers を実行すると、バイナリをそのまま使って約 1 秒で始まりました(ブログ自身の実行、2026-11-13)。ブログのアプリケーションに 3 つのテストファイル(8 テスト)を入れたものは、最大約 2.2 GB のメモリで 162〜233 秒かけてコンパイルされ、8.1 MB のバイナリになりました(2026-11-12)。テストはいくつか書いてからまとめて実行し、1 つのテストに取り組む間は、ビルドではなく実行のほうを絞り込んでください。
2 つのテストファイルやサポートファイルが同じトップレベルのメソッドや定数を定義していると(1 つのプログラムの中では 1 つになってしまいます:共有するヘルパーは test/support/ か、クラスの中に移してください)、gen/tests.rb は拒否され、cybertrain test はコンパイルせずに理由を出して 1 で終わります。テストクラスで gen が拒否するもののほかの場合も同じです。
フィクスチャ
alice:
email_address: alice@example.com
admin: true
one:
title: First post
body: A body long enough to pass the length check.
author: alice
created_at: 2026-11-01 09:00:00
two:
id: 42
title: Second post
body: Another body long enough.
author: alice
test/fixtures/<table>.yml は Rails と同じ形です:ラベル、その下にカラム。gen は実行時にファイルを辞書と同じ YAML のサブセットで読み、次のものを ファイル:行 を付けて拒否します:db/schema.rb のテーブルではないファイル、カラムでもモデルの belongs_to でもないキー、ERB(どこかに <% があること:eval はありません。現在時刻からの相対的な時刻は setup か travel_to で設定してください)、カラムの型に合わない値(存在しない日付、64 ビットに収まらない整数、真偽値の yes)、同じ id の 2 つのラベル、親のファイルのどの行も指さない belongs_to のラベル。DEFAULTS は Rails と同じく行ではありません。
id:のない行には、ラベルに対する Rails の id が付きます(ActiveRecord::FixtureSet.identify)。そのため、ラベルの id は Rails のアプリケーションと同じです。author: aliceはauthor_idを alice の id にします。- 日時は UTC です。行が省いた
created_atとupdated_atは、各テストの前にその行を挿入した時点の時計の時刻になります。 articles(:one)はその行のArticle.findを返します。未知のラベルはCybertrain::Test::FixtureNotFoundを発生させます。1 回の呼び出しで 1 つのラベルです。- フィクスチャは gen の実行時に検査されますが、そのエラーで止まるのはテストの実行だけです:
spin run genは先に進みます。スキャフォールドはマイグレーションより先にフィクスチャを書くので、cybertrain db migrate(先に gen を実行します)も止まりません。そしてcybertrain testがtest/fixtures/<table>.yml:<行>: ...を出して 1 で終わります。 - Rails と同じく、親を指すフィクスチャがあると、その親は削除できません:
comments.ymlにarticle: oneがあると、スキャフォールドの「should destroy article」は外部キーで失敗します。has_many :comments, dependent: :destroyを宣言するか、子のフィクスチャを別の行に向けるか(article: two)、何からも参照されていない行を削除してください。 - 提供しないもの:
fixtures :articles(どのファイルも読み込まれます)、articles(:one, :two)、ポリモーフィックなラベル(commentable: one (Article)。_idと_typeのカラムを書いてください)、has_and_belongs_to_manyのラベル、アンカーとエイリアス。
統合テスト
ActionDispatch::IntegrationTest は起動したアプリケーションにプロセス内でリクエストを送ります。ソケットは使わず、cookie jar はテストごとに新しくなります:
get、post、patch、put、delete、head(パス、params: {}、headers: {})。書き方は Rails と同じです。どれもCybertrain::Responseを返し(Rails はステータスを返します)、それはresponseでもあります(response.body、response.status、response.header(name))。params:は入れ子の Hash を受け取り、フォームと同じ形で送ります(article[title]=New)。値は String、Symbol、数値、true/false、nil、Date、Time にでき(カラムが読み戻すテキストとして送られます)、スキャフォールドのテストはレコードの値をそのまま送れます。Array は拒否されます。post、patch、putのparams:にfixture_file_upload("cover.png", "image/png")を入れると、リクエストは multipart で送られます。ファイルはtest/fixtures/files/から読まれます。headers:はヘッダーの名前か、Rails のHTTP_ACCEPTの形を取ります。config/routes.rbのパスヘルパーはコントローラーの中と同じく使えます。*_urlヘルパーはhttp://www.example.com/...を書きます。このホストの URL はパスでリクエストされ、assert_redirected_toはどちらの形でも比べます。ほかのホストの URL は拒否されます。cookiesはテストの cookie jar で、Cybertrain::Test::ClientCookiesです:cookies[:user]またはcookies["user"](生の、パーセントエンコードされたままの値)、[]=、key?、delete、keys、size、empty?、to_h。Max-AgeやExpiresが時計の上で過ぎた cookie は、その先へtravel_toした場合も含めて消えます(Max-AgeがExpiresより優先されます)。テストが[]=で書いた cookie は期限切れになりません。読めないMax-Age(Max-Age=abc)は無視され、負の値なら cookie は期限切れになります。Rails のものと違い、each、length、include?、fetch、==はありません:移植したテストではその代わりにcookies.to_hを読んでください。follow_redirect!は最後のレスポンスのLocationを(#fragmentを除いて)リクエストします。リダイレクトではないレスポンスのあとでは、テストを失敗させます:follow_redirect!: the last response was 200, not a redirect (3xx with a Location)。assert_response(:success)(どのステータスのシンボルでも、数値でも。:errorはちょうど 500 を意味し、Rails はどの 5xx でも受け付けます)、assert_redirected_to(path)、assert_select、assert_turbo_stream。- ないもの:
session、flash、assigns、request、host!、as:。代わりにページを検証してください(assert_select、response.body)。
リクエスト偽造対策は、Rails のテスト環境と同じく、config/app.rb が csrf を設定しない限りテストでは無効です。そのため post にトークンは要りません。この検査そのもののテストは、いくつかのリクエストだけ有効にします:
test "a form without the token is refused" do
with_forgery_protection do
post articles_path, params: { article: { title: "x" } }
assert_response :forbidden
end
end
ブロックの中では、フォームにはテストがリクエストしたページの authenticity_token が必要です。ブロックが終わると、中のアサーションが失敗した場合でも、すべて元に戻ります。テスト自身が設定したもの(アップロードのルート、ゾーン、ロケール、ログレベル)はそのまま残ります。
サインイン。 cybertrain generate authentication は test/support/session_test_helper.rb を書き出し、これはどの統合テストにも include されます:sign_in_as users(:one)(フィクスチャのユーザーのパスワードは "password"。remember: true で「ログインしたままにする」にチェックが入ります)、sign_out、authenticity_token_in(response.body)(ページの最初のフォームのトークン。with_forgery_protection の中のリクエスト用)、そして自分のクッキーを持つ 2 つ目のブラウザーである open_session(phone = open_session のあと、phone.sign_in_as users(:two) や phone.get ...)。リクエストはどれも 127.0.0.1 から来ます。別のクライアントアドレスが必要なテストは、自分で client = Cybertrain::Test::Client.new(Cybertrain::Test.app) を作って client.peer_address = "203.0.113.7" を設定します(クライアント自身のメソッドは client.get(path, headers) と client.post(path, fields, headers) です)。
アサーション
assert、assert_not(refute)、assert_equal、assert_not_equal、assert_nil、assert_not_nil、assert_includes、assert_not_includes、assert_empty、assert_not_empty、assert_match / assert_no_match(Regexp か、部分文字列としての String)、assert_in_delta(expected, actual, delta = 0.001)、assert_nothing_raised { }、flunk が Minitest と同じくあります。assert_equal は Minitest のテキスト(2 行の Expected: 1 と ` Actual: 0)で失敗し、新しく加わったアサーションも同様です。assert_includes、assert_nil、flunk はそれぞれ独自の短いテキストのままです。assert と refute` は 2 つ目の引数にメッセージを取ります。ブロックの形はラムダを位置引数で取ります:
assert_difference -> { Article.count }, 1 do
post articles_path, params: { article: { title: "New", body: "A body long enough" } }
end
assert_no_difference(-> { Article.count }) { post articles_path, params: { article: { title: "" } } }
assert_changes(-> { article.reload.title }, from: "Old", to: "New") { article.update(title: "New") }
message = assert_raises(Cybertrain::RecordNotFound) { Article.find(999) }
assert_includes message, "999"
assert_raisesはクラス(Minitest と同じくサブクラスも一致します)、String としてのクラス名の一部(assert_raises("RecordNotFound"))、または何も取らず(どの StandardError でも)、例外ではなく例外のメッセージを返します:Rails でerror = assert_raises(X) { }と書いてerror.messageを使うところでは、返ってくる String を使ってください。Spinel ではメソッドは 1 つの型しか返せず、テストが読むのはメッセージだからです。- ブロックのアサーションはブロックの値ではなく nil を返します。
- 提供しないもの:
assert_predicate(計算されたsendが要ります:assert article.valid?と書いてください)、assert_differenceの String の式(evalが要ります)、式の Array や Hash、ほかのアサーションのメッセージの引数。Minitest のrefute_*の名前のうちあるのはrefuteだけです:assert_not_equal、assert_not_nilなどのassert_not_*の形を書いてください。refute_equalを呼ぶと、定義しているものがないので、テストプログラムのビルドが止まります。
タイムトラベル
test "a remembered session survives day 15" do
sign_in_as users(:one), remember: true
travel_to 15.days.from_now do
get root_path
assert_response :success
end
end
test "the cache entry expires" do
freeze_time
Cybertrain::Cache.write("k", "v", expires_in: 5.minutes)
travel 6.minutes
assert_nil Cybertrain::Cache.read("k")
end
travel_to(time)、travel(seconds)、freeze_time、travel_back は Rails のヘルパーです:どれも時計を止め、1 秒未満の部分を落とします。ブロックを渡すと、ブロックが終わったとき(例外が起きたときも)元の時刻に戻り、渡さなければ travel_back かテストの終わりまで移動したままです。フレームワークが時刻を記録するものはすべてこれに従います:Time.current、テストプログラムの中の Time.now、レコードのタイムスタンプ、キャッシュの有効期限、レート制限、セッションの寿命、ジョブの run_at、トークンの有効期限、スケジューラー。待ちとタイムアウト(ストリームの読み取り、受信者)は実時間のままなので、時計を止めても待ちが止まったままになることはありません。本番では Time.now はシステムの時計です:移動に従うべきコードは、Rails が勧めるとおり Time.current を読みます。Time.now は組み込みのものと同じくプロセスの TZ での現地時刻を返し、Time.current は UTC です。travel_to が取るのは Time で、Date は取りません。Time.zone.local もありません:瞬間は Time.utc(...) で書いてください。スケジューラーは覚えていること(最後の回復、次の実行時刻)をタイムトラベルの間も持ち続けます。スケジューラーやワーカーのスレッドが動いている間にタイムトラベルするテストはサポートしていません。
期間は Integer の秒です:5.minutes は 300 で、2.weeks.ago と 3.days.from_now は時計の上の Time を返します。1.month はありません(1 か月には秒での長さがありません):実行されたときに NoMethodError になります。Time のカレンダーのメソッドを使ってください:Time.current.months_ago(1)、advance(months: 1)、beginning_of_day、end_of_month、yesterday(時刻とタイムゾーン)。advance は時、分、秒をカレンダーの部分のあとに経過時間として足し、Integer を取ります。実時間の時計はマイクロ秒を保ちます。
ストリームとコンポーネントのテスト
require "test_helper"
class CommentComponentTest < ViewComponent::TestCase
test "renders the comment" do
render_inline(CommentComponent.new(comment: comments(:one)))
assert_select "div.comment strong.comment-author", text: "Alice"
end
test "renders the form partial" do
html = render_inline(partial: "articles/form", locals: { article: Article.new })
assert_select "form[action=\"/articles\"] input[name=\"article[title]\"]"
assert_includes html, "Save"
end
end
render_inline(component, content: "") と render_inline(partial:, locals: {}) はリクエストの外でレンダリングし、HTML を返して(Rails は Nokogiri のフラグメントを返し、内容をブロックで受け取ります)、assert_select のために保持します。リクエストを必要とするヘルパーは Cybertrain::Views::OutsideRequest を発生させます。
assert_select(selector, equality = nil, count:, minimum:, maximum:, text:) は、このテストの最後の render_inline かレスポンスを検査し(どちらもなければ「No response yet」で失敗します)、一致した要素を返します:
- セレクター:タグ、
.class、#id、[attr]、[attr="v"]、それらの組み合わせ(a.btn[href="/x"])、子孫と子(>)の結合子、リスト(h1, h2)。疑似クラス、+と~、ほかの属性演算子、バックスラッシュ(assert_select: CSS escapes (\) are not supported)、入れ子のブロックの形はassert_select: <feature> is not supportedで失敗します。 text:は各要素のテキストと比べる String か、そのテキストに当てる Regexp です。テキストは、空白の連続を 1 つのスペースにし、両端を取り除いたものです(Rails は両端を取り除くだけです)。2 つ目の引数は Rails の位置引数の形にでき、テキスト(String か Regexp)、件数(Integer)、true/falseを取ります。件数には2..3のような Range も使えます。そこで件数を渡しつつcount:、minimum:、maximum:も渡すと拒否され、負の Range、逆向きの Range、両端のない Range も拒否されます(assert_select: a Range count needs both ends (got 2..))。- HTML は書かれたとおりに読まれ、ブラウザー(と、Rails の
assert_selectの裏にある Nokogiri)のように修復はされません:<tbody>なしで書かれた表にはtable > trが一致し、<p><div>にはp > divが一致し、省略された終了タグ(<li>a<li>b、<p>a<p>b)や自己終了の<div/>は、その位置を示してアサーションを失敗させます。フレームワーク自身のテンプレートはすべて読めます。
ブロードキャストは cybertrain_messages の行なので、ストリームのアサーションはポーラーもソケットも使わずにテーブルを読みます:
test "a new comment is broadcast and answered with a Turbo Stream" do
article = articles(:one)
payloads = assert_broadcasts(article, 1) do
post article_comments_path(article), params: { comment: { commenter: "Dave", body: "Hi" } },
headers: { "Accept" => "text/vnd.turbo-stream.html" }
end
assert_includes payloads[0], 'target="comments"'
assert_turbo_stream action: "append", target: "comments"
end
assert_broadcasts(stream, count) { } は、ブロックの間に(ブロックがなければテストの始まりから)ストリーム(名前かレコード)へブロードキャストされたものを数え、その内容を返します。assert_no_broadcasts(stream) は 1 つもないことを求めます。assert_turbo_stream(action:, target:, count: 1) は最後のレスポンス(text/vnd.turbo-stream.html でなければなりません)か、最後の render_inline を読みます。ブラウザーのようにライブのストリームを読むには、Cybertrain::Test::Client の client.get_stream(path, events: n) がストリーミングのレスポンスをメモリ上で動かします(リアルタイム)。そこでライターが投げた例外はテストに届きます。動いているアプリケーションでサーバーが報告するようには報告されません。
メールのテスト
cybertrain test では、config/app.rb が設定していない限り Cybertrain.config.mail_delivery_method は :test です:deliver_now、Mailer.deliver、deliver_later のジョブはメッセージを検査し、接続する代わりに Cybertrain::Mailer.deliveries に保持します。このリストは各テストの前に空になります。アプリケーションが送信者を設定していなければ、テストプログラムはメールの送信者を from@example.com にします。
test "a reset mails a link" do
assert_emails 1 do
post passwords_path, params: { email_address: users(:one).email_address }
end
mail = Cybertrain::Mailer.deliveries.last
assert_equal "Reset your password", mail.mail_subject
assert_includes mail.mail_body, "/passwords/"
end
assert_emails(count) { } はブロックが送ったメールを数えます。ブロックの中で deliver_later でキューに入れたメールは先に送られ、失敗したメールのジョブはそのエラーでアサーションを失敗させます。assert_no_emails { } は 1 通もないことを求めます。メッセージの読み取りメソッドは mail_to、mail_from、mail_subject、mail_body、mail_html です。SMTP の経路そのもののテストは Cybertrain.config.mail_delivery_method = :smtp を設定し、teardown で :test に戻します(この設定はテストの間でリセットされません)。外向きの呼び出しをテストすると同じです。テスト環境の外では :test は警告を出して起動し、メールは送られません。
ジョブのテスト
require "test_helper"
class NotifyCommentJobTest < ActiveSupport::TestCase
test "a comment queues its notification, which runs" do
comment = comments(:one)
NotifyCommentJob.perform_later("comment_id" => comment.id, "article_id" => comment.article_id)
assert_enqueued_jobs 1, "NotifyCommentJob"
assert_enqueued_with "NotifyCommentJob", { "comment_id" => comment.id }
assert_equal 1, perform_enqueued_jobs
assert_no_enqueued_jobs
end
test "the jobs a block queues run at once" do
performed = perform_enqueued_jobs { ReminderJob.perform_in(3600, { "id" => 1 }) }
assert_equal 1, performed
end
end
assert_enqueued_jobs(count, kind = "")はキューにあるジョブを数えます(種類を指定すればその種類だけ)。assert_no_enqueued_jobs(kind = "")は 1 つもないことを求めます。assert_enqueued_with(kind, args)は、その種類のジョブで、引数が指定したキーをすべて同じ値で持つものがキューにあることを求めます("comment_id" => 7は JSON の7に一致します。comment_id: 7でも動きます)。perform_enqueued_jobs { }は Rails のインラインの形で、ブロックを実行し、そのあとブロックの間にキューに入ったジョブと、それらがキューに入れたジョブを、run_atにかかわらずすべて実行し、実行した数を返します。例外を出したジョブはそのクラスとエラーでテストを失敗させ、再試行されません。アプリケーションが破棄したジョブ(discard_on)は実行済みと数えます。- ブロックのない
perform_enqueued_jobs(now = Time.current)は、nowの時点で期限の来たジョブを 1 つずつ、なくなるまで実行します。あとに予定された再試行はキューに残ります:その時刻を過ぎるまでtravelするか、もっと遅いnowを渡してください。どちらの形も、10,000 件のジョブのあとテストを失敗させます(自分自身を再びキューに入れるジョブ)。 clear_enqueued_jobsはキューにあるジョブを削除します。WelcomeJob.perform_now(args)はジョブを 1 つ直接実行し、例外はテストまで届きます。- 定期タスクは
Cybertrain::Scheduler.run_due(Time.current.to_i)(エポック秒) で 1 回ずつ実行します。
外向きの呼び出しをテストする
テスト対象のコードが Webhook(外向きの HTTP)や SMTP でのメール(メールを送る)を送るとき、テストはそれをプロセス内で受け取ります:Cybertrain::Test::HttpReceiver と Cybertrain::Test::SmtpReceiver は 127.0.0.1 で待ち受け、届いたものを記録し、用意した返事で答えます。テストの中で起動した受信者は、テストが失敗した場合でも、そのテストのあとに止められます。
require "test_helper"
require "cybertrain/test/http_receiver"
require "cybertrain/test/smtp_receiver"
class SignupHookTest < ActiveSupport::TestCase
setup do
Cybertrain.config.http_allow_private = true # そうしないと HttpClient はループバックを拒否する
end
teardown do
Cybertrain.config.http_allow_private = false
Cybertrain.config.mail_delivery_method = :test
end
test "a sign-up posts a webhook" do
hook = Cybertrain::Test::HttpReceiver.new(status: 202, body: "queued")
hook.start # 空いているポートにバインドし、それを返す
SignupHook.post(hook.url("/hooks/signup"), "ann@example.com") # アプリのコード
req = hook.received_request # 最大 5 秒待つ。何も来なければ nil
assert_equal "POST", req.http_method
assert_equal "/hooks/signup", req.http_target
assert_equal "application/json", req.http_header("Content-Type")
assert_includes req.http_body, "ann@example.com"
end
test "a refused recipient is reported" do
Cybertrain.config.mail_delivery_method = :smtp
smtp = Cybertrain::Test::SmtpReceiver.new(reject: { rcpt: "550 5.1.1 no such user" })
port = smtp.start
mailer = Cybertrain::Mailer.new(host: "127.0.0.1", port: port, tls: "none", from: "app@example.com")
assert_raises("RejectedError") { mailer.deliver(to: "nobody@example.org", subject: "Hi", body: "Hello\n") }
mail = smtp.received_message
assert_equal ["EHLO localhost", "MAIL FROM:<app@example.com>", "RCPT TO:<nobody@example.org>"],
mail.transcript.first(3)
assert_not mail.delivered?
end
end
HttpReceiver.new は用意する status:、headers:、body:、chunked: を取ります(respond_with でリクエストの間に変えられます)。リクエストは ReceivedRequest として返ります(http_method、http_target、http_path、小文字の名前の http_headers、http_header(name)、chunked の本文をデコードした http_body)。SmtpReceiver は 220、EHLO(eight_bit_mime: false でなければ 8BITMIME 付き、auth: true で AUTH PLAIN 付き)、MAIL、RCPT、DATA、QUIT を演じます。reject: は :greeting、:ehlo、:mail、:rcpt、:data、:message のどれでも、指定した返事で失敗させます。ReceivedMessage には envelope_from、envelope_recipients、message_data(ドットスタッフィングを戻したもの)、message_header(name)、message_body、コマンドの transcript があり、HTML のメッセージなら message_parts が "subject"、"text"、"html" にデコードします。どちらも max: で増やさない限り 1 つの接続を受け付けます(received_requests / received_messages がすべてを返します)。待ちにはすべて上限があります:受信者は接続がないまま accept_window:(10 秒)が過ぎるとあきらめ、黙ったクライアントは read_timeout:(5 秒)で切り、stop(2 回呼んでも安全)はスレッドを終わらせてポートを閉じるので、受信者があとのテストの接続を取ることはありません。テストの外で(ファイルの先頭で)起動した受信者は、自動では止められません。
フィードも同じように、127.0.0.1 上の台本どおりに動く WebSocket サーバー Cybertrain::Test::WebSocketReceiver でテストします:各接続は Cybertrain::Test::WsStep のリスト("accept"、"send_text"、"expect"、"silent"、"close"、"drop"、"echo_until_close" など)を演じ、クライアントが送ったフレームはマスクを外して ws_received から返ります。
require "test_helper"
require "cybertrain/websocket"
require "cybertrain/test/websocket_receiver"
TICKS = Array.new(0) { "" } # 定数:ブロックからはローカル変数が見えない
# ブロックは、そのパラメーターが使われるメソッドの中に書く。
def subscribe_trades(url)
Cybertrain::WebSocket.subscribe("trades", url, allow_private: true)
.on_open { |conn| conn.send_text("subscribe") }
.on_message { |conn, text| TICKS << text }
end
class TradesFeedTest < ActiveSupport::TestCase
test "a trade message is stored" do
rx = Cybertrain::Test::WebSocketReceiver.new
rx.ws_script([Cybertrain::Test::WsStep.new("accept"), Cybertrain::Test::WsStep.new("expect"),
Cybertrain::Test::WsStep.new("send_text", "tick"), Cybertrain::Test::WsStep.new("echo_until_close")])
rx.start
subscribe_trades(rx.url("/trades"))
Cybertrain::WebSocket.start! # テストプログラムはフィードを起動しない
# ... 最大で数秒、TICKS をポーリングする ...
Cybertrain::WebSocket.stop!
assert_equal ["tick"], TICKS
assert_equal "subscribe", rx.ws_received[0].rec_data
end
end
Cybertrain::WebSocket.random_source = -> { 0.5 } で再試行の間隔が正確になります。このリポジトリの test/websocket_integration.rb に完全なテストがあります。
ログとエラー報告のテスト
レスポンスの X-Request-Id がリクエストの ID です。ログの行を読むには、テストが見たい処理の間だけ Cybertrain.logger に StringIO を渡し、後でロガーを戻します。これは専用のメソッドの中で行います(yield を囲む rescue や ensure は、Spinel では素のメソッドに置きます):
require "test_helper"
require "stringio"
class LoggingTest < ActionDispatch::IntegrationTest
test "a comment's job logs the request's id" do
post article_comments_path(articles(:one)), params: { comment: { commenter: "Ann", body: "Hi" } }
rid = response.header("X-Request-Id").to_s
log = StringIO.new
perform_jobs_logging_to(log)
assert_includes log.string, "] [#{rid}] new comment "
end
private
def perform_jobs_logging_to(io)
saved = Cybertrain.logger
Cybertrain.logger = Cybertrain::Logger.new(io)
perform_enqueued_jobs
ensure
Cybertrain.logger = saved
end
end
行頭の時刻は実行のたびに変わるので(比べるなら freeze_time で止めます)、その後ろ、つまりレベル、タグ、メッセージを比べます。アプリケーションのリクエストログはテストでは出ませんが(log_level :none)、失敗したジョブの ERROR の行はそれでも書かれます。失敗するジョブを実行するテストは上のようにロガーを捕まえます。そうしないと、その行がテストの行の間に出ます。
エラー報告は Cybertrain::Test::SentryReceiver に届きます。これは cybertrain/test_help が読み込む 127.0.0.1 上の Sentry です。cybertrain test はエクスポートされた DSN を無視するので、テストが DSN を代入し、後で戻します。この例は examples/blog の NotifyCommentJob を動かします。これはコメントを Comment.find で探し、コメントがなくなっていると Cybertrain::RecordNotFound でジョブを破棄します(Retries and discards)。チュートリアルのジョブはログを出すだけなので、先にその Comment.find と discard_on Cybertrain::RecordNotFound を足してください:
require "test_helper"
class ErrorReportingTest < ActionDispatch::IntegrationTest
setup do
@sentry = Cybertrain::Test::SentryReceiver.new
@sentry.start
@saved_dsn = Cybertrain.config.sentry_dsn
@saved_private = Cybertrain.config.http_allow_private
Cybertrain.config.sentry_dsn = @sentry.dsn # http://public@127.0.0.1:<port>/1
Cybertrain.config.http_allow_private = true # そうしないと HttpClient はループバックを拒否する
end
teardown do
Cybertrain.config.sentry_dsn = @saved_dsn
Cybertrain.config.http_allow_private = @saved_private
end
test "a job whose comment is gone is discarded and reported" do
NotifyCommentJob.perform_later("comment_id" => 999_999, "article_id" => articles(:one).id)
perform_enqueued_jobs # 破棄でテストは失敗しない
event = @sentry.received_events(1)[0] # 最大 5 秒待つ
assert_equal "NotifyCommentJob", event.sentry_field("transaction")
assert_equal "Cybertrain::RecordNotFound", event.sentry_field("exception.values.0.type")
end
end
SentryReceiver.new(status: 200, max: 50, accept_window: 10.0) は各エンベロープに Sentry と同じように応答します(429 など別の status: で、拒否する Sentry を演じます)。dsn(project = "1", prefix = "") はそこに送る DSN で、received_events(count, wait = 5.0) は届いたものを返します。それぞれは Cybertrain::Test::SentryEnvelope で、sentry_path、sentry_auth(X-Sentry-Auth)、sentry_content_type、sentry_body(3 行の JSON)、イベントのフィールドを読む sentry_field("a.b.0.c")(ないときは "")、エンベロープのヘッダーを読む sentry_header_field(name) を持ちます。extra のドットを含むキーは丸ごと読めます。オブジェクトの中では、パスのうちキーになる最も長い部分が先に取られるからです:sentry_field("extra.job.attempt")。テストの中で起動したレシーバーは、ほかのレシーバーと同じくテストの後に止まります。
テストで追加したサブスクライバーは次のテストの前に外れます(config/app.rb が追加したものは残ります)。各テストの前に、レポーターはまだキューにあるものを届け、重複除去の時間枠を忘れるので、2 つのテストで同じ失敗が起きればどちらでも報告されます。サブスクライバーが受け取ったものを読むテストのために、Cybertrain.error.drain_reports がキューの報告を(最大 2 秒)待ちます:
# テストファイルの先頭に:
REPORTS_SEEN = Array.new(0) { "" }
class SeenReports < Cybertrain::ErrorSubscriber
def report(event)
REPORTS_SEEN << event.error_class
nil
end
end
# テストの中で:
Cybertrain.error.subscribe(SeenReports.new)
get "/articles/999999"
Cybertrain.error.drain_reports
assert_equal 0, REPORTS_SEEN.size # 404 は報告されない
テストクラスで gen が拒否するもの
gen はテストクラスをメソッドに書き換えます:test "shows it" do は def test_shows_it になり([A-Za-z0-9_] 以外の ASCII の文字は _ に、それ以外の文字は _u<hex>_(小文字のコードポイントを _ で閉じたもの)になるので、"ログ" は test__u30ed__u30b0_、"café x" は test_caf_ue9__x です。-n にはメソッド名も書いたとおりの名前も渡せます)、setup do と teardown do のブロックは super を呼ぶ setup と teardown のメソッドになります。書き換えで正確に移せないものがあると、そのファイルは拒否されます。黙って誤ったコピーを作ったり、テストを失ったりはしません:
- 素の文字列リテラルではないテスト名(式展開)や、gen が読まないエスケープ(
\u、\x、\c、\C、\M、8 進数)を含むテスト名(文字そのものを書いてください。\n、\t、\"は読まれます)。 - 1 つのクラスの中でメソッド名が同じになる 2 つのテスト(
def test_xも含む)。 - 1 つのクラスの中の
setup doとdef setupの両方(teardownも同じ)、そして親がアプリケーションの基底クラスであるクラスの中の、superのないdef setupやdef teardown(基底クラスのsetup doブロックが実行されなくなります)。 - パラメーターを取る
def test_x、またはprivateやprotectedのあとのdef test_x(Minitest は public なテストメソッドしか実行しません)。 setup { }とsetup :name(setup do ... endと書いてください)、test、setup、teardownのブロックパラメーター。- テスト、setup、teardown の本体の中の
next、break、redo(本体の中のif、unless、case、beginの中にあっても。returnを使ってください)、return <value>(どれも nil を返します)。 - 別のクラスやモジュールの中に入れ子にしたテストクラス、2 回開いたテストクラス、開き直した
ActiveSupport::TestCaseの中のsetup do(setup doを持つアプリケーションの基底クラスを書いて継承してください)。 - gen がクラス本体の中に置けない
test、setup、teardownの行(条件、ループ、文字列、ヒアドキュメントの中)、endで終わらない 1 行の形、あとにコードが続くend、タブとスペースが混じったインデント。 - 引数が文字列リテラルではない
require_relative。
拒否されたファイルがあっても spin run gen は止まらないので、開発サーバー、cybertrain db migrate、cybertrain build は動き続けます:gen は理由を出すだけの gen/tests.rb を書き、cybertrain test はコンパイルせずに <path>:<line>: <reason> を出して 1 で終わります。示された行を直してください。test "name" do は test"name" やタブを挟んだ形でも書けます。private のあとに書いた test "x" do は拒否されませんが、コピーの中で private なメソッドになり、実行すると失敗します(Rails では実行されます):テストは private より上に書いてください。ほかの既知の制限:_u3042_ という文字列を含む名前は、そこを "あ" にした名前と同じメソッド名になります(1 つのクラスの中では gen がその組を拒否します)。モジュールの中の def setup は super の検査を受けません。アプリケーションの基底クラスから 2 段下のクラスは、その基底クラスが setup を定義していなくても super を求められます。テストファイルが拒否されている間、spin run gen -- --check は gen/test/ の古いコピーを比べません(CI は cybertrain test で失敗します)。
cybertrain test はさらに、同じやり方で次のものを拒否します:test/test_helper.rb や test/support/ の中のトップレベルの test、setup、teardown(実行されることがありません)、トップレベルの def render_inline(フレームワークのものを置き換えてしまいます)、assert_select ... do と render_inline ... do、そしてテストを実行するで述べた重複するトップレベルのヘルパー。クラスの形のファイルは cybertrain test でしか実行できません:spin test では、そのクラス本体が「class-form tests run with cybertrain test FILE」を発生させます。
トップレベルの形
以前の形、つまりファイルのトップレベルに書いた test ブロックはそのまま動きます。cybertrain test(ここでのように、プログラムのアプリケーションとフィクスチャを使って)でも、cybertrain spin test でも動きます:
require "test_helper"
setup do
Cybertrain.config.http_allow_private = true
end
teardown do
Cybertrain.config.http_allow_private = false
end
test "shows an article" do
client = Cybertrain::Test::Client.new(Cybertrain::Test.app)
res = client.get("/articles/#{articles(:one).id}")
assert_response res, :success
assert_includes res.body, articles(:one).title
end
Cybertrain::Test.run!
トップレベルの setup do と teardown do は、そのファイルの各テストの前後に実行されます。cybertrain spin test は各 test/*.rb を別々のプログラムにコンパイルし、出力を test/<name>.rb.expected と比べます。そこではテーブルを空にすることもフィクスチャもなく(どちらも gen のテーブルの一覧が要ります)、Cybertrain::Test.run! がファイルのテストを実行します。cybertrain test では、ファイルのテストはテーブルを空にしてフィクスチャを入れたあとにほかのテストと一緒に実行され、run! は何もしません。spin test ではそのファイルのためにアプリケーションを起動するものがないので、そのようなファイルは 0.4 のサポートファイル(AppTest.boot、BlogTest.boot)がしていたように自分で起動し、フィクスチャは使いません。Cybertrain::Test::Client は cookie jar を持ち、CSRF も含めてアプリケーションを操作します(client.get、client.post(path, fields, headers)、client.follow_redirect!、client.response、引数 2 つの assert_response res, :ok と assert_redirected_to res, path)。SQLite に触れるテストのスナップショットはコンパイル済みのバイナリから取ります:フレームワークのチェックアウトでは script/regen-snapshot test/<name>.rb、または rm -f build/test/<name>; cybertrain spin test test/<name>.rb; ./build/test/<name> > test/<name>.rb.expected 2>&1。
0.4 からのアップグレード
- 上のとおりに
test/test_helper.rbを加え、サポートファイルが読み込み時にしていたこと(AppTest.boot、BlogTest.boot、データベースのマイグレート)をそこから外してください:テストプログラムは最初のテストの前に新しいデータベースで起動し、2 回目の起動は時間がかかるだけです。 - CI のステップを
spin testからcybertrain testに変えてください。 - 同じトップレベルのヘルパーや定数を定義する 2 つのファイル(0.4 のジェネレーターが書いたように、それぞれにある
new_client)は一緒に拒否されます:ヘルパーをtest/support/に移すか、どちらかの名前を変えてください。 - 各テストの前にすべてのテーブルが空になるので、あとのテストが前のテストの作った行に頼ることはもうできません:そのようなデータはフィクスチャか
setupに移してください。 - 時計の差し込み口はなくなりました:
Cybertrain::Cache.clock=、Cache.system_clock、RateLimit.current_time=、SessionStore#fixed_now=、Application.status_now=、Background.supervisor_clock=。travel_to、travel、freeze_timeを使ってください。ブロックの形なら、自分でensureを書かなくても時刻が戻ります。 - テストのメールは
Cybertrain::Mailer.deliveriesに保持されます。Test::SmtpReceiverでメールを読むテストは、先にCybertrain.config.mail_delivery_method = :smtpを設定します。 - 0.4 の
generate helperが書いたヘルパーのテストはトップレベルのrender_inline(source)を定義しており、これはフレームワークのものとぶつかります:そのファイルの中で、呼び出しも含めてrender_helper_templateに名前を変えてください。 1.month.agoはTime.current.months_ago(1)と書きます。assert_equalは Minitest の 2 行のテキストで失敗します。通るテストのスナップショットは変わりません。cybertrain generate authenticationをもう一度実行すると、クラスの形のテストを書き出し、それらが置き換える古いファイル(test/authentication.rb、test/support/app_test.rbなど)をそれぞれ示します。--forceでそれらを削除します。- 角括弧のレベルで始まるログの行を丸ごと探していたテストは、レベルとメッセージを別々に探します(
" ERROR "と"password reset mail not sent: ")。行はいまは時刻で始まり、リクエストの ID を持つことがあります(ログ)。 - エクスポートされた
CYBERTRAIN_LOG_FORMATやCYBERTRAIN_SENTRY_DSNはテストに届かなくなりました。それらでテストするには、config/app.rbで設定するか、テストで DSN を代入します。
継続的インテグレーション
cybertrain new はアプリ用に .github/workflows/ci.yml を書き出します。これはこのリポジトリの setup-cybertrain アクション(.github/actions/setup-cybertrain)を CLI のリリースタグに固定して呼び出します。アクションは SQLite、zlib、OpenSSL のヘッダーと Ruby をインストールし、アプリが固定しているフレームワークのコミットを spin.lock から読み、そのコミットのフレームワークを取得して、その cybertrain doctor と cybertrain setup を実行します(~/.cybertrain/spinel は Spinel のリリースとランナーのイメージごとにキャッシュされます)。そのあとワークフローは spin.lock が最新であること(spin lock && git diff --exit-code spin.lock)と gen/ が新しいこと(SPIN_DEBUG=1 spin run gen -- --check)を確かめ、cybertrain test を実行します。ツールチェーンの手順が変わるときは、各アプリのコピーではなくアクションが変わります。コミットは spin.lock から読みます。既定の git 依存でも、インデックスのバージョン(--version)でも、spin.lock にはコミットが記録されます。--path で作ったアプリは、フレームワークのチェックアウトを framework-path としてアクションに渡します。