hegeltest 0.3.4 → 0.4.0

data/lib/hegel/test_case.rb

@@ -46,6 +46,16 @@ module Hegel
     # loudly.
     DRAW_CALLER_DEPTH = 3
 
+    # The largest minimum length #repeat draws for its loop: 2**40, the
+    # bound hegel-rust's TestCase::repeat draws its own minimum under
+    # (max_safe_min_size).
+    REPEAT_MAX_MIN_SIZE = 2**40
+
+    # How many columns further #repeat indents the entries one iteration
+    # records: the indent hegel-rust's TestCase::repeat gives the block
+    # handle it runs each iteration under.
+    REPEAT_INDENT = 2
+
     # +impl+ and +ctx+ are carried alongside +handle+ so each draw call can
     # reach the same LibHegel implementation and context the run loop opened,
     # without this class knowing anything about the native binding layer or
@@ -54,17 +64,26 @@ module Hegel
     # +record+ defaults to false: recording is Hegel::Runner's decision, made
     # only for the one, already-shrunk replay that produces a failure report
     # (see #record_draw for why every other iteration skips it).
-    def initialize(impl, ctx, handle, record: false)
+    #
+    # +grammars+ is the run's Hegel::GrammarCache, which Hegel::Runner
+    # passes; a test case built without one compiles a grammar for each draw.
+    def initialize(impl, ctx, handle, record: false, grammars: nil)
       @impl = impl
       @ctx = ctx
       @handle = handle
       @record = record
       @entries = record ? [] : nil
       @pools = []
+      @grammars = grammars
+      # Only declares the ivar: an unset one already reads as nil.
+      @poison = nil # mutineer:disable-line statement_removal
+      @indent = 0
     end
 
-    # The [:draw, name, value] / [:note, message] entries recorded so far, in
-    # call order, or nil when this instance was not built to record.
+    # The [:draw, name, value, indent] / [:note, message, indent] entries
+    # recorded so far, in call order, or nil when this instance was not
+    # built to record. +indent+ is how many columns further in the report
+    # puts the entry; #repeat raises it around each iteration.
     # Hegel::Runner reads this once, after the block that owns this test
     # case has run to completion or raised. One tagged list rather than a
     # draws list and a separate notes list, so a note recorded between two
@@ -151,21 +170,56 @@ module Hegel
 
       return unless @record
 
-      @entries << [:note, has_message ? message : yield]
+      @entries << [:note, has_message ? message : yield, @indent]
+    end
+
+    # Runs the block over and over, for as long as the engine keeps the
+    # loop going, and never returns normally: when the engine ends the loop
+    # it raises Hegel::LoopDone, which Hegel::Runner.classify reports as a
+    # passing case. A `break` in the block ends the loop early and returns
+    # from this method instead; hegel-rust's TestCase::repeat has no
+    # counterpart, since a Rust closure cannot break its caller's loop.
+    # docs/adr/0034 records both decisions.
+    #
+    # The loop is a collection whose minimum length is drawn first, from 0
+    # up to REPEAT_MAX_MIN_SIZE, with no maximum, the way hegel-rust draws
+    # it. Each iteration notes "// Repetition #N", then records what the
+    # block records REPEAT_INDENT columns further in. An iteration whose
+    # assumption failed is skipped rather than discarding the whole case;
+    # any other exception ends the loop (see #repeat_iteration).
+    #
+    # The minimum length is drawn with no span around it. hegel-rust's
+    # draw_silent opens one around every draw, and this library opens a
+    # span only around a generator that makes more than one native call
+    # (.claude/skills/new-generator), which one generate_integer is not.
+    def repeat(&block)
+      min_size = generate_integer(0, REPEAT_MAX_MIN_SIZE)
+      collection = new_collection(min_size, LibHegel::HEGEL_COLLECTION_MAX_SIZE_UNBOUNDED)
+      begin
+        iteration = 0
+        while collection_more(collection)
+          iteration += 1
+          note { "// Repetition ##{iteration}" }
+          repeat_iteration(&block)
+        end
+      ensure
+        collection_free(collection)
+      end
+      raise Hegel::LoopDone, "hegel: repeat finished its loop"
     end
 
     # hegel_generate_integer, without recording. Hegel::Generators::
     # IntegerGenerator's own primitive; #draw_integer is this plus
     # recording.
     def generate_integer(min_value, max_value)
