branchout 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8562cdf0b59fc28be9b1c811b63727f18fab5b7d2bd54cd24825886ef359eefe
4
- data.tar.gz: d31f8699dba5f5541b217e7a80a634d1b13980e95da99976e74fbefd48233dbf
3
+ metadata.gz: 64ff63d2e207e25cfe34c461bcd712be46940a68eae6a51d17be6c99d63e4003
4
+ data.tar.gz: ab0f5f0477436d194c2ace4c2ad79587d8dc6c8f052d67fd93e9491e54ee8140
5
5
  SHA512:
6
- metadata.gz: d258d697f2f20e02c160d6998c0f6ce8ee5221b0e2b4aeea89a74a3b6289fe3881d185c4be7f2b8a999a9ac0f0b10a83eb9eae45e9b8b89f4b3a8ac870e69d9d
7
- data.tar.gz: 37c6415b5be529624d65a394d9a676b77ec74dcd5018f0ee6112e0ff6ebf1fdc66eee12df77c9605d5d8a179c9c0d12877fe712e65dde6de70f285a701b3f422
6
+ metadata.gz: 46fb8a24081902c65ec8a86049719746df7cc976303d80d15da095b3db9528d8449ac00f05c51f79ffcc08061e5258b81237bb4998a79ddb4868680e1ca5d818
7
+ data.tar.gz: 4a2539e0ada077b1355156fc7dad6bdf8dca0f8cb6563b2d00b71163f1f483d55588b9b8ec23a203f92910340449b81ca7477e3a083964198085845d626c5c53
data/README.ja.md CHANGED
@@ -272,8 +272,11 @@ branchout は、メソッド自身のリテラルとシード付きの標本か
272
272
  カバレッジは入力が通った腕を数えるだけで、値は確かめない。
273
273
  それぞれの行を、メソッドが返すべき値と見比べる。
274
274
  1 行に収まらない値は、ほかの値と見分けられる Hash の葉を先に示し、収まる範囲で残りの最上位のスカラーを続ける(`returns a Hash with due_cents: 900, discount: 10, discount_cents: 100, ...`)。
275
+ Array、Struct、Data は、要素数かクラスを示し、同じ要素数やクラスのほかの値と見分けられる葉を続ける(`returns an Array of 2 with [1].kind: "skips-callbacks", [0].line: 2, ...`)。
275
276
  入力ファイルの入力が 1 行に収まらないときは、そのファイルでの位置で示す(`inputs[3]`)。
276
277
  `--json` は、値全体を Ruby リテラル(`value`)で、入力全体もそのまま示す。
278
+ 一時ディレクトリやホームディレクトリの下のパスは、`<tmp>/` や `<home>/` で始め、その下のディレクトリを `.../` で示す(`"No hit under <tmp>/.../app."`)。
279
+ `value` でも同じなので、レポートはどのマシンでも同じになる。
277
280
  `EXCEPTIONS` は、例外とそれを出した場所ごとに 1 行で、出した入力の件数とその 1 件を示す。
278
281
  `--verbose` を付けると、通った各腕の入力も表示する。
279
282
 
