haveapi 0.31.1 → 0.32.0

data/spec/client_examples/context_performance_spec.rb

@@ -30,11 +30,12 @@ describe HaveAPI::ClientExample::Context, '#with' do
   it 'shares every unchanged field and owns a different snapshot for a new request' do
     parent = parent_context(8)
     other_request = parent_context(8)
-    children = [parent.with(profile:), parent.with(sample:)]
-    fields = %i[version host base_url version_url description resource_path resource action_name action sample profile]
+    changes = [{ profile: }, { sample: }, { detail: :thorough }]
+    children = changes.map { |change| parent.with(**change) }
+    fields = described_class::FIELDS
 
     children.each_with_index do |child, index|
-      changed = index == 0 ? :profile : :sample
+      changed = changes[index].keys.first
       (fields - [changed]).each do |field|
         expect(child.public_send(field)).to equal(parent.public_send(field))
       end
@@ -51,7 +52,7 @@ describe HaveAPI::ClientExample::Context, '#with' do
   it 'keeps allocations independent of unrelated description size for small changes' do
     small = parent_context(8)
     large = parent_context(128)
-    changes = [{ profile: }, { sample: }]
+    changes = [{ profile: }, { sample: }, { detail: :thorough }]
     [small, large].each do |parent|
       changes.each { |change| 80.times { parent.with(**change) } }
     end

data/spec/client_examples/context_spec.rb

@@ -25,6 +25,27 @@ describe HaveAPI::ClientExample::Context do
     expect(child).to be_frozen
   end
 
+  it 'defaults to simple and shares owned data when changing the detail' do
+    expect(context.detail).to eq(:simple)
+    thorough = context.with(detail: :thorough)
+    expect(thorough.detail).to eq(:thorough)
+    expect(thorough).to be_frozen
+    (described_class::FIELDS - [:detail]).each do |field|
+      expect(thorough.public_send(field)).to equal(context.public_send(field))
+    end
+    expect(thorough.with(detail: :simple).detail).to eq(:simple)
+    expect(context.detail).to eq(:simple)
+  end
+
+  it 'rejects detail values outside the two explicit symbols in construction and derivation' do
+    [nil, false, 'simple', 'thorough', :unknown].each do |detail|
+      expect { context.with(detail:) }.to raise_error(ArgumentError, 'detail must be :simple or :thorough')
+      expect do
+        described_class.new(version: '1', host: 'api.test', base_url: '/', version_url: '/v1/', description: {}, detail:)
+      end.to raise_error(ArgumentError, 'detail must be :simple or :thorough')
+    end
+  end
+
   describe '#with' do
     let(:fields) do
       {
@@ -33,7 +54,7 @@ describe HaveAPI::ClientExample::Context do
         description: { 'resources' => { 'widget' => { 'label' => 'Widget' } } },
         resource_path: [:widget, 2], resource: { 'label' => 'Widget' },
         action_name: :show, action: { 'method' => 'GET' },
-        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new
+        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new, detail: :simple
       }
     end
     let(:parent) { described_class.new(**fields) }
@@ -45,7 +66,7 @@ describe HaveAPI::ClientExample::Context do
         resource_path: [:other, 3], resource: { 'label' => 'Other' },
         action_name: :update, action: { 'method' => 'POST' },
         sample: { 'request' => { 'values' => [false, 0, nil, ''] } },
-        profile: Object.new
+        profile: Object.new, detail: :thorough
       }
     end
 

data/spec/client_examples/detail_spec.rb

