card-test — the canonical cast-pipeline test recipe

This skill gives ONE rigid recipe for runtime engine tests that cast a spell and
assert its effect. It exists because six test-harness foot-guns recur; the
[SpellCast] driver and [CastOutcome] (in crates/engine/src/game/scenario.rs)
make them structurally impossible when you follow this recipe.

Reference ports that demonstrate the pattern:

• crates/engine/tests/chord_of_calling.rs — X-spell, convoke, final_waiting_for() boundary.
• crates/engine/src/game/casting.rs — exsanguinate_* (life deltas, 2- and 3-player), vicious_rivalry_* (X-cost filter + zones), kozileks_command_modes_* (modal + X + multi-target).

The recipe

use engine::game::scenario::{GameScenario, GameRunner};
// ... typed imports for the effect under test ...

#[test]
fn my_card_does_the_thing() {
    // 1. BUILD STATE via GameScenario (or wrap a raw GameState with
    //    GameRunner::from_state(state) when the test builds state imperatively).
    let mut scenario = GameScenario::new();
    scenario.at_phase(Phase::PreCombatMain);
    let spell = scenario
        .add_spell_to_hand_from_oracle(P0, "My Card", /* is_instant */ true, ORACLE)
        .id();
    // ... stage targets / mana / library as needed ...
    let mut runner = scenario.build();

    // 2. CAST through the pipeline. Declare INTENT, never targets-by-hand.
    let outcome = runner
        .cast(spell)
        .modes(&[0, 2])              // modal "choose N" — omit if non-modal
        .x(3)                        // announce X — omit if non-X
        .target_player(P1)           // declare a player intent (reusable across slots)
        .target_objects(&[victim])   // declare object intents (one per slot, in order)
        .convoke_with(&[creature])   // tap creatures to pay via Convoke — omit otherwise
        .resolve();

    // 3. ASSERT via CastOutcome deltas — behavior/semantics, never AST internals.
    outcome.assert_life_delta(P1, -3);
    outcome.assert_zone(&[victim], Zone::Exile);
    outcome.assert_hand_drawn(P0, 1);
    // For "no further prompt" boundaries (e.g. fail-to-find), inspect the halt state:
    assert!(matches!(outcome.final_waiting_for(), WaitingFor::Priority { .. }));
}

What the driver does for you

resolve() runs a bounded state-machine over state.waiting_for (CR 601.2a–h):

• ModeChoice → submits .modes(..) (panics if modal but no modes declared).
• ChooseXValue → submits .x(..) (panics if X needed but not declared).
• ManaPayment { convoke_mode } → taps each .convoke_with(..) creature with
  mana of its color, then finalizes (CR 702.51b). Pool-funded casts auto-pay and
  never surface this window.
• TargetSelection → answers one slot at a time, in written order
  (CR 601.2c). Object intent is consumed (one declared object per slot); player
  intent is reusable (one player may be targeted by several modes).
• Priority (post-cast) → captures the per-player hand baseline at stack commit
  (CR 601.2a) and proceeds to resolution.
• Resolution auto-answers OrderTriggers (CR 603.3b) and ScryChoice (keeps
  looked-at cards on top, CR 701.22a); it stops at stack-empty or at any prompt
  it is not taught to answer (e.g. SearchChoice) so you can assert on it via
  final_waiting_for().
• Any unhandled prompt → a clear extend the driver or drive this case manually
  panic. Extending the driver is the correct response; never assert around a
  silent skip.

CastOutcome accessors

Accessor	Returns
hand_drawn(p) / assert_hand_drawn(p, n)	net cards drawn since stack commit (the clean resolution delta)
zone_of(o) / assert_zone(&[o], zone)	an object's current zone
life_delta(p) / assert_life_delta(p, n)	net life change since before the cast
final_waiting_for()	the state the pipeline halted in
state()	read-only &GameState for assertions the typed accessors don't cover

Anti-patterns — the six foot-guns and the right-way fix