@@ -286,7 +289,7 @@ cat shipping_spec.rb
286
289
  ```ruby
287
290
  # frozen_string_literal: true
288
291
 
289
- # Generated by branchout 0.1.0. Characterization specs for discovered inputs.
292
+ # Generated by branchout 0.2.0. Characterization specs for discovered inputs.
290
293
  # target: shipping.rb
291
294
  # entry: Shipping.fee
292
295
 
@@ -409,7 +412,7 @@ Finished in 0.00228 seconds (files took 0.07051 seconds to load)
409
412
  このリポジトリのチェックアウトでは、`ruby bin/branchout` が `branchout` と同じコマンドを実行する。
410
413
  種ファイルの入力は `[0]` の 1 件である。
411
414
  `--verbose` はレポート全体を出す。
412
- 動いた戦略の実行の設定と件数のあとに、`COVERED`(各腕を通った入力)、`FRONTIER`(どの入力も通らなかった各腕と、`nearest` が通った腕の `path`)、`RETURNED`(各値と、それを返した入力)、`EXCEPTIONS`(例外を出した入力ごとに 1 件)、`NOT COUNTED`、`OPERATORS`、`BOUNDARIES` が続く。
415
+ 動いた戦略の実行の設定と件数のあとに、`COVERED`(各腕を通った入力)、`FRONTIER`(どの入力も通らなかった各腕と、`nearest` が通った腕の `path`)、`RETURNED`(各値と、それを返した入力)、`EXCEPTIONS`(例外を出した入力ごとに 1 件)、`after` を持つ入力があるときの `AFTER`(読んだ値ごとに、それを読んだ入力)、`NOT COUNTED`、`OPERATORS`、`BOUNDARIES` が続く。
413
416
  付けないときのレポートは、件数と、入力が届いた `FRONTIER` の腕を、変えるべき `nearest` の入力の下に 1 行ずつと、どの入力も届かなかった決定ごとに 1 行と、返した値ごとに 1 行と、例外とそれを出した場所ごとに 1 行を残す。
414
417
  [アプリなしで試す](#アプリなしで試す) の出力がその形である。
415
418
  `--json` は、レポート全体のすべての項目を持つ。
@@ -482,7 +485,8 @@ BOUNDARIES
482
485
  `{"args": [5], "new": {"kwargs": {"main": 1}}}` は `Const.new(main: 1).method(5)` を呼ぶ。
483
486
  メソッドが読む状態が `new` のあとの呼び出しで決まるときは、その呼び出しを順に `setup` へ書く。
484
487
  `{"args": [], "setup": [{"method": "add", "args": ["apple", 3]}]}` は、新しいレシーバーで `add("apple", 3)` を呼んでからメソッドを呼ぶ。
485
- 各ステップは `method`、`args`、`kwargs` を取る。
488
+ 各ステップは `method`、`args`、`kwargs`、`block` を取る(`{"method": "start", "args": ["r1"], "block": "{ hold.pause(:read); :end }"}`)。
489
+ `setup` があるときは、`new` で作ったレシーバーにも出力するテストと同じ名前が付くので、ステップの引数とブロックからそのレシーバーを読める。
486
490
  カバレッジが数えるのはメソッドの呼び出しだけで、`new` と `setup` は数えない。
487
491
  対象ファイルが `initialize` を定義していれば、`mutate` と `random` はその引数から `new` も埋める。
488
492
  `--entry ENTRY` は位置引数の代わりになる。
@@ -536,7 +540,7 @@ ruby bin/branchout baselines examples/magic_value.rb MagicValue.classify \
536
540
  エントリは配列だけでもよい。
537
541
  キーワードは `kwargs` に、コンストラクタ引数は `new` に、レシーバーの状態を作る呼び出しは `setup` に書く。
538
542
  保存済みのレコードのように `new` では作れないレシーバーは、`receiver` に Ruby で書く(`{"receiver": {"ruby": "Factories.loan(3)"}, "args": [{"ruby": "loan.amount"}]}`)。
539
- レシーバーには、出力するテストと同じ名前(クラス名のスネークケース)が付くので、引数と `setup` からそのレシーバーを読める。
543
+ レシーバーには、出力するテストと同じ名前(クラス名のスネークケース)が付くので、引数、`setup`、`block` からそのレシーバーを読める。
540
544
  `before` の Ruby は、レシーバーと引数より前に、その入力のセーブポイントの中で動き、クラスメソッドが探す行のようにメソッドが読むものを作る(`{"before": {"ruby": "FactoryBot.create(:part, sku: \"A\")"}, "args": ["A"]}`)。
541
545
  RSpec はそれを入力の context の `before` として書き、minitest は呼び出しの前の行として書く。どちらも各行を字下げする。
542
546
  ただし `<<` と `<<-` のヒアドキュメントの本文と終端は元の桁のまま書くので、ヒアドキュメントは終わり、その文字列も変わらない。
@@ -545,12 +549,15 @@ RSpec はそれを入力の context の `before` として書き、minitest は
545
549
  そうする `before` も同じように名前を付ける(`after FactoryBot.create(:part).tap { |p| p.update!(size: 1) }`)。
546
550
  呼び出しで名前を付ける `before` の名前が 80 文字を超えるときは、兄弟のそれぞれと見分けられる最少のキーワードとブロックだけを残す(`after FactoryBot.create(:part) with code: "B"`)。
547
551
  それでも 80 文字を超える文の中の 30 文字を超えるブロックは、兄弟のブロックと分かれる所で切る(`when fact.tap { ...long piece', 2]) }`)。
548
- `new`、`receiver`、`setup`、`kwargs`、`block`、`before` のどれかがあるエントリは、位置引数のない呼び出しなら `args` を省ける(`{"receiver": {"ruby": "FactoryBot.build(:user)"}}`)。
552
+ `new`、`receiver`、`setup`、`kwargs`、`block`、`before`、`after` のどれかがあるエントリは、位置引数のない呼び出しなら `args` を省ける(`{"receiver": {"ruby": "FactoryBot.build(:user)"}}`)。
549
553
  型推論が違うときは、`"types"` に位置引数 1 つにつき `int`、`float`、`string`、`array`、`hash`、`bool` のいずれかを置く。
550
554
  既定値が `[]`、`{}`、`true`、`false` の引数はその型になる。
551
555
  `bool` の引数には、変異とランダムサンプリングが `false` と `true` の両方を試す。
552
556
  `meta` のような他のトップレベルキーは無視する。
553
- 各エントリの `note` も無視するので、その入力を選んだ理由をすぐ横に書ける。
557
+ 各エントリの `note` には、その入力を選んだ理由をすぐ横に書ける。
558
+ `note` は呼び出しには加わらず、入力の名前になる。
559
+ `RETURNED` は長い入力を位置と `note` で示し(`inputs[9] (one save)`)、`--json` は入力に `note` を添え、minitest のテスト名は `note` の語から作り(`test_one_save_returns_array_of_1`)、RSpec の例は結果のあとに `note` を括弧で書く(`returns 1 (one save)`)。
560
+ ラテン文字も数字もない `note` からは名前の語ができないので、minitest はその入力を値で名づける。
554
561
  エントリの `pin_keys`(`{"args": [3], "pin_keys": ["tax"]}`)は、その入力のテストに限って `--pin-keys` の代わりになる。
555
562
  `"pin_keys": []` は、その Hash を丸ごと固定する。
556
563
  レコードや例外のように JSON で書けない値は、`{"ruby": "..."}` に Ruby で書く。
@@ -571,6 +578,90 @@ RSpec はそれを入力の context の `before` として書き、minitest は
571
578
  エントリは末尾へ足す。
572
579
  消したり並べ替えたりしない。
573
580
 
581
+ 状態を変えるメソッドでは、戻り値はそのメソッドがすることの半分でしかない。
582
+ 残りの半分は `after` で読む。
583
+ `after` は Ruby の式 1 つで、呼び出しが値を返したあとにも例外を出したあとにも、その入力のスコープで動く。
584
+ そのため、出力するテストがレシーバーに付ける名前でレシーバーを読める。
585
+ エントリに書くか、ファイルの先頭に書いてすべての入力に使う。
586
+ エントリ自身の `after` はファイルのものに代わり、`mutate` と `random` が作る入力もファイルのものを使う。
587
+ スイートの中では、その入力のセーブポイントを巻き戻す前に動く。
588
+ quint_driver のチェックアウトで、次のファイルは `QuintDriver::Hold#start` を探索する。
589
+ このメソッドはブロックを一時停止まで動かし、それまでその名前を保持する。
590
+
591
+ ```json
592
+ {
593
+ "after": {"ruby": "hold.held"},
594
+ "inputs": [
595
+ {"note": "pauses", "args": ["r1"], "block": "{ hold.pause(:read); :written }"},
596
+ {"note": "ends without a pause", "args": ["r1"], "block": "{ :written }"},
597
+ {"note": "raises before a pause", "args": ["r1"], "block": "{ raise \"boom\" }"},
598
+ {"note": "name already held", "args": ["r1"], "block": "{ :again }",
599
+ "setup": [{"method": "start", "args": ["r1"], "block": "{ hold.pause(:read) }"}]}
600
+ ]
601
+ }
602
+ ```
603
+
604
+ ```sh
605
+ branchout explore lib/quint_driver/hold.rb 'QuintDriver::Hold#start' --inputs hold.json \
606
+ --strategy inputs --random 0 --seed 1 --emit-tests test/hold_start_test.rb
607
+ ```
608
+
609
+ ```
610
+ branchout explore lib/quint_driver/hold.rb QuintDriver::Hold#start
611
+ covered: 5 of 6 arms by 4 inputs
612
+ raised: 2 inputs
613
+ tests: test/hold_start_test.rb
614
+
615
+ FRONTIER (add an input like the nearest above each arm, changed as the arm says)
616
+ nearest: {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ :written }"}
617
+ lib/quint_driver/hold.rb:71:10 makes `%i[paused done].include?(kind) && answer.is_a?(Array)` false
618
+
619
+ RETURNED (coverage does not check a value; compare each with what the method should return)
620
+ returns :written for inputs[1] (ends without a pause)
621
+ returns :read for inputs[0] (pauses)
622
+
623
+ EXCEPTIONS
624
+ ArgumentError at lib/quint_driver/hold.rb:32 raised by {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ :again }","setup":[{"args":["r1"],"block":"{ hold.pause(:read) }","method":"start"}]}: quint: "r1" is already held; finish it first
625
+ RuntimeError at lib/quint_driver/hold.rb:34 raised by {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ raise \"boom\" }"}: boom
626
+
627
+ AFTER (what each after read once its call returned or raised; compare each with the state the call should leave)
628
+ hold.held is ["r1"] for inputs[3] (name already held), inputs[0] (pauses)
629
+ hold.held is [] for inputs[1] (ends without a pause), inputs[2] (raises before a pause)
630
+
631
+ OPERATORS (coverage does not see which side ran; vary each left side)
632
+ lib/quint_driver/hold.rb:70:46 && in `%i[paused done].include?(kind) && answer.is_a?(Array)`
633
+
634
+ Pass --verbose for every covered arm and the run settings.
635
+ ```
636
+
637
+ 出力するテストは、`after` が読んだものを値と同じように、値か例外のあとで固定する。
638
+ 例外を出した呼び出しでは、レシーバーを `assert_raises` の前に作るので、`after` がそれを読める。
639
+
640
+ ```ruby
641
+ def test_raises_before_a_pause_raises_runtime_error
642
+ # covers:
643
+ # line 32: if held?(name) -> else
644
+ hold = QuintDriver::Hold.new
645
+ error = assert_raises(RuntimeError) do
646
+ hold.start("r1") { raise "boom" }
647
+ end
648
+ assert_equal "boom", error.message
649
+ assert_equal [], hold.held
650
+ end
651
+ ```
652
+
653
+ RSpec は、`expect { hold.start("r1") { raise "boom" } }.to raise_error(RuntimeError, "boom")` のあとに、呼び出しが動いた `let` について `expect(hold.held).to eq([])` を書く。
654
+ `Hold#run` の中で名前を解放する `rescue` を消しても、`start` は同じ `boom` の `RuntimeError` を出し、`after` だけが失敗する(`Expected: []`、`Actual: ["r1"]`)。
655
+ `after` が実行ごとに新しく読む値は固定しない。
656
+ Hash は 2 回の実行で同じだったキーだけを残し、標準エラーがそれぞれを示す。
657
+ これは戻り値と同じである。
658
+ その中のパスは、戻り値のパスと同じように書く。
659
+ 複数の値は 1 つの Array か Hash として読む(`[cart.items, cart.total]`)。
660
+ 後置の `if` や 2 つの文は受け付けない。
661
+ 例外を出す `after` は探索を止め、その入力を示す。
662
+ `new` か setup の呼び出しが例外を出したときは、状態を残した呼び出しがないので、`AFTER` はその入力について `read nothing` と示し、テストはこれまでどおりその例外を固定する。
663
+ `--json` は読んだ値ごとに `after` の下に `after`、`is`、`value`、`inputs` を持つ。
664
+
574
665
  ```sh
575
666
  ruby bin/branchout explore examples/hidden_bug.rb HiddenBug.scale \
576
667
  --inputs examples/inputs/hidden_bug.json \
@@ -590,6 +681,8 @@ Ruby 3.4 でメッセージの文言が変わったためである。
590
681
  バックトレースのフレーム(`lib/x.rb:3:in 'Box.run'`)を含むメッセージは正規表現で照合し、フレームのラベルだけはどちらの書式でも通す。
591
682
  Ruby 3.4 はラベルを `` `run' `` から `'Box.run'` に変えたためである。
592
683
  `raised in:` の行のように、フレームを含む String の戻り値も同じように照合する。
684
+ ファイル記述子を含む Errno のメッセージ(`Is a directory @ io_fillbuf - fd:5 ...`)も正規表現で照合し、記述子の番号はどれでも通す。
685
+ 番号は、それまでにプロセスが開いたファイルで変わるためである。
593
686
  `Set` は要素で固定し(`Set[1, 2]`)、`Date` は値で固定する(`Date.new(2026, 4, 1)`)。
594
687
  メンバーがすべてリテラルで書ける `Struct` と `Data` は、クラスとメンバーの値で固定する(`eq(Rule.new(action: "borrow", on: Date.new(2026, 4, 1)))`)。
595
688
  `==` がメンバーを比べるためである。
@@ -806,6 +899,9 @@ C で書かれたメソッド、Ruby 自身の prelude のメソッド、属性
806
899
  1 つのオブジェクトへの呼び出しをまたいでメモ化するもので、各入力はレシーバーを新しく作るため、どの入力も左辺を変えられないからである。
807
900
  入口に腕がなく、そうした演算子があるときは、stderr がそう伝える。
808
901
  分岐がそのメモ化だけのときは、stderr がそのメモ化を挙げ、右辺が呼ぶメソッドを探索し、メモ化は 1 つのオブジェクトへの 2 回の呼び出しで手で確かめるよう伝える。
902
+ `defined?(@ivar)` によるメモ化(`return @value if defined?(@value)`)には、カバレッジが数える腕がある。
903
+ `setup` でそのメソッドを呼ぶ入力はキャッシュ側の腕を通るが、その腕は 1 回目の呼び出しが保存した値を返すので、固定した値はメモ化がなくても同じになる。
904
+ stderr はそうしたメモ化を 1 つずつ挙げ、同じように手で確かめるよう伝える。
809
905
  比較の `<`、`<=`、`>`、`>=` も、カバレッジにはどちらの辺も見えない。
810
906
  そのため、両辺を等しくする入力がなくてもすべての腕を通れるが、`>` を `>=` に変えた変異はその入力でしか見つからない。
811
907
  `BOUNDARIES` は数えたコードの比較を 1 つずつ挙げ、`boundaries_not_counted` がその数を示す。
data/README.md CHANGED
@@ -226,7 +226,7 @@ shipping.rb:5:18 <= in `weight <= 2`
226
226
  Pass --verbose for every covered arm and the run settings.
227
227
  ```
228
228
 
229
- branchout ran 13 inputs that it made from the method's own literals and from a seeded sample. They took 5 of the 6 arms. `FRONTIER` is the arm that no input took: `express` was never true, so add an input like `nearest` that makes it true. `RETURNED` shows what each input returned, grouped by value: coverage counts the arms an input took and never checks a value, so read each line against what the method should return. A value longer than a line shows the Hash leaves that tell it from the other values first, then the rest of its top-level scalars that fit (`returns a Hash with due_cents: 900, discount: 10, discount_cents: 100, ...`), and an input from the inputs file longer than a line shows its place there (`inputs[3]`). `--json` gives each whole value as a Ruby literal (`value`) and each whole input. `EXCEPTIONS` gives one line for each error and the place that raised it, with how many inputs raised it and one of them. `--verbose` also prints the input that took each covered arm.
229
+ branchout ran 13 inputs that it made from the method's own literals and from a seeded sample. They took 5 of the 6 arms. `FRONTIER` is the arm that no input took: `express` was never true, so add an input like `nearest` that makes it true. `RETURNED` shows what each input returned, grouped by value: coverage counts the arms an input took and never checks a value, so read each line against what the method should return. A value longer than a line shows the Hash leaves that tell it from the other values first, then the rest of its top-level scalars that fit (`returns a Hash with due_cents: 900, discount: 10, discount_cents: 100, ...`). An Array, a Struct, or a Data shows its size or class, then the leaves that tell it from the other values of that size or class (`returns an Array of 2 with [1].kind: "skips-callbacks", [0].line: 2, ...`), and an input from the inputs file longer than a line shows its place there (`inputs[3]`). `--json` gives each whole value as a Ruby literal (`value`) and each whole input. A path under the temporary or the home directory shows as `<tmp>/` or `<home>/` with `.../` for its directories (`"No hit under <tmp>/.../app."`), in `value` too, so the report is the same on every machine. `EXCEPTIONS` gives one line for each error and the place that raised it, with how many inputs raised it and one of them. `--verbose` also prints the input that took each covered arm.
230
230
 
231
231
  The emitted spec pins each return value and each error:
232
232
 
@@ -237,7 +237,7 @@ cat shipping_spec.rb
237
237
  ```ruby
238
238
  # frozen_string_literal: true
239
239
 
240
- # Generated by branchout 0.1.0. Characterization specs for discovered inputs.
240
+ # Generated by branchout 0.2.0. Characterization specs for discovered inputs.
241
241
  # target: shipping.rb
242
242
  # entry: Shipping.fee
243
243
 
@@ -350,7 +350,7 @@ A coding agent adding tests can see that a branch was missed and still not know
350
350
 
351
351
  The method follows concolic testing ([DART](https://doi.org/10.1145/1065010.1065036), [CUTE](https://doi.org/10.1145/1094811.1094816)) and LLM-guided concolic work such as [ConcoLLMic](https://concollmic.github.io/). branchout is inspired by concolic testing but does no symbolic solving. The agent proposes inputs from the branch frontier.
352
352
 
353
- From a checkout of this repository, `ruby bin/branchout` runs the same command as `branchout`. The seed file holds one input, `[0]`. `--verbose` prints the whole report: the run settings of the strategies that ran and the counts, then `COVERED` (the input that took each arm), `FRONTIER` (each arm no input took, with `path`, the arms `nearest` took), `RETURNED` (each value and the inputs that returned it), `EXCEPTIONS` (one record for each input that raised), `NOT COUNTED`, `OPERATORS`, and `BOUNDARIES`. Without it, the report keeps the counts, the `FRONTIER` arms that an input reached, one line each under the `nearest` input to change, one line for each decision that no input reached, one line for each returned value, and one line for each error and the place that raised it, as in [Try it without an app](#try-it-without-an-app). `--json` holds every field of the whole report.
353
+ From a checkout of this repository, `ruby bin/branchout` runs the same command as `branchout`. The seed file holds one input, `[0]`. `--verbose` prints the whole report: the run settings of the strategies that ran and the counts, then `COVERED` (the input that took each arm), `FRONTIER` (each arm no input took, with `path`, the arms `nearest` took), `RETURNED` (each value and the inputs that returned it), `EXCEPTIONS` (one record for each input that raised), `AFTER` when an input has an `after` (each value it read and the inputs that read it), `NOT COUNTED`, `OPERATORS`, and `BOUNDARIES`. Without it, the report keeps the counts, the `FRONTIER` arms that an input reached, one line each under the `nearest` input to change, one line for each decision that no input reached, one line for each returned value, and one line for each error and the place that raised it, as in [Try it without an app](#try-it-without-an-app). `--json` holds every field of the whole report.
354
354
 
355
355
  ```sh
356
356
  ruby bin/branchout explore examples/magic_value.rb MagicValue.classify \
@@ -411,7 +411,7 @@ BOUNDARIES
411
411
 
412
412
  `sense: cond-true` on `x == 114514` is the arm `[0]` did not take. Append `[114514]` and rerun the same command. `examples/inputs/magic_value.json` is that file. It reports `arms_covered: 2` and `FRONTIER` `(none)`.
413
413
 
414
- `ENTRY` is `Const.method` or `Const#method`. A method under `module_function` or in a module that calls `extend self` is `Const.method`. For `Const#method`, each input gets its own receiver from `Const.new`. If `initialize` takes arguments, put them in `new` on each input, in the same shape as an input: `{"args": [5], "new": [10]}` calls `Const.new(10).method(5)`. A `new` of keywords only may leave out `args`: `{"args": [5], "new": {"kwargs": {"main": 1}}}` calls `Const.new(main: 1).method(5)`. When the state the method reads comes from calls after `new`, list them in `setup`, in order: `{"args": [], "setup": [{"method": "add", "args": ["apple", 3]}]}` calls `add("apple", 3)` on the new receiver and then the method. Each step takes `method`, `args`, and `kwargs`. Coverage counts only the call to the method, not `new` or `setup`. When the target file defines `initialize`, `mutate` and `random` fill `new` from its parameters too. `--entry ENTRY` may replace the positional entry.
414
+ `ENTRY` is `Const.method` or `Const#method`. A method under `module_function` or in a module that calls `extend self` is `Const.method`. For `Const#method`, each input gets its own receiver from `Const.new`. If `initialize` takes arguments, put them in `new` on each input, in the same shape as an input: `{"args": [5], "new": [10]}` calls `Const.new(10).method(5)`. A `new` of keywords only may leave out `args`: `{"args": [5], "new": {"kwargs": {"main": 1}}}` calls `Const.new(main: 1).method(5)`. When the state the method reads comes from calls after `new`, list them in `setup`, in order: `{"args": [], "setup": [{"method": "add", "args": ["apple", 3]}]}` calls `add("apple", 3)` on the new receiver and then the method. A step takes `method`, `args`, `kwargs`, and `block` (`{"method": "start", "args": ["r1"], "block": "{ hold.pause(:read); :end }"}`), and with setup steps the receiver takes the name the emitted test gives it, so a step's arguments and block can read it. Each step takes `method`, `args`, and `kwargs`. Coverage counts only the call to the method, not `new` or `setup`. When the target file defines `initialize`, `mutate` and `random` fill `new` from its parameters too. `--entry ENTRY` may replace the positional entry.
415
415
 
416
416
  While searching, pass `--strategy inputs --random 0` and keep `--seed` fixed, so a new covered arm comes from an input you added. The search procedure is in [skills/branchout/SKILL.md](skills/branchout/SKILL.md).
417
417
 
@@ -459,7 +459,72 @@ An inputs file starts as one seed:
459
459
  }
460
460
  ```
461
461
 
462
- An entry may be a bare array. Keywords go in `kwargs`, constructor arguments go in `new`, and calls that build the receiver's state go in `setup`. A receiver that `new` cannot build, such as a saved record, is Ruby in `receiver`: `{"receiver": {"ruby": "Factories.loan(3)"}, "args": [{"ruby": "loan.amount"}]}`. The receiver takes the name the emitted test gives it, the class in snake case, so the arguments and `setup` can read from it. Ruby in `before` runs before the receiver and the arguments, in the input's own savepoint, and makes what the method reads, such as the rows a class method looks up: `{"before": {"ruby": "FactoryBot.create(:part, sku: \"A\")"}, "args": ["A"]}`. RSpec writes it as the `before` of the input's context, and minitest as the line before the call, each line of it indented except the body and the terminator of a `<<` or `<<-` heredoc, which keep their columns so that the heredoc ends and its text stays the same. A `before` of several lines is named by the lines that differ from its siblings', a call by its keywords that differ (`after FactoryBot.create(:membership) with enabled: false`). A Ruby argument that runs a block through `tap` or `then` is named by its block when its siblings differ there (`when fact.tap { Parts.rows.replace(["A"]) }`), and so is a `before` that does (`after FactoryBot.create(:part).tap { |p| p.update!(size: 1) }`). A `before` named by a call whose label would pass 80 characters keeps the fewest of its keywords and its block that tell it from each sibling (`after FactoryBot.create(:part) with code: "B"`). A block over 30 characters in a text that would still pass 80 is cut where it parts from its siblings' blocks (`when fact.tap { ...long piece', 2]) }`). An entry with `new`, `receiver`, `setup`, `kwargs`, `block`, or `before` may leave out `args` for a call with no positional argument: `{"receiver": {"ruby": "FactoryBot.build(:user)"}}`. If type inference is wrong, set `"types"` to one of `int`, `float`, `string`, `array`, `hash`, or `bool` per positional parameter. A default value of `[]`, `{}`, `true`, or `false` gives its type, and `bool` makes mutation and random sampling try both `false` and `true`. Other top-level keys, such as `meta`, are ignored, and so is a `note` on an entry, which keeps the reason for that input beside it. An entry's `pin_keys` (`{"args": [3], "pin_keys": ["tax"]}`) replaces `--pin-keys` for that input's test, and `"pin_keys": []` pins its Hash whole. A value JSON cannot write, such as a record or an exception, is Ruby in `{"ruby": "..."}`, often a factory in a `--require` file: `{"args": [{"ruby": "Factories.loan(3)"}]}`. Each call evaluates it again at the top level, and the emitted tests write it as given (`Lending.approve(Factories.loan(3))`). A block the method takes goes in `block`, with braces: `{"args": [5], "block": "{ |amount| amount > 2 }"}`. A Hash argument whose one key is `"ruby"` is written as Ruby too: `{"ruby": "{\"ruby\" => \"3.4\"}"}`. A String that names a path under the emitted test's project (the nearest directory above the test with a `Gemfile`, a gemspec, or `.git`) is written from the test's own directory, `File.expand_path("../fixtures/files/rates.csv", __dir__)`, so the test passes in any checkout of the project, a jitcatch copy too. Its name and description say the path from the project root (`spec/fixtures/files/rates.csv`). A path under the temporary or the home directory and outside the project stays as written, and stderr names it: one that exists, since the test passes only on this machine, and one that does not, since the test still holds this machine's directories. Put such a path under the project, for example in `spec/fixtures/files`. A returned value or an error message that holds a path under the project names the project root from the test's own directory too (`"No such file or directory @ rb_sysopen - #{File.expand_path("..", __dir__)}/spec/fixtures/none.csv"`). One that holds a path of this machine outside the project stays as written, and stderr names it. A test name or description says a path under the temporary or the home directory by its file alone, so it is the same on every machine. Append entries. Do not delete or reorder them.
462
+ An entry may be a bare array. Keywords go in `kwargs`, constructor arguments go in `new`, and calls that build the receiver's state go in `setup`. A receiver that `new` cannot build, such as a saved record, is Ruby in `receiver`: `{"receiver": {"ruby": "Factories.loan(3)"}, "args": [{"ruby": "loan.amount"}]}`. The receiver takes the name the emitted test gives it, the class in snake case, so the arguments, `setup`, and `block` can read from it. Ruby in `before` runs before the receiver and the arguments, in the input's own savepoint, and makes what the method reads, such as the rows a class method looks up: `{"before": {"ruby": "FactoryBot.create(:part, sku: \"A\")"}, "args": ["A"]}`. RSpec writes it as the `before` of the input's context, and minitest as the line before the call, each line of it indented except the body and the terminator of a `<<` or `<<-` heredoc, which keep their columns so that the heredoc ends and its text stays the same. A `before` of several lines is named by the lines that differ from its siblings', a call by its keywords that differ (`after FactoryBot.create(:membership) with enabled: false`). A Ruby argument that runs a block through `tap` or `then` is named by its block when its siblings differ there (`when fact.tap { Parts.rows.replace(["A"]) }`), and so is a `before` that does (`after FactoryBot.create(:part).tap { |p| p.update!(size: 1) }`). A `before` named by a call whose label would pass 80 characters keeps the fewest of its keywords and its block that tell it from each sibling (`after FactoryBot.create(:part) with code: "B"`). A block over 30 characters in a text that would still pass 80 is cut where it parts from its siblings' blocks (`when fact.tap { ...long piece', 2]) }`). An entry with `new`, `receiver`, `setup`, `kwargs`, `block`, `before`, or `after` may leave out `args` for a call with no positional argument: `{"receiver": {"ruby": "FactoryBot.build(:user)"}}`. If type inference is wrong, set `"types"` to one of `int`, `float`, `string`, `array`, `hash`, or `bool` per positional parameter. A default value of `[]`, `{}`, `true`, or `false` gives its type, and `bool` makes mutation and random sampling try both `false` and `true`. Other top-level keys, such as `meta`, are ignored. A `note` on an entry keeps the reason for that input beside it and takes no part in the call; it names the input: `RETURNED` shows a long input by its place and its note (`inputs[9] (one save)`), `--json` keeps it on the input, a minitest name is made from its words (`test_one_save_returns_array_of_1`), and an RSpec example says it after the outcome (`returns 1 (one save)`). A note with no Latin letter or digit gives a minitest name no words, so that input is named by its values. An entry's `pin_keys` (`{"args": [3], "pin_keys": ["tax"]}`) replaces `--pin-keys` for that input's test, and `"pin_keys": []` pins its Hash whole. A value JSON cannot write, such as a record or an exception, is Ruby in `{"ruby": "..."}`, often a factory in a `--require` file: `{"args": [{"ruby": "Factories.loan(3)"}]}`. Each call evaluates it again at the top level, and the emitted tests write it as given (`Lending.approve(Factories.loan(3))`). A block the method takes goes in `block`, with braces: `{"args": [5], "block": "{ |amount| amount > 2 }"}`. A Hash argument whose one key is `"ruby"` is written as Ruby too: `{"ruby": "{\"ruby\" => \"3.4\"}"}`. A String that names a path under the emitted test's project (the nearest directory above the test with a `Gemfile`, a gemspec, or `.git`) is written from the test's own directory, `File.expand_path("../fixtures/files/rates.csv", __dir__)`, so the test passes in any checkout of the project, a jitcatch copy too. Its name and description say the path from the project root (`spec/fixtures/files/rates.csv`). A path under the temporary or the home directory and outside the project stays as written, and stderr names it: one that exists, since the test passes only on this machine, and one that does not, since the test still holds this machine's directories. Put such a path under the project, for example in `spec/fixtures/files`. A returned value or an error message that holds a path under the project names the project root from the test's own directory too (`"No such file or directory @ rb_sysopen - #{File.expand_path("..", __dir__)}/spec/fixtures/none.csv"`). One that holds a path of this machine outside the project stays as written, and stderr names it. A test name or description says a path under the temporary or the home directory by its file alone, so it is the same on every machine. Append entries. Do not delete or reorder them.
463
+
464
+ For a method that changes state, the value is half of what it does. `after` reads the other half: one Ruby expression that runs once the call returned or raised, in the input's scope, so it reads the receiver by the name the emitted test gives it. It goes on an entry, or at the top of the file for every input, where an entry's own `after` replaces it and the inputs that `mutate` and `random` make take it too. Inside a suite it runs before the input's savepoint is rolled back. In a checkout of quint_driver, this file explores `QuintDriver::Hold#start`, which runs a block until the block pauses and holds its name until then:
465
+
466
+ ```json
467
+ {
468
+ "after": {"ruby": "hold.held"},
469
+ "inputs": [
470
+ {"note": "pauses", "args": ["r1"], "block": "{ hold.pause(:read); :written }"},
471
+ {"note": "ends without a pause", "args": ["r1"], "block": "{ :written }"},
472
+ {"note": "raises before a pause", "args": ["r1"], "block": "{ raise \"boom\" }"},
473
+ {"note": "name already held", "args": ["r1"], "block": "{ :again }",
474
+ "setup": [{"method": "start", "args": ["r1"], "block": "{ hold.pause(:read) }"}]}
475
+ ]
476
+ }
477
+ ```
478
+
479
+ ```sh
480
+ branchout explore lib/quint_driver/hold.rb 'QuintDriver::Hold#start' --inputs hold.json \
481
+ --strategy inputs --random 0 --seed 1 --emit-tests test/hold_start_test.rb
482
+ ```
483
+
484
+ ```
485
+ branchout explore lib/quint_driver/hold.rb QuintDriver::Hold#start
486
+ covered: 5 of 6 arms by 4 inputs
487
+ raised: 2 inputs
488
+ tests: test/hold_start_test.rb
489
+
490
+ FRONTIER (add an input like the nearest above each arm, changed as the arm says)
491
+ nearest: {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ :written }"}
492
+ lib/quint_driver/hold.rb:71:10 makes `%i[paused done].include?(kind) && answer.is_a?(Array)` false
493
+
494
+ RETURNED (coverage does not check a value; compare each with what the method should return)
495
+ returns :written for inputs[1] (ends without a pause)
496
+ returns :read for inputs[0] (pauses)
497
+
498
+ EXCEPTIONS
499
+ ArgumentError at lib/quint_driver/hold.rb:32 raised by {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ :again }","setup":[{"args":["r1"],"block":"{ hold.pause(:read) }","method":"start"}]}: quint: "r1" is already held; finish it first
500
+ RuntimeError at lib/quint_driver/hold.rb:34 raised by {"after":{"ruby":"hold.held"},"args":["r1"],"block":"{ raise \"boom\" }"}: boom
501
+
502
+ AFTER (what each after read once its call returned or raised; compare each with the state the call should leave)
503
+ hold.held is ["r1"] for inputs[3] (name already held), inputs[0] (pauses)
504
+ hold.held is [] for inputs[1] (ends without a pause), inputs[2] (raises before a pause)
505
+
506
+ OPERATORS (coverage does not see which side ran; vary each left side)
507
+ lib/quint_driver/hold.rb:70:46 && in `%i[paused done].include?(kind) && answer.is_a?(Array)`
508
+
509
+ Pass --verbose for every covered arm and the run settings.
510
+ ```
511
+
512
+ The emitted test pins what the after read as it pins a value, after the value or the error. For a call that raised, the receiver is built before `assert_raises`, so the after can read it:
513
+
514
+ ```ruby
515
+ def test_raises_before_a_pause_raises_runtime_error
516
+ # covers:
517
+ # line 32: if held?(name) -> else
518
+ hold = QuintDriver::Hold.new
519
+ error = assert_raises(RuntimeError) do
520
+ hold.start("r1") { raise "boom" }
521
+ end
522
+ assert_equal "boom", error.message
523
+ assert_equal [], hold.held
524
+ end
525
+ ```
526
+
527
+ RSpec writes `expect(hold.held).to eq([])` after `expect { hold.start("r1") { raise "boom" } }.to raise_error(RuntimeError, "boom")`, on the `let` the call ran on. Without the `rescue` in `Hold#run` that frees the name, `start` still raises `RuntimeError` with `boom`, and only the after fails: `Expected: []`, `Actual: ["r1"]`. A value an after reads anew on each run is not pinned, a Hash keeps the keys that were the same on both runs, and stderr names each, as for a returned value. A path in it is written as a returned path is. Read several values as one Array or Hash (`[cart.items, cart.total]`); a modifier `if` or two statements are refused. An after that raises stops explore and names the input. When `new` or a setup call raised, no call left a state, so `AFTER` says `read nothing` for that input and its test pins the error as before. `--json` lists each value under `after`, with `after`, `is`, `value`, and `inputs`.
463
528
 
464
529
  ```sh
465
530
  ruby bin/branchout explore examples/hidden_bug.rb HiddenBug.scale \
@@ -469,7 +534,7 @@ ruby bin/branchout explore examples/hidden_bug.rb HiddenBug.scale \
469
534
  --format rspec
470
535
  ```
471
536
 
472
- That run covers 4 of 4 arms and records `ZeroDivisionError` (`divided by 0`) for `[24,12]`. The emitted file pins each return value, or the exception class and message, a message over several lines as it was raised. Each test starts with a `# covers:` list of the arms its input took, one per line, as the condition's line, the condition as written, and the arm (`line 20: unless rate.is_a?(Numeric) -> else`, `line 9: elsif tag.start_with?("beta") -> then`). A ternary is written whole (`line 10: label ? :noted : :plain -> then`), and a `case` arm sits on its own `when`, `in`, or `else` line, which names it (`line 6: when 1, 2 then :low`). A `NameError` or `NoMethodError` is pinned by its class and missing name (`error.name`), because Ruby 3.4 reworded their messages. A message that quotes a backtrace frame (`lib/x.rb:3:in 'Box.run'`) is matched by a Regexp that accepts the frame's label in either form, because Ruby 3.4 changed labels from `` `run' `` to `'Box.run'`. So is a returned String that quotes one, such as a `raised in:` line. A `Set` is pinned by its members (`Set[1, 2]`), and a `Date` by its value (`Date.new(2026, 4, 1)`). A `Struct` or `Data` whose members all have a literal is pinned by its class and members (`eq(Rule.new(action: "borrow", on: Date.new(2026, 4, 1)))`), since `==` compares the members; one whose own `initialize` makes another value from those members is not. A return value with no Ruby literal, such as an `Object`, a `Time`, or a record, is pinned by its class only. In RSpec a `Struct` or `Data` that holds such a value is pinned by its class and members, and an Array or Hash that holds one item by item (`match([a_kind_of(Rule).and(have_attributes(action: "borrow", at: a_kind_of(Time)))])`); minitest checks the same parts: each part with no literal by its class (`assert_kind_of Time, value[0].at`), a `Struct` or `Data` by its class and members, and an Array or Hash by comparing it with a literal that reads those parts back from the value (`assert_equal([value[0]], value)`), so a missing key or item fails too. A Hash with a key that has no literal is pinned by its class in both formats. An expected Hash keeps the value's own key order, so a failure diff lines up key by key. A private or protected entry, and a private `new`, are called through `send`, as `explore` called them. A String argument is a plain literal, which the file's `frozen_string_literal` freezes, and `explore` passes it frozen as well. An input that raises `FrozenError` with frozen Strings, and not with unfrozen ones, keeps the unfrozen run: its test writes each String as `+"..."` under a comment that says so. That run came second, so it saw what the first run changed before it raised: a savepoint undoes rows, but no run undoes a global, a class variable, or a file. The comment says this too. Run the emitted test on its own to check that value. A class or module that `private_constant` hides is reached through `const_get` (`Shop.const_get(:Ledger)`), and the RSpec describe names it as a string. A minitest test is named after its input and outcome, such as `test_24_12_raises_zero_division_error`. Inputs whose names would be the same are named by the values that differ between them, such as `test_status_timeout_and_error_class_timeout_returns_ok`, so adding an input can rename those. Strings that share their start are named from the words where they part. Ruby source that shares its start, such as two factory calls in `receiver`, keeps the word before they part (`test_limit_100_returns_ok`). A name is cut between words, a blank string shows as `blank`, an empty Array or Hash argument as `empty_array` or `empty_hash`, and a Hash argument is named by its values. A collection in a Hash argument is named by its key and size (`groups_3`, `tags_empty`), and an Array of collections by its size (`array_of_2`). An Array that holds scalars and collections says `array`, then each scalar and the keys of each Hash (`returns [:ok, a Hash of id, name]`, `returns_array_ok_hash_id_and_name`), so `["Done", []]` is not named as the String `"Done"` (`returns_array_done_empty_array`). A number of more than 15 digits is named by its first three digits and its power of ten (`123e46`). A key that ends another leaf's path too keeps the keys above it (`items_id` beside `id`). A Hash outcome is named by the fewest leaves, nested ones too, that tell its siblings apart (`returns_due_cents_0_and_discount_100`), the same leaves in both formats, or by its keys when it has no sibling (`returns_hash_lines_and_discount_cents`). A Hash or an Array that holds a part with no literal, as one that `--pin-keys` or a varying id leaves may, is named in both formats by its parts that have one: the leaves that tell its siblings apart (`returns_due_cents_100`, RSpec `returns due_cents: 100`), else its keys (`returns_hash_name_and_start_at`, RSpec `returns a Hash of name, start_at, end_at`) or its size (`returns_array_of_2`, RSpec `returns an Array of 2`). Each key after the first comes after `and`, and a cut never splits a key. An Array of scalars says `array` (`[nil]` is `returns_array_nil`), and a String or a Symbol that reads as `nil`, `true`, or `false` says `text` (`returns_text_nil`). A Hash key that reads so says `key` (`returns_key_nil_0` for `{"NIL" => 0}`). A test emitted outside the target's directory tree requires the target by absolute path, unless `--require-by-name` is given and an `-I` or `--require` directory holds it. When a test requires a file by its path from out of its own project (the nearest directory with a `Gemfile`, a gemspec, or `.git`), by absolute path or by a climb into another project, stderr warns that the test runs only where that file sits on this machine, and names the fix. A target that a `--require` file already loads gets no require of its own.
537
+ That run covers 4 of 4 arms and records `ZeroDivisionError` (`divided by 0`) for `[24,12]`. The emitted file pins each return value, or the exception class and message, a message over several lines as it was raised. Each test starts with a `# covers:` list of the arms its input took, one per line, as the condition's line, the condition as written, and the arm (`line 20: unless rate.is_a?(Numeric) -> else`, `line 9: elsif tag.start_with?("beta") -> then`). A ternary is written whole (`line 10: label ? :noted : :plain -> then`), and a `case` arm sits on its own `when`, `in`, or `else` line, which names it (`line 6: when 1, 2 then :low`). A `NameError` or `NoMethodError` is pinned by its class and missing name (`error.name`), because Ruby 3.4 reworded their messages. A message that quotes a backtrace frame (`lib/x.rb:3:in 'Box.run'`) is matched by a Regexp that accepts the frame's label in either form, because Ruby 3.4 changed labels from `` `run' `` to `'Box.run'`. So is a returned String that quotes one, such as a `raised in:` line. An Errno message that names a file descriptor (`Is a directory @ io_fillbuf - fd:5 ...`) is matched by a Regexp that accepts any descriptor, because its number depends on what the process opened before. A `Set` is pinned by its members (`Set[1, 2]`), and a `Date` by its value (`Date.new(2026, 4, 1)`). A `Struct` or `Data` whose members all have a literal is pinned by its class and members (`eq(Rule.new(action: "borrow", on: Date.new(2026, 4, 1)))`), since `==` compares the members; one whose own `initialize` makes another value from those members is not. A return value with no Ruby literal, such as an `Object`, a `Time`, or a record, is pinned by its class only. In RSpec a `Struct` or `Data` that holds such a value is pinned by its class and members, and an Array or Hash that holds one item by item (`match([a_kind_of(Rule).and(have_attributes(action: "borrow", at: a_kind_of(Time)))])`); minitest checks the same parts: each part with no literal by its class (`assert_kind_of Time, value[0].at`), a `Struct` or `Data` by its class and members, and an Array or Hash by comparing it with a literal that reads those parts back from the value (`assert_equal([value[0]], value)`), so a missing key or item fails too. A Hash with a key that has no literal is pinned by its class in both formats. An expected Hash keeps the value's own key order, so a failure diff lines up key by key. A private or protected entry, and a private `new`, are called through `send`, as `explore` called them. A String argument is a plain literal, which the file's `frozen_string_literal` freezes, and `explore` passes it frozen as well. An input that raises `FrozenError` with frozen Strings, and not with unfrozen ones, keeps the unfrozen run: its test writes each String as `+"..."` under a comment that says so. That run came second, so it saw what the first run changed before it raised: a savepoint undoes rows, but no run undoes a global, a class variable, or a file. The comment says this too. Run the emitted test on its own to check that value. A class or module that `private_constant` hides is reached through `const_get` (`Shop.const_get(:Ledger)`), and the RSpec describe names it as a string. A minitest test is named after its input and outcome, such as `test_24_12_raises_zero_division_error`. Inputs whose names would be the same are named by the values that differ between them, such as `test_status_timeout_and_error_class_timeout_returns_ok`, so adding an input can rename those. Strings that share their start are named from the words where they part. Ruby source that shares its start, such as two factory calls in `receiver`, keeps the word before they part (`test_limit_100_returns_ok`). A name is cut between words, a blank string shows as `blank`, an empty Array or Hash argument as `empty_array` or `empty_hash`, and a Hash argument is named by its values. A collection in a Hash argument is named by its key and size (`groups_3`, `tags_empty`), and an Array of collections by its size (`array_of_2`). An Array that holds scalars and collections says `array`, then each scalar and the keys of each Hash (`returns [:ok, a Hash of id, name]`, `returns_array_ok_hash_id_and_name`), so `["Done", []]` is not named as the String `"Done"` (`returns_array_done_empty_array`). A number of more than 15 digits is named by its first three digits and its power of ten (`123e46`). A key that ends another leaf's path too keeps the keys above it (`items_id` beside `id`). A Hash outcome is named by the fewest leaves, nested ones too, that tell its siblings apart (`returns_due_cents_0_and_discount_100`), the same leaves in both formats, or by its keys when it has no sibling (`returns_hash_lines_and_discount_cents`). A Hash or an Array that holds a part with no literal, as one that `--pin-keys` or a varying id leaves may, is named in both formats by its parts that have one: the leaves that tell its siblings apart (`returns_due_cents_100`, RSpec `returns due_cents: 100`), else its keys (`returns_hash_name_and_start_at`, RSpec `returns a Hash of name, start_at, end_at`) or its size (`returns_array_of_2`, RSpec `returns an Array of 2`). Each key after the first comes after `and`, and a cut never splits a key. An Array of scalars says `array` (`[nil]` is `returns_array_nil`), and a String or a Symbol that reads as `nil`, `true`, or `false` says `text` (`returns_text_nil`). A Hash key that reads so says `key` (`returns_key_nil_0` for `{"NIL" => 0}`). A test emitted outside the target's directory tree requires the target by absolute path, unless `--require-by-name` is given and an `-I` or `--require` directory holds it. When a test requires a file by its path from out of its own project (the nearest directory with a `Gemfile`, a gemspec, or `.git`), by absolute path or by a climb into another project, stderr warns that the test runs only where that file sits on this machine, and names the fix. A target that a `--require` file already loads gets no require of its own.
473
538
 
474
539
  An RSpec file describes the constant, then `.method` or `#method`, and calls the class as `described_class`. It pins `true` and `false` with `be(true)` and `be(false)`, and `nil` with `be_nil`, and a Hash literal in either format has a space inside its braces (`{ total: 2 }`), as RuboCop and rubocop-rspec expect by default, so a file emitted again needs no autocorrect. The receiver is a `let`, each setup call a `before`, and inputs that start with the same receiver, calls, or argument values share a `context`. A receiver whose `new` differs from a sibling's only at some keywords is named by those keywords (`context "with start_at: Date.new(2026, 5, 1)"`), and `new` takes its keywords in the input's order. An example says its outcome first, then the argument values of its own, so `rspec --format documentation` reads like a spec. A value inside an argument is named by its path, and an Array of scalars as a whole (`items is [1, 2]`). A path writes a String key quoted and a Symbol key bare, so a String-keyed Hash such as Rails params does not read as a Symbol lookup: the JSON input `[{"sku": "B"}]` reads `items[0]["sku"] is "B"`, and the Ruby literal `{"ruby": "[{sku: \"B\"}]"}` reads `items[0].sku is "B"`. Ruby in `{"ruby": ...}` that is a plain literal is named by its value in this way, in both formats. A Ruby call with keyword arguments, such as `FactoryBot.build(:fact, a: "X", b: "Y")`, is named by its keywords as a Hash is (`when b is "Y"`), so factory calls that share a long start read apart; the call before its keywords is named only when it differs. A Hash outcome writes each key as its literal does (`returns "state" => "open"`, `returns due_cents: 0`), and a nested leaf under a String key as the literal that holds it, with the leaves under one key in one literal (`returns "counts" => {"discarded" => 1}`, `returns "tests" => [{"file" => "a_spec.rb", "disposition" => "flaky"}]`). A context says only the values that tell it from its siblings. No text is longer than 80 characters: a longer example says only the values that tell it apart, by their deepest key (`when status is "timeout"`), or by the keys above it too when another leaf ends in the same key (`when result.status is "timeout"`). A String key is named with the argument and the literal that holds the leaf (`when doc holds "status" => "timeout"`, `when doc holds "result" => {"status" => "timeout"}`), since `doc["status"]` would name another leaf, and a long String is cut where it parts from its siblings, and ends before a word the cut would split. An example still over 80 characters cuts its outcome, not those values (`returns ["require \"shop\"",... when target_path is "app/cart.rb"`), and an example that raises keeps the error's class whole and cuts the values after it. An outcome over 40 characters that is a String or an Array of scalars shows its start, then is cut (`returns ["require_relative \"../lib/shop/cart...`). A text with a double quote is written in single quotes, so it needs no escape, even when a String value in it shows its own backslashes (`'returns 1 when x is "say \"hi\""'`).
475
540
 
@@ -507,7 +572,7 @@ branchout loads the `--require` files and then the target after `Coverage.setup(
507
572
 
508
573
  A method in another file is not counted, so its arms are not in the total, the `M` of `covered: N of M arms` (`arms_total` in `--verbose` and `--json`). When a check moves from a subclass's method into a parent class's helper, the total gets smaller while the logic stays the same. `NOT COUNTED` names each such callee: a method that the counted code calls by a bare call or `self.` and that Ruby finds in another file, such as a parent class or a mixin, and a method it calls on an object it builds with `Const.new`, kept in a local (`journal = Ledger.new`) or in an instance variable that a method of the class sets (`@ledger = Ledger.new` in `initialize`). Each entry has `callee` (`Register#required_sku`), `loc` (the file and line of its `def`), and `arms` (the branch arms in that `def`, or `unknown` when its file loaded before coverage started or the method has no `def`, as with `define_method`). Explore the callee as its own entry to cover those arms. Methods of an installed gem or of Ruby's own library are not listed, because an app cannot move a check into one: a Rails model calls dozens of them, such as an association reader or `update!`. Methods written in C, Ruby's own prelude methods, attribute readers and writers, methods with no arms, and calls on an object whose class the code does not show are not listed.
509
574
 
510
- Branch coverage counts no arm for `||`, `&&`, `||=`, or `&&=`, so it cannot say whether their right side ran. A method that branches only through them, as `user&.admin? || params[:force]` does past its `&.`, would report fewer arms than it has, or `covered: 0 of 0 arms`, which reads as fully covered. `OPERATORS` lists each one in the counted code, and `operators_not_counted` counts them: `loc` (the operator's line and column), `op`, and `text` (the whole expression, cut at 160 characters). Give inputs that make each left side truthy and falsy. An `@ivar ||=` or `@ivar &&=` on an instance variable the file sets nowhere else is left out: it memoizes across calls on one object, and each input builds its own receiver, so no input can vary its left side. When the entry has no arm but has such an operator, stderr says so. When its only branch is such a memo, stderr names the memo and says to explore the methods its right side calls and to test the memo by hand, with two calls on one object. Coverage sees no side of a `<`, `<=`, `>`, or `>=` either, so every arm can be taken with no input that makes the two sides equal, and only such an input catches `>` changed to `>=`. `BOUNDARIES` lists each comparison in the counted code, in the shape of `OPERATORS`, and `boundaries_not_counted` counts them; give an input that makes its sides equal. The list comes from the source, so it does not change when an input does that. `&.` has arms of its own (`receiver-present`, `receiver-nil`).
575
+ Branch coverage counts no arm for `||`, `&&`, `||=`, or `&&=`, so it cannot say whether their right side ran. A method that branches only through them, as `user&.admin? || params[:force]` does past its `&.`, would report fewer arms than it has, or `covered: 0 of 0 arms`, which reads as fully covered. `OPERATORS` lists each one in the counted code, and `operators_not_counted` counts them: `loc` (the operator's line and column), `op`, and `text` (the whole expression, cut at 160 characters). Give inputs that make each left side truthy and falsy. An `@ivar ||=` or `@ivar &&=` on an instance variable the file sets nowhere else is left out: it memoizes across calls on one object, and each input builds its own receiver, so no input can vary its left side. When the entry has no arm but has such an operator, stderr says so. When its only branch is such a memo, stderr names the memo and says to explore the methods its right side calls and to test the memo by hand, with two calls on one object. A memo on `defined?(@ivar)` (`return @value if defined?(@value)`) has arms that coverage counts, and an input with a `setup` call of the method covers the cached arm, but that arm returns what the first call stored, so the pinned values read the same without the memo; stderr names each such memo and says to test it the same way. Coverage sees no side of a `<`, `<=`, `>`, or `>=` either, so every arm can be taken with no input that makes the two sides equal, and only such an input catches `>` changed to `>=`. `BOUNDARIES` lists each comparison in the counted code, in the shape of `OPERATORS`, and `boundaries_not_counted` counts them; give an input that makes its sides equal. The list comes from the source, so it does not change when an input does that. `&.` has arms of its own (`receiver-present`, `receiver-nil`).
511
576
 
512
577
  An arm id is `kind@line:column/arm@line:column`, from the Coverage branch key. Columns are 0-based. `cond` is the Prism predicate. For a `when` or `in` arm it is that line. If the locations do not match, the source line is used.
513
578
 
data/lib/branchout/cli.rb CHANGED
@@ -150,7 +150,7 @@ module Branchout
150
150
  user_inputs = []
151
151
  type_overrides = nil
152
152
  if opts[:inputs]
153
- user_inputs, type_overrides = InputFile.load(opts[:inputs])
153
+ user_inputs, type_overrides, opts[:after] = InputFile.load(opts[:inputs])
154
154
  InputFile.quoted_strings(user_inputs).each { |line| $stderr.puts "branchout: #{line}" }
155
155
  end
156
156
 
@@ -167,7 +167,8 @@ module Branchout
167
167
  mutate_cap: opts[:mutate_cap],
168
168
  timeout: opts[:timeout],
169
169
  requires: opts[:requires],
170
- load_paths: opts[:load_paths]
170
+ load_paths: opts[:load_paths],
171
+ after: opts[:after]
171
172
  )
172
173
  if result.repeated_inputs.positive?
173
174
  $stderr.puts "branchout: #{result.repeated_inputs} of #{user_inputs.length} inputs repeat an earlier input, " \
@@ -192,6 +193,12 @@ module Branchout
192
193
  "Only a bare call, a self. call, and a call on new are followed; target the method that branches. " \
193
194
  "--emit-tests still pins the return value or error of each input."
194
195
  end
196
+ Array(result.defined_memos).each do |found|
197
+ $stderr.puts "branchout: `#{found.text}` at #{found.loc} is a memo. Its cached arm runs only on a second call on the same object, " \
198
+ "and returns what the first call stored, so the value an input that covers it pins is the same with the memo or without it. " \
199
+ "Test the memo by hand: call the method twice on one object and check that the second call does not compute the value again, " \
200
+ "such as with a counter in what it calls."
201
+ end
195
202
  write_optional(opts[:json_out], Report.json(result, pin_keys: opts[:pin_keys]))
196
203
  write_optional(opts[:md_out], Report.markdown(result))
197
204
  if opts[:emit_tests]
@@ -238,7 +245,8 @@ module Branchout
238
245
  timeout: opts[:timeout],
239
246
  command: "baselines",
240
247
  requires: opts[:requires],
241
- load_paths: opts[:load_paths]
248
+ load_paths: opts[:load_paths],
249
+ after: opts[:after]
242
250
  )
243
251
  end
244
252
 
@@ -33,9 +33,15 @@ module Branchout
33
33
  lines.concat(Support.cover_comment(pin, " "))
34
34
  lines.concat(Support.thawed_comment(pin, " "))
35
35
  arrange, call = Support.arrange(target, pin.input, private_calls: private_calls, const: const, thawed: pin.thawed)
36
+ # An after reads the receiver once the call raised too, so the
37
+ # receiver is built before assert_raises, where the after can name
38
+ # it. An input whose new or setup call raised read no after, so
39
+ # its receiver is built inside, where that raise is pinned.
40
+ after = Support.after_pin(pin)
36
41
  if pin.error
42
+ lines.concat(Support.indent(arrange, " ")) if after
37
43
  lines << " error = assert_raises(#{pin.error.class_name}) do"
38
- lines.concat(Support.indent(arrange + [call], " "))
44
+ lines.concat(Support.indent((after ? [] : arrange) + [call], " "))
39
45
  lines << " end"
40
46
  if pin.error.name
41
47
  lines << " assert_equal #{pin.error.name.inspect}, error.name"
@@ -44,14 +50,25 @@ module Branchout
44
50
  elsif pin.error.message_pattern
45
51
  lines << " assert_match(#{Regexp.new(pin.error.message_pattern).inspect}, error.message)"
46
52
  end
47
- return lines << " end"
53
+ else
54
+ lines.concat(Support.indent(arrange, " "))
55
+ lines.concat(value_lines(pin, call, Support.keys_for(pin, pin_keys)))
56
+ end
57
+ if after && after.varying != :whole
58
+ source = after.input.after.source
59
+ lines.concat(value_lines(after, source, Support.keys_for(after, []), on: Support.receiver_form(source)))
48
60
  end
61
+ lines << " end"
62
+ end
49
63
 
50
- lines.concat(Support.indent(arrange, " "))
51
- pinned = Support.pinned_value(pin.value, Support.keys_for(pin, pin_keys))
64
+ # The assertions that pin +pin+'s value, which +call+ gives.
65
+ # +on+ is +call+ as a method's receiver.
66
+ def value_lines(pin, call, keys, on: call)
67
+ lines = []
68
+ pinned = Support.pinned_value(pin.value, keys)
52
69
  if !pinned.equal?(pin.value) && Support.literal?(pinned)
53
70
  keys = pinned.keys.map { |key| Support.ruby_literal(key) }.join(", ")
54
- lines << " assert_equal(#{Support.ruby_literal(pinned)}, #{call}.slice(#{keys}))"
71
+ lines << " assert_equal(#{Support.ruby_literal(pinned)}, #{on}.slice(#{keys}))"
55
72
  elsif !pinned.equal?(pin.value)
56
73
  lines.concat(part_lines(pinned, call))
57
74
  elsif pin.value.nil?
@@ -70,7 +87,6 @@ module Branchout
70
87
  lines << " value = #{call}"
71
88
  lines.concat(Support.shape_assertions(pin.value).map { |line| " #{line}" })
72
89
  end
73
- lines << " end"
74
90
  lines
75
91
  end
76
92
 
@@ -137,6 +137,12 @@ module Branchout
137
137
  else
138
138
  lines << "#{indent} expect(#{call}).to #{value_matcher(pin.value, Support.keys_for(pin, @pin_keys))}"
139
139
  end
140
+ # The let memoizes the receiver, so the after reads the object the
141
+ # call ran on, after it returned or raised.
142
+ after = Support.after_pin(pin)
143
+ if after && after.varying != :whole
144
+ lines << "#{indent} expect(#{after.input.after.source}).to #{value_matcher(after.value, Support.keys_for(after, []))}"
145
+ end
140
146
  lines << "#{indent}end"
141
147
  end
142
148
 
@@ -181,6 +187,8 @@ module Branchout
181
187
  peers = members.flat_map { |member| pins_of(member) }
182
188
  texts = members.to_h do |member|
183
189
  others = members.reject { |other| other.equal?(member) }.flat_map { |other| pins_of(other) }
190
+ next [member, noted_text(member)] if member.is_a?(Example) && member.pin.input.note
191
+
184
192
  steps = member.is_a?(Example) ? member.facts : member.steps
185
193
  text = member_text(member, steps, peers)
186
194
  text = member_text(member, telling(steps, others), peers) if text.length > LIMIT || member.is_a?(Node)
@@ -196,6 +204,20 @@ module Branchout
196
204
  end
197
205
  end
198
206
 
207
+ # An example whose input has a note says its outcome and the note,
208
+ # which tells why the input is there better than its facts do. A
209
+ # text over LIMIT is cut at its end, never inside an error's outcome.
210
+ def noted_text(member)
211
+ note = " (#{member.pin.input.note})"
212
+ outcome = @outcomes[member.pin]
213
+ outcome = @short_outcomes[member.pin] if outcome.length + note.length > LIMIT
214
+ text = "#{outcome}#{note}"
215
+ return text if text.length <= LIMIT
216
+
217
+ kept = member.pin.error ? outcome.length : [outcome.length, LIMIT / 2].min
218
+ cut_after(text, kept)
219
+ end
220
+
199
221
  # +text+ cut to +limit+ characters with "...", but never inside its
200
222
  # first +kept+ characters.
201
223
  def cut_after(text, kept, limit = LIMIT)
@@ -382,8 +404,9 @@ module Branchout
382
404
  kind = pin.error ? :inline : :before
383
405
  input.setup.each do |call|
384
406
  plain = Support.argument_list(call.arguments)
385
- code = Support.call_text(receiver_expression, call.method_name, Support.argument_list(call.arguments, thawed: pin.thawed), [])
386
- steps << Step.new(kind, "#{call.method_name}#{"(#{plain})" unless plain.empty?}", code)
407
+ code = Support.with_block(Support.call_text(receiver_expression, call.method_name, Support.argument_list(call.arguments, thawed: pin.thawed), []),
408
+ call.arguments.block)
409
+ steps << Step.new(kind, Support.with_block("#{call.method_name}#{"(#{plain})" unless plain.empty?}", call.arguments.block), code)
387
410
  end
388
411
  steps + fact_steps(input)
389
412
  end