-      @impl.generate_integer(@ctx, @handle, min_value, max_value)
+      @impl.generate_integer(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_integer_big, without recording. Hegel::Generators::
     # IntegerGenerator's own primitive for bounds outside int64_t's range,
     # used instead of #generate_integer only then; see IntegerGenerator#do_draw.
     def generate_integer_big(min_value, max_value)
-      @impl.generate_integer_big(@ctx, @handle, min_value, max_value)
+      @impl.generate_integer_big(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_boolean, without recording. Hegel::Generators::
@@ -175,14 +229,14 @@ module Hegel
       # has_forced is false, so the engine ignores the forced argument's value.
       # .mutineer.yml ignores that mutant by id, since a line marker would also
       # hide the killed mutant of has_forced.
-      @impl.generate_boolean(@ctx, @handle, p, false, false)
+      @impl.generate_boolean(@ctx, live_handle, p, false, false)
     end
 
     # hegel_generate_float. Hegel::Generators::FloatGenerator's own
     # primitive.
     def generate_float(width, min_value, max_value, allow_nan:, allow_infinity:, exclude_min:, exclude_max:,
       smallest_nonzero_magnitude:)
-      @impl.generate_float(@ctx, @handle, width, min_value, max_value, allow_nan, allow_infinity, exclude_min,
+      @impl.generate_float(@ctx, live_handle, width, min_value, max_value, allow_nan, allow_infinity, exclude_min,
         exclude_max, smallest_nonzero_magnitude)
     end
 
@@ -220,33 +274,49 @@ module Hegel
     # this class makes. Writing the same check on this side would only
     # give one mistake two messages to drift apart from each other.
     def target(value, label: "")
-      @impl.target(@ctx, @handle, value, label)
+      @impl.target(@ctx, live_handle, value, label)
+    end
+
+    def event(label)
+      @impl.event(@ctx, live_handle, label)
+    end
+
+    # No finite check here: hegel_event_value's HEGEL_E_INVALID_ARG reaches
+    # the caller through LibHegel.check!, as it does for #target.
+    def event_value(label, value)
+      @impl.event_value(@ctx, live_handle, label, value)
     end
 
     # hegel_start_span, labelled with a generator's label (see
     # Hegel::Generator#label). Every compound Hegel::Generator (map, filter,
     # arrays) opens one of these around its own draw; see #stop_span.
     def start_span(label)
-      @impl.start_span(@ctx, @handle, label)
+      @impl.start_span(@ctx, live_handle, label)
     end
 
     # hegel_stop_span, closing the span #start_span most recently opened.
     # +discard+ true marks it rejected (a filter predicate that did not
     # hold), so libhegel retries from before the span opened.
+    #
+    # Makes no native call while an abandoned recursive attempt unwinds:
+    # hegel_recursion_retry discards the spans that attempt left open, and
+    # closing them here first would keep them. See docs/adr/0032.
     def stop_span(discard: false)
+      return if @poison
+
       @impl.stop_span(@ctx, @handle, discard)
     end
 
     # hegel_new_collection: Hegel::Generators::ArrayGenerator's own sizing
     # primitive, paired with #collection_more and #collection_free.
     def new_collection(min_size, max_size)
-      @impl.new_collection(@ctx, @handle, min_size, max_size)
+      @impl.new_collection(@ctx, live_handle, min_size, max_size)
     end
 
     # hegel_collection_more: whether to draw another element into
     # +collection+.
     def collection_more(collection)
-      @impl.collection_more(@ctx, @handle, collection)
+      @impl.collection_more(@ctx, live_handle, collection)
     end
 
     # hegel_collection_reject: tells libhegel the element most recently
@@ -255,7 +325,7 @@ module Hegel
     # #collection_more call offers another attempt at the same slot instead
     # of treating the collection as one element closer to done.
     def collection_reject(collection, why: nil)
-      @impl.collection_reject(@ctx, @handle, collection, why)
+      @impl.collection_reject(@ctx, live_handle, collection, why)
     end
 
     # hegel_collection_free.
@@ -275,10 +345,11 @@ module Hegel
     end
 
     # Runs the block with a regex-matching string generator handle built
-    # from +pattern+/+fullmatch+ (see #string_generator_regex), freeing it
-    # via #with_generator_handle whether the block returns or raises.
-    def with_regex_generator(pattern, fullmatch:, &block)
-      with_generator_handle(string_generator_regex(pattern, fullmatch), &block)
+    # from +pattern+/+fullmatch+/+alphabet+ (see #string_generator_regex),
+    # freeing it via #with_generator_handle whether the block returns or
+    # raises. +alphabet+ stays the caller's to free.
+    def with_regex_generator(pattern, fullmatch:, alphabet: nil, &block)
+      with_generator_handle(string_generator_regex(pattern, fullmatch, alphabet), &block)
     end
 
     # Runs the block with an email-address string generator handle (see
@@ -304,26 +375,26 @@ module Hegel
     # #with_regex_generator, #with_email_generator, #with_url_generator, or
     # #with_domain_generator).
     def generate_string(generator)
-      @impl.generate_string(@ctx, @handle, generator)
+      @impl.generate_string(@ctx, live_handle, generator)
     end
 
     # hegel_generate_bytes. A future Hegel::Generators::BinaryGenerator's
     # own primitive, the bytes counterpart to #generate_string.
     def generate_bytes(min_size, max_size)
-      @impl.generate_bytes(@ctx, @handle, min_size, max_size)
+      @impl.generate_bytes(@ctx, live_handle, min_size, max_size)
     end
 
     # hegel_generate_ipv4, returning the address's 4 raw bytes. Converting
     # to a caller-facing address type (IPAddr or similar) is left to the
     # generator built on top of this call.
     def generate_ipv4
-      @impl.generate_ipv4(@ctx, @handle)
+      @impl.generate_ipv4(@ctx, live_handle)
     end
 
     # hegel_generate_ipv6, returning the address's 16 raw bytes. Same
     # division of labor as #generate_ipv4.
     def generate_ipv6
-      @impl.generate_ipv6(@ctx, @handle)
+      @impl.generate_ipv6(@ctx, live_handle)
     end
 
     # hegel_generate_uuid, returning 16 raw bytes. Hegel::Generators::
@@ -331,7 +402,7 @@ module Hegel
     # hex String is that generator's job, the same division of labor
     # #generate_ipv4/#generate_ipv6 already follow.
     def generate_uuid(version, has_version)
-      @impl.generate_uuid(@ctx, @handle, version, has_version)
+      @impl.generate_uuid(@ctx, live_handle, version, has_version)
     end
 
     # hegel_string_generator_regex. +alphabet+ is an optional string
@@ -385,7 +456,7 @@ module Hegel
     # Hegel::Stateful::Pool.new cannot forget it and leak the handle --
     # docs/adr/0011 has the ownership decision behind this.
     def new_pool
-      pool = @impl.new_pool(@ctx, @handle)
+      pool = @impl.new_pool(@ctx, live_handle)
       @pools << pool
       pool
     end
@@ -394,7 +465,7 @@ module Hegel
     # associate with the value it just generated. Hegel::Stateful::Pool#add's
     # own primitive.
     def pool_add(pool)
-      @impl.pool_add(@ctx, @handle, pool)
+      @impl.pool_add(@ctx, live_handle, pool)
     end
 
     # hegel_pool_generate: the variable id libhegel chose from +pool+ (and
@@ -405,7 +476,13 @@ module Hegel
     # translates that to Hegel::AssumeFailed, the same as every other
     # assumption failure.
     def pool_generate(pool, consume)
-      @impl.pool_generate(@ctx, @handle, pool, consume)
+      @impl.pool_generate(@ctx, live_handle, pool, consume)
+    end
+
+    # hegel_pool_restore: puts back +variable_id+, a consuming
+    # #pool_generate's answer that the caller is throwing away unused.
+    def pool_restore(pool, variable_id)
+      @impl.pool_restore(@ctx, live_handle, pool, variable_id)
     end
 
     # hegel_pool_free. Not called directly by a caller of
@@ -431,34 +508,34 @@ module Hegel
     # here rather than on that module, the same reason every other native
     # call is a method on this class: Hegel::Stateful never touches @impl or
     # @ctx directly, only this handle-scoped surface.
-    def new_state_machine(rule_names, invariant_names, always_check, step_count)
-      @impl.new_state_machine(@ctx, @handle, rule_names, invariant_names, always_check, step_count)
+    def new_state_machine(rule_names, rule_weights, invariant_names, always_check, step_count)
+      @impl.new_state_machine(@ctx, live_handle, rule_names, rule_weights, invariant_names, always_check, step_count)
     end
 
     # hegel_state_machine_next_group: starts the next round, or returns
     # LibHegel::HEGEL_STATE_MACHINE_DONE once the machine is done.
     def state_machine_next_group(state_machine)
-      @impl.state_machine_next_group(@ctx, @handle, state_machine)
+      @impl.state_machine_next_group(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_next_rule: the index (into the +rule_names+
     # #new_state_machine was given) of the next rule to run this round, or
     # LibHegel::HEGEL_STATE_MACHINE_DONE once the round is over.
     def state_machine_next_rule(state_machine)
-      @impl.state_machine_next_rule(@ctx, @handle, state_machine)
+      @impl.state_machine_next_rule(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_rule_rejected: tells libhegel the rule most
     # recently returned by #state_machine_next_rule stopped early on a
     # failed assumption, so its round does not count toward the step budget.
     def state_machine_rule_rejected(state_machine)
-      @impl.state_machine_rule_rejected(@ctx, @handle, state_machine)
+      @impl.state_machine_rule_rejected(@ctx, live_handle, state_machine)
     end
 
     # hegel_state_machine_should_check_invariant: whether to run the
     # invariant at +index+ at this join point.
     def state_machine_should_check_invariant(state_machine, index)
-      @impl.state_machine_should_check_invariant(@ctx, @handle, state_machine, index)
+      @impl.state_machine_should_check_invariant(@ctx, live_handle, state_machine, index)
     end
 
     # hegel_state_machine_free. Takes no test-case handle, unlike every
@@ -470,11 +547,69 @@ module Hegel
       @impl.state_machine_free(@ctx, state_machine)
     end
 
+    # A hegel_new_recursion handle, and whether #recursion_free has
+    # released it.
+    Recursion = Struct.new(:handle, :freed)
+
+    # hegel_new_recursion. Hegel::Generators::RecursiveGenerator's own
+    # scope, freed by #recursion_free in that generator's `ensure`.
+    def new_recursion(max_depth, max_leaves)
+      Recursion.new(@impl.new_recursion(@ctx, live_handle, max_depth, max_leaves), false)
+    end
+
+    # hegel_recursion_branch: whether the sub-value at +depth+ is a branch.
+    def recursion_branch(recursion, depth)
+      @impl.recursion_branch(@ctx, live_handle, recursion.handle, depth)
+    end
+
+    # hegel_recursion_leaf. Raises Hegel::LeafBudgetExceeded when the
+    # attempt outgrew its leaf budget, and keeps it until #recursion_retry:
+    # every call that takes the test-case handle raises it again instead of
+    # reaching the engine, so a body that rescues it cannot draw on into an
+    # attempt the engine is about to discard.
+    def recursion_leaf(recursion)
+      return if @impl.recursion_leaf(@ctx, live_handle, recursion.handle)
+
+      @poison = LeafBudgetExceeded.new(recursion)
+      raise @poison
+    end
+
+    # True while the attempt +recursion+ abandoned through #recursion_leaf
+    # still waits for #recursion_retry.
+    def abandoned_by?(recursion)
+      @poison.is_a?(LeafBudgetExceeded) && @poison.recursion.equal?(recursion)
+    end
+
+    # hegel_recursion_retry, which reaches the engine with the raw handle
+    # while an attempt is abandoned. HEGEL_E_ASSUME or HEGEL_E_STOP_TEST ends the
+    # test case, so its exception takes the abandoned attempt's place and
+    # later calls raise it without reaching the engine.
+    def recursion_retry(recursion)
+      @impl.recursion_retry(@ctx, @handle, recursion.handle)
+      @poison = nil
+    rescue AssumeFailed, StopTest => e
+      @poison = e
+      raise
+    end
+
+    # hegel_recursion_finish: false when the engine discarded the finished
+    # attempt, which the caller then draws again from the root.
+    def recursion_finish(recursion)
+      @impl.recursion_finish(@ctx, live_handle, recursion.handle)
+    end
+
+    # hegel_recursion_free. Takes no test-case handle, so it runs while an
+    # attempt is abandoned.
+    def recursion_free(recursion)
+      recursion.freed = true
+      @impl.recursion_free(@ctx, recursion.handle)
+    end
+
     # hegel_generate_date, without recording. Hegel::Generators::
     # DatesGenerator's own primitive. +min_value+/+max_value+ are each a
     # [year, month, day] Array; the return value is the same shape.
     def generate_date(min_value, max_value)
-      @impl.generate_date(@ctx, @handle, min_value, max_value)
+      @impl.generate_date(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_time, without recording. Hegel::Generators::
@@ -482,7 +617,7 @@ module Hegel
     # [hour, minute, second, microsecond] Array; the return value is the
     # same shape.
     def generate_time(min_value, max_value)
-      @impl.generate_time(@ctx, @handle, min_value, max_value)
+      @impl.generate_time(@ctx, live_handle, min_value, max_value)
     end
 
     # hegel_generate_datetime, without recording. Hegel::Generators::
@@ -491,11 +626,97 @@ module Hegel
     # [hour, minute, second, microsecond] Array; the return value is a
     # [[year, month, day], [hour, minute, second, microsecond]] pair.
     def generate_datetime(min_date, min_time, max_date, max_time)
-      @impl.generate_datetime(@ctx, @handle, min_date, min_time, max_date, max_time)
+      @impl.generate_datetime(@ctx, live_handle, min_date, min_time, max_date, max_time)
+    end
+
+    # Yields the Hegel::GrammarCache::Compiled under +key+ in the run's
+    # cache, calling +build+ to compile it on the first draw. Without a
+    # cache, it compiles one for this draw alone and frees it afterwards.
+    def with_grammar(key, build)
+      return yield @grammars.fetch(key, &build) if @grammars
+
+      compiled = build.call
+      begin
+        yield compiled
+      ensure
+        grammar_free(compiled.grammar)
+      end
+    end
+
+    def grammar_builder_new(text)
+      @impl.grammar_builder_new(@ctx, text)
+    end
+
+    def grammar_builder_file(builder, index)
+      @impl.grammar_builder_file(@ctx, builder, index)
+    end
+
+    def grammar_builder_provide(builder, index, text)
+      @impl.grammar_builder_provide(@ctx, builder, index, text)
+    end
+
+    def grammar_builder_free(builder)
+      @impl.grammar_builder_free(@ctx, builder)
+    end
+
+    def grammar_new(builder, start, max_size, max_depth, alphabet, names)
+      @impl.grammar_new(@ctx, builder, start, max_size, max_depth, alphabet, names)
+    end
+
+    def grammar_placeholder(grammar, name)
+      @impl.grammar_placeholder(@ctx, grammar, name)
+    end
+
+    def grammar_free(grammar)
+      @impl.grammar_free(@ctx, grammar)
+    end
+
+    # hegel_generate_grammar, without recording.
+    def generate_grammar(grammar, max_size)
+      @impl.generate_grammar(@ctx, live_handle, grammar, max_size)
     end
 
     private
 
+    def live_handle
+      raise @poison if @poison
+
+      @handle
+    end
+
+    # Runs one #repeat iteration with the indent raised by REPEAT_INDENT.
+    # hegel-rust indents an iteration's output through hegel_test_case_block,
+    # which indents only what the engine printer prints. This library
+    # renders its report itself (Hegel::Report, docs/adr/0005), so the
+    # indent is kept on this side and recorded with each entry.
+    #
+    # The rescue order follows hegel-rust's TestCase::repeat, after the
+    # fatal exceptions every `rescue Exception` here lets through first. The
+    # library's own control exceptions, a nested #repeat's Hegel::LoopDone
+    # among them, and Hegel::Error, which stands where hegel-rust's
+    # InvalidArgument and InternalError stand, re-raise unchanged. A failed
+    # assumption skips to the next iteration. Anything else is a failure:
+    # one boolean is drawn before it re-raises, as hegel-rust draws one.
+    #
+    # standard:disable Lint/RescueException -- the same reason as
+    # Hegel::Runner.classify: a failing assertion descends from Exception.
+    def repeat_iteration
+      @indent += REPEAT_INDENT
+      begin
+        yield
+      ensure
+        @indent -= REPEAT_INDENT
+      end
+    rescue *Hegel::FATAL_EXCEPTIONS, Hegel::StopTest, Hegel::LoopDone, Hegel::Error
+      raise
+    rescue Hegel::AssumeFailed
+      # Skips this iteration; #repeat goes on to the next one.
+    rescue Exception
+      generate_boolean
+      raise
+    end
+    # standard:enable Lint/RescueException
+
     # Runs the block with +generator+, freeing it via #string_generator_free
     # whether the block returns or raises. The one #ensure
     # #with_regex_generator/#with_email_generator/#with_url_generator/
@@ -522,7 +743,7 @@ module Hegel
     def record_draw(label, value)
       return unless @record
 
-      @entries << [:draw, name_for(label, DRAW_CALLER_DEPTH), value]
+      @entries << [:draw, name_for(label, DRAW_CALLER_DEPTH), value, @indent]
     end
 
     # The single place a draw's name is decided, tried in this order: the

data/lib/hegel/test_location.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "runner"
+
+module Hegel
+  # Where a Hegel.test call lives, in the four pieces
+  # hegel_settings_set_test_location takes. Under Antithesis the engine
+  # reports each run's verdict as the assertion
+  # "<class_name>::<function> passes properties" at file:begin_line, so two
+  # calls that share a class_name and a function share one assertion.
+  TestLocation = Data.define(:file, :begin_line, :class_name, :function)
+
+  class TestLocation
+    # Matches the label prefix Ruby 3.4 puts on a frame inside a block, so
+    # that the method underneath names the test.
+    BLOCK_PREFIX = /\A(?:block(?: \(\d+ levels\))? in )+/
+
+    # Matches "Class#method" and "Class.method". Greedy, so a namespaced
+    # class keeps its "::" and a "#<Class:0x...>" label splits at its last
+    # separator.
+    METHOD_LABEL = /\A(.+)[#.]([^#.]+)\z/
+
+    # The first of +locations+ that is the caller's own, by the same rule
+    # Runner.origin_for uses to name a failure (see ADR 0012), so a wrapper in
+    # this gem, a gem, or the standard library is not named as the test.
+    # +locations+ is never empty, because the frame of Hegel.test's own caller
+    # exists even at the top of a script.
+    def self.from_locations(locations)
+      location = locations.find { |candidate| !Runner.infrastructure?(candidate.path) } || locations.first
+      path = location.absolute_path || location.path
+      root = File.join(Dir.pwd, "")
+      file = path.start_with?(root) ? path.delete_prefix(root) : path
+      class_name, function = names(location.label, file, location.lineno)
+      new(file: file, begin_line: location.lineno, class_name: class_name, function: function)
+    end
+
+    # [class_name, function] for a frame +label+. A frame with no enclosing
+    # method (a script body, or an RSpec example, whose block sits at the top
+    # of its file) has no name of its own, so it takes its file and line:
+    # that keeps two examples in one file from sharing one assertion.
+    def self.names(label, file, lineno)
+      match = METHOD_LABEL.match(label.sub(BLOCK_PREFIX, ""))
+      return match.captures if match
+
+      [file.delete_suffix(".rb"), "line #{lineno}"]
+    end
+    private_class_method :names
+  end
+end

data/lib/hegel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hegel
-  VERSION = "0.3.4"
+  VERSION = "0.4.0"
 end

data/lib/hegel.rb

@@ -3,6 +3,7 @@
 require_relative "hegel/version"
 require_relative "hegel/errors"
 require_relative "hegel/runner"
+require_relative "hegel/test_location"
 require_relative "hegel/generator"
 require_relative "hegel/generators"
 require_relative "hegel/syntax/methods"
@@ -28,6 +29,13 @@ module Hegel
   # assertion failure rather than as a Hegel-specific one. Raises
   # Hegel::Error for a run-level failure instead of a property failure.
   #
+  # +profile+ names the settings profile the run starts from: one of the
+  # engine's shipped profiles, one in hegel.toml, or one registered with
+  # Hegel::Settings.register_profile. Left nil, the run starts from the
+  # default profile. A keyword passed alongside still beats the profile, and
+  # report_multiple_failures is always passed, so a profile's value for it
+  # never applies (see docs/adr/0028). An unknown name raises Hegel::Error.
+  #
   # +test_cases+, +seed+, +derandomize+, +verbosity+, +phases+, and
   # +suppress_health_check+ all default to nil, which means the same thing
   # for each of them: do not call the matching libhegel setter, and let the
@@ -54,6 +62,11 @@ module Hegel
   # keyword above: see Hegel::Runner.run's own comment for why it is always
   # passed.
   #
+  # +stop_on_first_failure+, +print_blob+, +show_statistics+,
+  # +nondeterminism_strictness+, and +backend+ default to nil, so the engine's
+  # profile decides as it does for +test_cases+; they follow hegel-rust's
+  # Settings.
+  #
   # +output+ (default $stderr) is where a failure report is written; a
   # caller passes its own IO to capture that report instead (tests do).
   #
@@ -66,13 +79,16 @@ module Hegel
   # real engine. Ordinary callers never pass it. Its default expression
   # (#default_impl) only runs when +impl+ is not given, so a test that does
   # pass one never opens the native library at all.
-  def test(test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
-    phases: nil, suppress_health_check: nil, report_multiple_failures: false, output: $stderr,
+  def test(profile: nil, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
+    phases: nil, suppress_health_check: nil, report_multiple_failures: false, stop_on_first_failure: nil,
+    print_blob: nil, show_statistics: nil, nondeterminism_strictness: nil, backend: nil, output: $stderr,
     reproduce_failure: nil, impl: default_impl, &block)
-    Runner.run(impl: impl, test_cases: test_cases, seed: seed, derandomize: derandomize, verbosity: verbosity,
+    Runner.run(impl: impl, profile: profile, test_cases: test_cases, seed: seed, derandomize: derandomize, verbosity: verbosity,
       database: database, database_key: database_key, phases: phases, suppress_health_check: suppress_health_check,
-      report_multiple_failures: report_multiple_failures, output: output, reproduce_failure: reproduce_failure,
-      &block)
+      report_multiple_failures: report_multiple_failures, stop_on_first_failure: stop_on_first_failure,
+      print_blob: print_blob, show_statistics: show_statistics, nondeterminism_strictness: nondeterminism_strictness,
+      backend: backend, output: output, reproduce_failure: reproduce_failure,
+      test_location: TestLocation.from_locations(caller_locations(1)), &block)
   end
 
   # The Hegel::LibHegel::Real instance #test uses by default, built once and