ObanCodex.Testing (oban_codex v0.1.0)

Copy Markdown View Source

Build deterministic Codex outcomes for worker tests without invoking the CLI.

The helpers encode the same JSONL events ObanCodex reads in production, so tests exercise text/1, structured/1, session_id/1, and usage/1 rather than relying on a parallel fake result representation.

import ObanCodex.Testing

assert {:ok, result} =
         ObanCodex.run(%{"prompt" => "x"}, query_fun: respond("done"))

assert ObanCodex.text(result) == "done"

result = structured_result(%{"outcome" => "blocked"}, session_id: "thread-1")
assert ObanCodex.outcome(result) == "blocked"
assert ObanCodex.session_id(result) == "thread-1"

Summary

Types

failable()

A normalized error struct or shorthand error kind.

respondable()

A result struct or shorthand final-message string.

Functions

error(kind, opts \\ [])

Build a normalized pre-result execution error.

fail(error)

Return a query function that always fails before producing a CLI result.

failed_result(output \\ "codex command failed", opts \\ [])

Build a completed non-zero Codex result.

respond(response)

Return a query function that always succeeds.

result(text_or_opts \\ "")

Build a successful %CodexWrapper.Result{} with realistic JSONL stdout.

result(text, opts)

Build a result from final-message text plus keyword options.

sequence(values)

Return each scripted result/error in sequence, raising after exhaustion.

structured_result(data, opts \\ [])

Build a successful result whose final message is JSON-encoded structured data.

Types

failable()

@type failable() :: ObanCodex.Error.t() | atom()

A normalized error struct or shorthand error kind.

respondable()

@type respondable() :: CodexWrapper.Result.t() | String.t()

A result struct or shorthand final-message string.

Functions

error(kind, opts \\ [])

@spec error(
  atom(),
  keyword()
) :: ObanCodex.Error.t()

Build a normalized pre-result execution error.

fail(error)

@spec fail(failable()) :: ObanCodex.query_fun()

Return a query function that always fails before producing a CLI result.

failed_result(output \\ "codex command failed", opts \\ [])

@spec failed_result(
  String.t(),
  keyword()
) :: CodexWrapper.Result.t()

Build a completed non-zero Codex result.

This models CLI failures such as authentication or invalid config, which the wrapper returns as %Result{success: false} rather than {:error, reason}.

respond(response)

@spec respond(respondable()) :: ObanCodex.query_fun()

Return a query function that always succeeds.

result(text_or_opts \\ "")

@spec result(String.t() | keyword()) :: CodexWrapper.Result.t()

Build a successful %CodexWrapper.Result{} with realistic JSONL stdout.

A string is shorthand for the final agent message. Keyword options:

  • :text / :result — final agent message (:result is a parity alias)
  • :session_id — emitted as the thread_id
  • :usage — map emitted on turn.completed
  • :stderr — raw stderr
  • :events — additional raw event maps inserted before turn.completed

result(text, opts)

@spec result(
  String.t(),
  keyword()
) :: CodexWrapper.Result.t()

Build a result from final-message text plus keyword options.

sequence(values)

@spec sequence([respondable() | failable()]) :: ObanCodex.query_fun()

Return each scripted result/error in sequence, raising after exhaustion.

Strings become successes, atoms become normalized errors, and prebuilt %Result{} / %Error{} structs retain their sense.

structured_result(data, opts \\ [])

@spec structured_result(
  map() | list(),
  keyword()
) :: CodexWrapper.Result.t()

Build a successful result whose final message is JSON-encoded structured data.