@@ -0,0 +1,175 @@
+require 'spec_helper'
+require 'open3'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExample, '.render' do
+  include DynamicExampleFixture
+
+  let(:renderers) do
+    [HaveAPI::ClientExamples::JsClient, HaveAPI::ClientExamples::JsAsyncClient,
+     HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient,
+     HaveAPI::ClientExamples::PythonClient, HaveAPI::ClientExamples::PythonAsyncClient]
+  end
+
+  it 'keeps simple actions focused on the existing api and leaves setup and diagnostics to thorough' do
+    renderers.each do |renderer|
+      context = dynamic_context
+      simple = renderer.render(:example, context:).fetch(:code)
+      thorough = renderer.render(:example, context: context.with(detail: :thorough)).fetch(:code)
+      expect(simple).to include('api', 'name/with space')
+      expect(simple).not_to include('import ', 'credential(', 'os.environ', 'new AsyncClient', 'new CallbackClient',
+                                    'with Client(', 'with AsyncClient(', 'try:', 'try {', 'response.meta', 'reply.meta()')
+      expect(thorough).to include('import ', context.base_url)
+      expect(thorough).to include(renderer.code == :python ? 'except HaveAPIError' : 'catch (error)')
+      expect(context.detail).to eq(:simple)
+      expect(context.sample[:request][:enabled]).to be(false)
+      expect(context.sample[:request][:count]).to eq(0)
+      expect(context.sample[:request][:nullable]).to be_nil
+    end
+  end
+
+  it 'returns identical limitations at both levels without revealing hidden sample or metadata values' do
+    contexts = [
+      dynamic_context(sample: dynamic_sample.merge(path_params: [7])),
+      dynamic_context(sample: dynamic_sample.merge(request: { hidden_parameter: 'private-sample' })),
+      dynamic_context(sample: { request: nil, response: nil }),
+      dynamic_context(action: dynamic_action.merge(meta: {
+        global: { input: { parameters: { secret: { required: true, default: 'private-default' } } } }
+      }))
+    ]
+    renderers.each do |renderer|
+      contexts.each do |context|
+        simple = renderer.render(:example, context:)
+        thorough = renderer.render(:example, context: context.with(detail: :thorough))
+        expect(simple).to eq(thorough)
+        expect(simple[:status]).to eq(:limitation)
+        expect(simple[:reason]).not_to include('private-sample', 'private-default', 'hidden_parameter')
+      end
+    end
+  end
+
+  it 'validates unsupported required authentication before returning either action fragment' do
+    context = dynamic_context(action: dynamic_action.merge(auth: true), description: { authentication: {} })
+    renderers.each do |renderer|
+      results = %i[simple thorough].map { |detail| renderer.render(:example, context: context.with(detail:)) }
+      expect(results[0]).to eq(results[1])
+      expect(results[0][:status]).to eq(:limitation)
+    end
+  end
+
+  it 'keeps Python async fragments in an explicit async context without adding executable wrappers' do
+    source = HaveAPI::ClientExamples::PythonAsyncClient.render(:example, context: dynamic_context).fetch(:code)
+    script = 'import ast, sys; ast.parse("async def example():\n" + "".join("    " + line for line in sys.stdin))'
+    output, status = Open3.capture2e('python', '-c', script, stdin_data: source)
+    expect(status).to be_success, output
+    expect(source).to include('# Run inside an async function after initializing api.', 'response = await api.resources')
+    expect(source).not_to include('__main__', 'async def ', 'asyncio.run')
+  end
+
+  it 'preserves operation waiting and its timeout meaning at both detail levels' do
+    context = dynamic_context(action: dynamic_action.merge(blocking: true))
+    [HaveAPI::ClientExamples::PythonClient, HaveAPI::ClientExamples::PythonAsyncClient].each do |renderer|
+      %i[simple thorough].each do |detail|
+        source = renderer.render(:example, context: context.with(detail:)).fetch(:code)
+        expect(source).to include('response.operation.wait(timeout=300, interval=1)', 'does not cancel a server operation')
+      end
+    end
+  end
+
+  it 'uses simple fragments for positional dynamic, Ruby and PHP renderers without changing their calls' do
+    context = dynamic_context
+    args = [context.host, context.base_url, context.version, context.resource_path, context.resource,
+            context.action_name, context.action]
+    renderers.each do |renderer|
+      expect(renderer.new(*args).example(context.sample)).to eq(renderer.render(:example, context:))
+    end
+    sample = { path_params: [7], request: { name: '' }, status: false }
+    action = { output: { layout: :hash } }
+    ruby = HaveAPI::ClientExamples::RubyClient.new('api.test', 'https://api.test/', '1', ['widget'], {}, 'show', action)
+    php = HaveAPI::ClientExamples::PhpClient.new('api.test', 'https://api.test/', '1', ['widget'], {}, 'show', action)
+    expect(ruby.example(sample)).to start_with('reply = api.widget.show(7,')
+    expect(php.example(sample)).to start_with('$reply = $api->widget->show(7,')
+    expect(ruby.example(sample)).not_to include('HaveAPI::Client.new')
+    expect(php.example(sample)).not_to include('new \\HaveAPI\\Client')
+  end
+
+  it 'offers callback setup once while preserving real action lookup and reply error handling' do
+    [HaveAPI::ClientExamples::JsClient, HaveAPI::ClientExamples::TsClient].each do |renderer|
+      context = dynamic_context
+      %i[init auth].each do |kind|
+        result = renderer.render(kind, context:, auth_method: :basic, auth_description: {})
+        expect(result.fetch(:code)).to include('if (!ready)', 'Discovery or authentication failed')
+        levels = renderer.detail_levels_for(kind, context:, result:, auth_method: :basic, auth_description: {})
+        expect(levels).to eq([:simple])
+        expect(levels).to be_frozen
+      end
+      result = renderer.render(:example, context:)
+      expect(result.fetch(:code)).to include('findAction', 'if (!reply.isOk())')
+      thorough = renderer.render(:example, context: context.with(detail: :thorough)).fetch(:code)
+      expect(thorough).to include('try {', 'catch (error)', 'reply.meta()')
+      expect(renderer.detail_levels_for(:example, context:, result:)).to eq(%i[simple thorough])
+    end
+  end
+
+  it 'offers async discovery and Python context-manager error handling for setup and actions' do
+    [HaveAPI::ClientExamples::JsAsyncClient, HaveAPI::ClientExamples::TsAsyncClient,
+     HaveAPI::ClientExamples::PythonClient, HaveAPI::ClientExamples::PythonAsyncClient].each do |renderer|
+      context = dynamic_context
+      %i[init auth example].each do |kind|
+        result = renderer.render(kind, context:, auth_method: :basic, auth_description: {})
+        levels = renderer.detail_levels_for(kind, context:, result:, auth_method: :basic, auth_description: {})
+        expect(levels).to eq(%i[simple thorough])
+        expect(levels).to be_frozen
+        thorough = renderer.render(kind, context: context.with(detail: :thorough),
+                                         auth_method: :basic, auth_description: {}).fetch(:code)
+        expect(thorough).to include(renderer.code == :python ? 'except HaveAPIError' : 'error instanceof AsyncError')
+      end
+    end
+  end
+
+  it 'offers Ruby and PHP real error handling while retaining simple direct calls' do
+    context = dynamic_context(resource_path: ['widget'], action_name: 'show')
+    [HaveAPI::ClientExamples::RubyClient, HaveAPI::ClientExamples::PhpClient].each do |renderer|
+      %i[init auth example].each do |kind|
+        result = renderer.render(kind, context:, auth_method: :basic, auth_description: {})
+        expect(renderer.detail_levels_for(kind, context:, result:, auth_method: :basic)).to eq(%i[simple thorough])
+        source = renderer.render(kind, context: context.with(detail: :thorough),
+                                       auth_method: :basic, auth_description: {}).fetch(:code)
+        expect(source).to include(renderer.code == :ruby ? 'api.setup' : '$api->setup()')
+        expect(source).to include('ValidationError', 'ActionFailed', renderer.code == :ruby ? 'rescue' : 'catch')
+      end
+      expect(context.detail).to eq(:simple)
+      expect(context.sample).to eq(dynamic_sample)
+    end
+  end
+
+  it 'advertises only Simple for built-in limitations without probing another render' do
+    context = dynamic_context(sample: dynamic_sample.merge(path_params: [7]))
+    results = renderers.to_h { |renderer| [renderer, renderer.render(:example, context:)] }
+    renderers.each do |renderer|
+      result = results.fetch(renderer)
+      expect(result).to include(status: :limitation)
+      allow(renderer).to receive(:render).and_call_original
+      expect(renderer.detail_levels_for(:example, context:, result:)).to eq([:simple])
+      expect(renderer).not_to have_received(:render)
+    end
+    [HaveAPI::ClientExamples::RubyClient, HaveAPI::ClientExamples::RubyCli].each do |renderer|
+      result = renderer.render(:auth, context:, auth_method: :oauth2, auth_description: {})
+      expect(result.fetch(:code)).to include('not supported')
+      expect(renderer.detail_levels_for(:auth, context:, result:, auth_method: :oauth2,
+                                               auth_description: {})).to eq([:simple])
+    end
+  end
+
+  it 'authenticates protected Ruby and PHP programs with advertised literal existing credentials' do
+    context = dynamic_context(action: dynamic_action.merge(auth: true), resource_path: ['widget'], action_name: 'show', detail: :thorough)
+    [HaveAPI::ClientExamples::RubyClient, HaveAPI::ClientExamples::PhpClient].each do |renderer|
+      result = renderer.render(:example, context:)
+      expect(result[:status]).to eq(:code)
+      expect(result[:code]).to include('example-token')
+      expect(result[:code].index('example-token')).to be < result[:code].index(renderer.code == :ruby ? 'reply = api.widget' : '$reply = $api->widget')
+      unsupported = renderer.render(:example, context: context.with(description: { authentication: {} }))
+      expect(unsupported).to include(status: :limitation)
+    end
+  end
+end

