Documentation
¶
Overview ¶
Package codextest provides a reusable Codex SQLite + rollout-files fixture builder for tests across the codebase (pkg/provider, pkg/sync, pkg/daemon, cmd). It writes a minimal version of Codex's state schema (just the columns `threads` + `thread_spawn_edges` that the CLI queries) to a fresh tmp directory, exposes builder methods for adding root and subagent rollouts, and points the CLI's Codex-state lookups at the fixture via CONFAB_CODEX_DIR.
The fixture's schema intentionally mirrors only what the CLI reads — Codex's real schema is larger and evolves; tracking it column-for-column in tests would couple us to upstream changes that don't affect us.
Index ¶
- type Fixture
- func (f *Fixture) AddRoot(threadUUID string) *RolloutBuilder
- func (f *Fixture) AddSubagent(parentUUID, threadUUID string, opts SubagentOpts) *RolloutBuilder
- func (f *Fixture) AddSubagentNoEdge(_ *testing.T, threadUUID string, opts SubagentOpts) *RolloutBuilder
- func (f *Fixture) DB() *sql.DB
- func (f *Fixture) DeleteRolloutFile(threadUUID string)
- func (f *Fixture) InsertEdgeLater(parentUUID, childUUID string, delay time.Duration)
- type RolloutBuilder
- func (b *RolloutBuilder) Path() string
- func (b *RolloutBuilder) ThreadUUID() string
- func (b *RolloutBuilder) WithLegacyUserMessage(msg string) *RolloutBuilder
- func (b *RolloutBuilder) WithRawLine(line string) *RolloutBuilder
- func (b *RolloutBuilder) WithSessionMeta(cwd string) *RolloutBuilder
- func (b *RolloutBuilder) WithUserMessage(msg string) *RolloutBuilder
- type SubagentOpts
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Fixture ¶
type Fixture struct {
Dir string
StateDBPath string
SessionsDir string
// contains filtered or unexported fields
}
Fixture is a temporary Codex directory layout with a state DB and a sessions tree, scoped to a single test. The CONFAB_CODEX_DIR env var points at the fixture for the duration of the test.
func NewFixture ¶
NewFixture creates a tmp Codex directory, initializes the state DB with the minimal schema, sets CONFAB_CODEX_DIR for the test, and resets the provider's cached state-DB path so the fixture is picked up immediately.
All resources are cleaned up via t.Cleanup.
func (*Fixture) AddRoot ¶
func (f *Fixture) AddRoot(threadUUID string) *RolloutBuilder
AddRoot inserts a row into `threads` representing a user-initiated (root) thread with `thread_source='user'`, and creates an empty rollout JSONL file under SessionsDir. Returns a RolloutBuilder for chaining.
func (*Fixture) AddSubagent ¶
func (f *Fixture) AddSubagent(parentUUID, threadUUID string, opts SubagentOpts) *RolloutBuilder
AddSubagent inserts a thread row with agent_* metadata and an edge from parentUUID → threadUUID in thread_spawn_edges. The rollout JSONL file is created as empty; chain WithSessionMeta/WithLines to populate it.
func (*Fixture) AddSubagentNoEdge ¶
func (f *Fixture) AddSubagentNoEdge(_ *testing.T, threadUUID string, opts SubagentOpts) *RolloutBuilder
AddSubagentNoEdge inserts a subagent-tagged thread row WITHOUT a parent edge. Used by edge-race tests to model the window where Codex has committed the new subagent's `threads` row but not yet committed the matching `thread_spawn_edges` row. Pair with InsertEdgeLater to add the edge after a delay (or omit to model "edge never appears").
func (*Fixture) DB ¶
DB returns the underlying *sql.DB so tests can insert custom rows that don't fit the builder pattern. Use sparingly.
func (*Fixture) DeleteRolloutFile ¶
DeleteRolloutFile removes the rollout JSONL but leaves the threads row in place, so tests can exercise the "DB references a missing file" branch inside ListSubtree's verification.
func (*Fixture) InsertEdgeLater ¶
InsertEdgeLater schedules a parent→child edge insert after the given delay. Used by WalkUpToRoot retry tests to simulate the spawn-vs-edge race where the hook fires before Codex commits the edge.
The goroutine inherits the fixture's t and will t.Errorf on failure rather than crashing the test runner.
type RolloutBuilder ¶
type RolloutBuilder struct {
// contains filtered or unexported fields
}
RolloutBuilder is a small fluent helper for populating a rollout JSONL after the row has been registered in the threads table.
func (*RolloutBuilder) Path ¶
func (b *RolloutBuilder) Path() string
Path returns the absolute rollout file path on disk.
func (*RolloutBuilder) ThreadUUID ¶
func (b *RolloutBuilder) ThreadUUID() string
ThreadUUID returns the rollout's owning thread ID.
func (*RolloutBuilder) WithLegacyUserMessage ¶ added in v0.17.4
func (b *RolloutBuilder) WithLegacyUserMessage(msg string) *RolloutBuilder
WithLegacyUserMessage appends the user-message line in the shape Codex emitted before ~0.149.1: event_msg / payload.type "user_message" with a flat `message` string. Transcribed from a real 0.130.0 rollout.
Rollouts in this shape are still on disk on user machines, so the CLI must keep parsing them; this builder keeps that path covered.
func (*RolloutBuilder) WithRawLine ¶
func (b *RolloutBuilder) WithRawLine(line string) *RolloutBuilder
WithRawLine appends a raw JSON line verbatim. Use for testing malformed session_meta payloads or unexpected line types.
func (*RolloutBuilder) WithSessionMeta ¶
func (b *RolloutBuilder) WithSessionMeta(cwd string) *RolloutBuilder
WithSessionMeta writes a `session_meta` JSONL line at the start of the rollout. The CLI's IsUserSession / agent-rollout filtering reads this line to verify the rollout's role.
No `model` key is written: Codex's SessionMeta has no model field in any version (only `model_provider`), so a fixture that emitted one would let tests assert a value production can never see.
func (*RolloutBuilder) WithUserMessage ¶
func (b *RolloutBuilder) WithUserMessage(msg string) *RolloutBuilder
WithUserMessage appends the user-message line in the shape Codex emits today (>= 0.149.1): event_msg / payload.type "item_completed" carrying an item of type "UserMessage" whose prompt text lives in typed content parts. Transcribed from a real 0.154.0 rollout.
Use WithLegacyUserMessage for the retired pre-0.149 shape.
Source Files