Module: ClaudeAgentSDK::Testing

Defined in:
lib/claude_agent_sdk/testing/session_store_conformance.rb

Overview

Test helpers shipped in the gem for third-party SessionStore adapter authors.

Defined Under Namespace

Classes: ConformanceError

Constant Summary collapse

OPTIONAL_METHODS = 
%w[list_sessions list_session_summaries delete list_subkeys].freeze

Class Method Summary collapse

Class Method Details

.run_session_store_conformance(make_store, skip_optional: []) ⇒ Object

Assert the 15 SessionStore behavioral contracts against an adapter.

Framework-agnostic: raises ConformanceError on the first violated contract, otherwise returns nil. Call it from any test framework, e.g.

it 'conforms' do
  ClaudeAgentSDK::Testing.run_session_store_conformance(-> { MyStore.new })
end

Parameters:

  • make_store (#call) —

    invoked once per contract to provide isolation; returns a fresh SessionStore (or duck-typed adapter).

  • skip_optional (Array<String>) (defaults to: []) —

    optional method names to skip. Contracts for an optional method are also skipped automatically when the store does not override it.

Raises:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/claude_agent_sdk/testing/session_store_conformance.rb', line 30

def run_session_store_conformance(make_store, skip_optional: [])
  skip_optional = skip_optional.map(&:to_s)
  invalid = skip_optional - OPTIONAL_METHODS
  raise ConformanceError, "unknown optional methods in skip_optional: #{invalid}" unless invalid.empty?

  fresh = -> { make_store.call }

  probe = fresh.call
  has_list_sessions = optional?(probe, 'list_sessions', skip_optional)
  has_list_summaries = optional?(probe, 'list_session_summaries', skip_optional)
  has_delete = optional?(probe, 'delete', skip_optional)
  has_list_subkeys = optional?(probe, 'list_subkeys', skip_optional)

  check_append_and_load(fresh, has_list_sessions)
  check_list_sessions(fresh) if has_list_sessions
  check_list_session_summaries(fresh, has_list_sessions, has_delete) if has_list_summaries
  check_delete(fresh, has_list_subkeys, has_list_sessions) if has_delete
  check_list_subkeys(fresh) if has_list_subkeys
  nil
end