data/spec/client_examples/dynamic_acceptance.md

@@ -1,9 +1,10 @@
 # Dynamic example verification
 
 The six JavaScript, TypeScript and Python variants are ordinary server renderers.
-They require no generated-SDK profile. Their examples use exact public lookups,
-mounted base URLs and explicit API versions. Credentials come from environment
-variables in the example process; no example executes in a documentation request.
+They require no API client profile. Their examples use exact public lookups,
+mounted base URLs and explicit API versions. Credentials are public example
+literals: `user`, `secret`, `example-token` and `example-access-token`. Examples
+do not execute during a documentation request.
 
 Run the focused checks in the prepared top-level Nix environment:
 
@@ -16,9 +17,11 @@ bundle exec rspec spec/client_examples/dynamic_js_spec.rb \
 ```
 
 The unit checks parse the actual generated source and compile both TypeScript
-variants against emitted public declarations. Prepare the JavaScript build and
-its declared development dependencies first. The Rack fixture check renders real
-mounted HTML and verifies the extraction boundary and request/result fixtures;
+variants at both detail levels against emitted public declarations. Simple
+action fragments receive a declared initialized `api` in the compiler fixture;
+Python async fragments are parsed in an async function. Prepare the JavaScript
+build and its declared development dependencies first. The Rack fixture check
+renders real mounted HTML and verifies extraction and request/result fixtures;
 it opens no listening socket and does not install packages.
 
 `make test-documentation-python` runs the supplemental native Python request
@@ -31,12 +34,11 @@ transport. It installs nothing and is separate from ordinary Ruby spec discovery
 The focused JavaScript specs cross-check the built callback and async query/body
 serializers with a mocked transport. The full `make test` includes both checks.
 
-Python token-login examples read required request fields from JSON values in
-`HAVEAPI_AUTH_*` environment variables. For example, an API that requires
-`lifetime` reads `HAVEAPI_AUTH_lifetime`. The examples omit optional lifetime and
-interval fields. The acceptance fixture explicitly chooses `"fixed"` from its
-advertised lifetime values and omits optional interval. The Python challenge
-object supplies the continuation token.
+Token-login examples use advertised typed literal input maps. Python selects
+continuations through `step.next_action` and calls `step.submit(values)`;
+JavaScript/TypeScript use their actual action callback argument. The runtime
+propagates intermediate tokens. The acceptance fixture requires fixed lifetime,
+credential request and verification before authenticated discovery.
 
 `dynamic_acceptance.rb` checks the installed packages. Supply the built npm and
 Python artifacts, the compiler and Node declaration directories, and a directory
@@ -54,20 +56,51 @@ bundle exec ruby spec/client_examples/dynamic_acceptance.rb \
 ```
 
 Repeat with the retained Python sdist and a separate evidence directory. Replace