1. Hand-written TargetRef vectors. Building a flat Vec<TargetRef> and
   submitting SelectTargets { targets } is fragile (TargetRef is non-Copy;
   .copied() won't compile, and the order must match the slots exactly).
   Fix: declare intent with .target_object(..) / .target_player(..); the
   driver matches each intent to its slot.

2. Incomplete modal target submission. Omitting one mode's slot yields
   InvalidAction("Illegal target selected") because targets are validated one
   per slot, in written order (ability_utils::choose_target).
   Fix: the driver answers every slot via ChooseTarget in order — you cannot
   forget a slot.

3. Hand/zone baseline captured at the wrong point. handle_cast_spell does
   NOT remove the spell from hand; CR 601.2a removes it only when the cast
   commits to the stack (the Priority window). A baseline taken before that is
   off by one.
   Fix: CastOutcome::hand_drawn is measured against the stack-commit
   baseline the driver captures for you. Use assert_hand_drawn, never a
   hand-picked let hand_before = ....

4. Keywords fed as inline Oracle reminder text. Writing "Convoke (Your creatures ...)" as plain text parses to Effect::Unimplemented.
   Fix: build keyworded cards via
   from_oracle_text_with_keywords(&["Convoke"], text), and pay convoke via
   .convoke_with(&[..]) (which the driver routes through TapForConvoke).

5. Asserting representation-internal dual-encoded flags. Asserting an
   AST field such as ChangeZone.up_to couples the test to one encoding of the
   spec rather than the behavior.
   Fix: assert behavior via CastOutcome deltas (zone_of, life_delta,
   hand_drawn). When a SHAPE assertion is genuinely needed (parser structure),
   label the test SHAPE and assert via semantic accessors (e.g. a
   MultiTargetSpec), not internal bools.

6. Vacuous negative assertions. A negative assertion (!detector(...),
   "no longer parses to X", "counter is NOT applied") passes for the wrong
   reason when an upstream guard short-circuits before the code under test
   runs. Canonical instance: check_swallowed_clauses returns early when any
   parsed ability contains Effect::Unimplemented, so
   !has_swallowed_clause(...) passes on a card that failed to parse at all —
   the single most common review finding on contributor PRs.
   Fix: every negative assertion must be paired with a positive reach-guard
   in the same test proving the input got past the short-circuit (parse
   succeeded, zero Effect::Unimplemented entries, the expected positive AST
   shape, or a positive runtime delta on the sibling path). Better still,
   replace the negative with a runtime regression whose assertion flips when
   the fix is reverted.

Hard rules

• Never call the raw resolve() stack function directly. Drive through the
  apply() pipeline (via runner.cast(..).resolve() or runner.act(..)).
  Calling stack::resolve_top / effect::resolve directly bypasses the
  intervening-if recheck and the cast_from_zone carry-through, so cast-trigger
  bugs (cascade/storm/casualty) go invisible. See the memory landmine
  project_cast_from_zone_stack_wipe.
• Prefer runtime-behavior tests. Reserve AST-SHAPE tests for parser
  structure; label them SHAPE and assert via semantic accessors, not internal
  flags. The two Kozilek/Chord SHAPE tests
  (kozileks_command_full_four_mode_parse,
  chord_of_calling_parses_x_mana_value_search_shape) are the correct pattern
  for that and are intentionally NOT driven through cast().
• CR-annotate any assertion that encodes a rule (verify the number against
  docs/MagicCompRules.txt before writing it).
• Use the card's verbatim Oracle text, never a paraphrase. Build the test
  card from the real card's exact Oracle text (add_spell_to_hand_from_oracle
  with the verbatim string, or add_real_card for integration fixtures).
  Paraphrased text can take a different parser branch than the real card, so
  the test goes green while the actual card stays broken until card-data is
  regenerated (see project_parser_fix_inert_until_data_regen).
• Regenerate the integration fixture when your parser change touches a card
  it contains. add_real_card reads the committed
  crates/engine/tests/fixtures/integration_cards.json snapshot.
  python3 scripts/gen-test-fixture.py --check verifies coverage only — that every
  referenced card is PRESENT (a key-set comparison). It never compares the stored parse
  VALUES against a fresh export. So a parser change that alters a fixture card's parse
  leaves the fixture stale while the gate stays green: the integration test then asserts
  against the old parse and proves nothing about the code you shipped. If your change
  alters how any fixture card parses, re-run python3 scripts/gen-test-fixture.py (no
  --check) and commit the regenerated fixture in the same PR.