-artifact versions with the release being tested. The test installs the supplied
-packages without checkout imports, starts its disposable mounted fixture, extracts
-the code from the served HTML, compiles TypeScript with strict checking and runs
-the snippets with the installed clients. It checks discovery, Basic/existing
-token/OAuth credentials, a deterministic token challenge, success/failure and
-request receipts preserving exact names, path order, Unicode, nested Custom
-values, omission, null, empty strings, false and zero. Output and extracted
-programs remain in the evidence directory. The fixture stops and disposable
-consumer is removed when the operation exits.
+artifact versions with the release being tested. The harness installs the
+supplied packages without checkout imports and starts its disposable mounted
+fixture. It extracts examples from the overview, authentication and selected
+nested-resource pages, requesting thorough detail. Each group's escaped
+`data-example-details` map selects thorough when declared and Simple otherwise.
+Missing or malformed declarations, duplicate panels, limitations and missing
+code fail the run.
+
+The fixture selects exactly 36 panels: six variants, each with initialization,
+Basic, token, OAuth2, successful action and failed action. Eight callback
+JavaScript/TypeScript initialization and provider panels are Simple; the other
+28 are thorough. The harness compiles TypeScript with strict checking and runs
+the exact extracted code with the installed clients. It preserves source,
+including its stdout messages. This does not establish complete-program
+acceptance of all Simple action fragments.
+
+Checks cover discovery, Basic/existing token/OAuth credentials, a deterministic
+token challenge, success/failure and request receipts. Receipts preserve exact
+names, path order, Unicode, nested Custom values, omission, null, empty strings,
+false and zero. Output and extracted programs remain in the evidence directory.
+The fixture stops and the disposable consumer is removed when the operation
+exits.
 
 Each snippet's output is saved before completion checks, including nonzero
-exits. Token panels have separate `example-N-challenge.log` files for the login
-flow without an existing token. `fixture.log` records request method, path and
-HTTP status; the trace excludes headers, query strings and request bodies.
+exits. Each of the 36 programs has its own before/after receipt snapshot and
+saves its action/event delta beside the log. The six token-auth programs each
+complete their challenge flow in that run. The fixture receipt endpoint returns
+separate `actions` and `events` collections. Events contain only method, path,
+status, provider/authenticated state and token request/verification completion.
+They exclude credentials, tokens, challenge values, headers, queries and extra
+request bodies. `fixture.log` records method, path and status.
+
+Simple callback initialization and authentication code omits success-only
+stdout markers. Completion requires successful mounted/versioned OPTIONS
+discovery, authenticated through the expected provider where applicable.
+Anonymous discovery alone is insufficient for authentication examples. Each
+token program requires ordered request, verification and authenticated-discovery
+events from that run. The twelve protected action programs require existing-token
+authentication and discovery; challenge events cannot substitute for that proof.
+
+The harness requires stdout markers where the selected source emits them, and
+rejects failed callbacks or nonzero processes. Action samples retain exactly
+one receipt, exact path/input values and DOC_SUCCESS/DOC_FAILURE.
+`result.json` records group, variant and panel IDs with requested/effective
+detail for all 36 programs, including `challenge_completions: 6`.
 
 JavaScript list input and nested GET/OPTIONS query values produce a visible
 limitation; HEAD input retains the client's JSON body behavior. Python GET
@@ -79,5 +112,5 @@ methods produce a limitation. Required global or object input metadata also
 produces a limitation because the sample format has no metadata input channel.
 Optional metadata needs no invented values. Prose-only and incomplete samples do
 not become fabricated calls. Callback examples print the raw response; async
-examples use the actual invocation receipt. Operation waiting is shown only through the client's existing
-API, and a timeout is not a cancellation of the server operation.
+examples use the actual invocation receipt. Operation waiting uses the client's
+existing API; a timeout does not cancel the server operation.

data/spec/client_examples/dynamic_acceptance.rb

@@ -11,6 +11,7 @@ require_relative '../../test_support/dynamic_documentation_api'
 
 module DynamicDocumentationAcceptance
   VARIANTS = %w[javascript-callback javascript-async typescript-callback typescript-async python-sync python-async].freeze
+  PAGES = { overview: '', authentication: '?page=authentication', resource: '?resource=constructor.resources' }.freeze
 
   def self.run!(*command, chdir:, env: {}, log_path: nil)
     output, status = Open3.capture2e(env, *command, chdir:)
@@ -28,12 +29,150 @@ module DynamicDocumentationAcceptance
     response.body
   end
 
-  def self.extract(html)
-    html.scan(%r{<div id="([^"]+)">\s*<h[46]>[^<]*</h[46]>\s*<pre><code class="([^"]+)">(.*?)</code></pre>}m).filter_map do |id, language, escaped|
-      variant = VARIANTS.find { |name| id.end_with?("-#{name}") }
-      next unless variant
+  GROUPS = %w[init-examples auth-basic-examples auth-token-examples auth-oauth2-examples
+              example-constructor.resources-new-0-examples example-constructor.resources-new-1-examples].freeze
 
-      { id:, variant:, language:, source: CGI.unescapeHTML(escaped) }
+  class DetailMap < Hash
+    def []=(key, value)
+      raise "Duplicate example detail declaration: #{key}" if has_key?(key)
+
+      super
+    end
+  end
+
+  def self.attributes(source)
+    entries = source.scan(/([a-z][a-z0-9-]*)="([^"]*)"/)
+    raise 'Duplicate example HTML attribute' unless entries.map(&:first).uniq.length == entries.length
+
+    entries.to_h.transform_values { |value| CGI.unescapeHTML(value) }
+  end
+
+  def self.extract(html, detail: :thorough)
+    raise 'Invalid requested example detail' unless %i[simple thorough].include?(detail)
+
+    groups = html.scan(%r{<div\b([^>]*\bdata-example(?=\s|>)[^>]*)>(.*?)</div>}m)
+    raise 'Malformed example group' unless groups.length == html.scan(/<div\b[^>]*\bdata-example(?=\s|>)/).length
+
+    ids = []
+    groups.flat_map do |attributes, body|
+      group = self.attributes(attributes)
+      id = group.fetch('id')
+      raise "Duplicate example group: #{id}" if ids.include?(id)
+
+      ids << id
+      declarations = JSON.parse(group.fetch('data-example-details'), object_class: DetailMap)
+      unless declarations.is_a?(Hash) && declarations.all? do |client, levels|
+        client.is_a?(String) && [%w[simple], %w[simple thorough]].include?(levels)
+      end
+        raise "Invalid example detail declarations: #{id}"
+      end
+
+      actual = body.scan(%r{<details\b([^>]*\bdata-example-panel\b[^>]*)>(.*?)</details>}m)
+      VARIANTS.map do |variant|
+        levels = declarations.fetch(variant)
+        effective = levels.include?(detail.to_s) ? detail.to_s : 'simple'
+        variants = actual.select { |data, _code| self.attributes(data)['data-client'] == variant }
+        unless variants.map { |data, _code| self.attributes(data)['data-detail'] }.sort == levels.sort
+          raise "Missing, duplicate or undeclared example panels: #{id}/#{variant}"
+        end
+
+        data, code_body = variants.find { |data, _code| self.attributes(data)['data-detail'] == effective }
+        panel = self.attributes(data)
+        code = code_body.scan(%r{<pre><code class="([^"]+)">(.*?)</code></pre>}m)
+        unless code.length == 1 && code[0][0] == variant.split('-').first && !code_body.include?('class="client-limitation"')
+          raise "Expected one code panel: #{id}/#{variant}/#{effective}"
+        end
+
+        { group: id, id: panel.fetch('id'), variant:, language: code[0][0], requested_detail: detail,
+          detail: effective.to_sym, source: CGI.unescapeHTML(code[0][1]) }
+      end
+    end
+  end
+
+  def self.validate_coverage!(panels)
+    VARIANTS.each do |variant|
+      selected = panels.select { |panel| panel[:variant] == variant }
+      raise "Incomplete rendered coverage for #{variant}" unless selected.map { |panel| panel[:group] }.sort == GROUPS.sort
+
+      selected.each do |panel|
+        singleton = %w[javascript-callback typescript-callback].include?(variant) && !panel[:group].start_with?('example-')
+        expected = singleton ? :simple : :thorough
+        unless panel[:requested_detail] == :thorough && panel[:detail] == expected
+          raise "Unexpected effective example detail: #{panel[:group]}/#{variant}"
+        end
+      end
+    end
+    unless panels.length == 36 && panels.count { |panel| panel[:detail] == :simple } == 8 &&
+           panels.map { |panel| panel[:id] }.uniq.length == panels.length
+      raise 'Unexpected rendered panel matrix'
+    end
+  end
+
+  def self.receipt_delta(before, after)
+    unless [before, after].all? { |receipt| receipt.is_a?(Hash) && receipt.keys.sort == %w[actions events] && receipt.values.all?(Array) }
+      raise 'Invalid fixture receipt envelope'
+    end
+
+    before.to_h do |kind, previous|
+      current = after.fetch(kind)
+      raise 'Fixture receipts changed before the run boundary' unless current.take(previous.length) == previous
+
+      [kind, current.drop(previous.length)]
+    end
+  end
+
+  def self.authenticated_discovery(events, provider)
+    events.each_index.find do |index|
+      event = events[index]
+      request = event['type'] == 'request' && event['method'] == 'OPTIONS' && event['path'] == '/mount/v2/' &&
+                event['status'] == 200 && event['provider'] == provider && event['authenticated'] == !provider.nil?
+      request && (provider.nil? || events.take(index).any? do |previous|
+        previous['type'] == 'authentication' && previous['provider'] == provider && previous['authenticated'] == true
+      end)
+    end
+  end
+
+  def self.verify_completion!(panel, output, delta)
+    raise "Failed callback: #{panel[:id]}" if output.include?('Discovery or authentication failed')
+
+    actions = delta.fetch('actions')
+    events = delta.fetch('events')
+    if panel[:group].start_with?('example-')
+      raise "Rendered action did not execute once: #{panel[:id]}" unless actions.length == 1
+
+      receipt = actions.first
+      expected = { 'name' => '', 'enabled' => false, 'nullable' => nil, 'payload' => DynamicDocumentationAPI::PAYLOAD }
+      raise "Changed request values: #{receipt.inspect}" unless receipt['input'].except('count') == expected
+      raise 'Changed mounted path arguments' unless receipt['path'].map(&:to_s) == ['7', 'name with space']
+
+      count = panel[:group] == GROUPS.last ? -1 : 0
+      raise 'Changed sample success/failure input' unless receipt['input']['count'] == count
+
+      unless authenticated_discovery(events, 'token') && events.none? { |event| event['type'].start_with?('token_') }
+        raise "Existing-token action authentication did not complete: #{panel[:id]}"
+      end
+
+      marker = count < 0 ? 'DOC_FAILURE' : 'DOC_SUCCESS'
+      raise "Wrong result/error handling: #{panel[:id]}\n#{output}" unless output.include?(marker)
+    else
+      raise "Unexpected action during setup: #{panel[:id]}" unless actions.empty?
+
+      provider = panel[:group] == 'init-examples' ? nil : panel[:group].delete_prefix('auth-').delete_suffix('-examples')
+      discovery = authenticated_discovery(events, provider)
+      raise "Discovery/authentication did not complete: #{panel[:id]}" unless discovery
+
+      if provider == 'token'
+        sequence = events.map { |event| event['type'] }
+        request = sequence.index('token_request')
+        verification = sequence.index('token_verification')
+        unless provider == 'token' && request && verification && request < verification && verification < discovery
+          raise "Token challenge did not complete: #{panel[:id]}"
+        end
+      end
+      if panel[:detail] == :thorough
+        marker = provider ? 'Authenticated' : 'Discovery complete'
+        raise "Missing completion output: #{panel[:id]}\n#{output}" unless output.include?(marker)
+      end
     end
   end
 
@@ -63,31 +202,20 @@ module DynamicDocumentationAcceptance
             end
           end
           reader = Thread.new { File.write(File.join(output, 'fixture.log'), server_output.read) }
-          html = request("#{base}/mount/v2/")
-          File.write(File.join(output, 'documentation.html'), html)
-          panels = extract(html)
-          raise 'No actual HTML code panels extracted' if panels.empty?
-
-          VARIANTS.each do |variant|
-            selected = panels.select { |panel| panel[:variant] == variant }
-            raise "Incomplete rendered coverage for #{variant}" unless selected.length >= 4 &&
-                                                                       selected.any? { |panel| panel[:id].start_with?('init-') } &&
-                                                                       selected.any? { |panel| panel[:id].start_with?('auth-basic-') } &&
-                                                                       selected.count { |panel| panel[:id].start_with?('example-') } >= 2
+          panels = PAGES.flat_map do |page, query|
+            html = request("#{base}/mount/v2/#{query}")
+            File.write(File.join(output, "documentation-#{page}.html"), html)
+            extract(html)
           end
+          validate_coverage!(panels)
+          executions = []
           panels.each_with_index do |panel, index|
             extension = { 'typescript' => '.ts', 'javascript' => '.mjs', 'python' => '.py' }.fetch(panel[:language])
             name = "example-#{index}#{extension}"
             path = File.join(consumer, name)
             File.write(path, panel[:source])
             File.write(File.join(output, name), panel[:source])
-            env = { 'NODE_PATH' => nil, 'PYTHONPATH' => nil, 'PYTHONHOME' => nil,
-                    'HAVEAPI_USER' => 'fixture-user', 'HAVEAPI_PASSWORD' => 'fixture-password',
-                    'HAVEAPI_TOKEN' => 'fixture-token', 'HAVEAPI_ACCESS_TOKEN' => 'fixture-access-token',
-                    'HAVEAPI_AUTH_user' => JSON.generate('fixture-user'),
-                    'HAVEAPI_AUTH_password' => JSON.generate('fixture-password'),
-                    'HAVEAPI_AUTH_lifetime' => JSON.generate('fixed'),
-                    'HAVEAPI_AUTH_scope' => JSON.generate('all'), 'HAVEAPI_CHALLENGE_code' => JSON.generate('123456') }
+            env = { 'NODE_PATH' => nil, 'PYTHONPATH' => nil, 'PYTHONHOME' => nil }
             if extension == '.ts'
               config = {
                 compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', strict: true,
@@ -104,29 +232,21 @@ module DynamicDocumentationAcceptance
             end
             before = JSON.parse(request("#{base}/__acceptance_receipts"))
             command = panel[:language] == 'python' ? [python, path] : ['node', path]
-            result = run!(*command, chdir: consumer, env:, log_path: File.join(output, "example-#{index}.log"))
-            if panel[:id].start_with?('auth-token-')
-              challenge_result = run!(*command, chdir: consumer, env: env.merge('HAVEAPI_TOKEN' => nil),
-                                                log_path: File.join(output, "example-#{index}-challenge.log"))
-              raise "Token challenge did not complete: #{panel[:id]}\n#{challenge_result}" unless challenge_result.include?('Authenticated')
-            end
-            after = JSON.parse(request("#{base}/__acceptance_receipts"))
-            if panel[:id].start_with?('example-')
-              raise "Rendered action did not execute: #{panel[:id]}\n#{result}" unless after.length == before.length + 1
-
-              receipt = after.last
-              expected = { 'name' => '', 'enabled' => false, 'nullable' => nil, 'payload' => DynamicDocumentationAPI::PAYLOAD }
-              raise "Changed request values: #{receipt.inspect}" unless receipt['input'].except('count') == expected
-              raise 'Changed mounted path arguments' unless receipt['path'].map(&:to_s) == ['7', 'name with space']
-
-              marker = receipt['input']['count'] < 0 ? 'DOC_FAILURE' : 'DOC_SUCCESS'
-              raise "Wrong result/error handling: #{panel[:id]}\n#{result}" unless result.include?(marker)
-            else
-              marker = panel[:id].start_with?('init-') ? 'Discovery complete' : 'Authenticated'
-              raise "Discovery/authentication did not complete: #{panel[:id]}\n#{result}" unless result.include?(marker)
+            begin
+              result = run!(*command, chdir: consumer, env:, log_path: File.join(output, "example-#{index}.log"))
+            ensure
+              after = JSON.parse(request("#{base}/__acceptance_receipts"))
+              delta = receipt_delta(before, after)
+              File.write(File.join(output, "example-#{index}-receipts.json"), JSON.pretty_generate(delta))
             end
+            verify_completion!(panel, result, delta)
+            executions << panel.except(:source).merge(challenge_completion: panel[:group] == 'auth-token-examples')
           end
-          File.write(File.join(output, 'result.json'), JSON.pretty_generate({ panels: panels.length, variants: VARIANTS, status: 'passed' }))
+          raise 'Incomplete token challenge coverage' unless executions.count { |execution| execution[:challenge_completion] } == VARIANTS.length
+
+          File.write(File.join(output, 'result.json'), JSON.pretty_generate({ panels: panels.length, variants: VARIANTS,
+                                                                              details: panels.group_by { |panel| panel[:detail] }.transform_values(&:length),
+                                                                              challenge_completions: VARIANTS.length, executions:, status: 'passed' }))
         ensure
           Process.kill('TERM', wait.pid) if wait.alive?
           wait.value