Documentation
¶
Overview ¶
Package facadetest provides a scriptable test double (fake) for the ports.WorkflowFacade and ports.RunSession interfaces.
Overview ¶
facadetest is the third member of the AWF testutil family alongside internal/testutil/mocks (thread-safe port mocks) and internal/testutil/builders (fluent object builders). Its purpose is different: instead of recording or stubbing individual method calls, it lets a test script a complete event sequence that a FakeSession will emit in order, including synchronization points where the session pauses until the consumer calls Respond.
Architecture ¶
The Fake struct implements ports.WorkflowFacade. FakeSession implements ports.RunSession.
Design decisions:
- D37: New testutil sub-packages get doc.go per CLAUDE.md convention.
- D38: Builder-style API allows all consumer packages (CLI, API, ACP, conformance suite) to share one fake rather than defining per-package inline doubles.
The package depends only on:
- internal/domain/ports — the interface contract Fake and FakeSession satisfy.
- internal/application — MapError for ErrorCode mapping in WithTerminalFailed.
It does NOT depend on the production FacadeAdapter (internal/interfaces/facade). Depending on the adapter would create a compilation cycle and block the parallel build of T064 and T058.
Event Channel Lifecycle ¶
Each call to Fake.Run creates a fresh FakeSession with its own buffered event channel, sized to len(script)+1 to avoid blocking the pump goroutine. The pump goroutine sends events in order and exits (closing the channel) after:
- a terminal event (EventWorkflowCompleted or EventWorkflowFailed) is sent, or
- the context is cancelled, or
- FakeSession.Close is called.
The events channel is always closed before Close returns, so reading from sess.Events() after sess.Close() immediately yields the zero value and false.
Builder API ¶
Construct a Fake with the New() constructor and chain builder methods:
f := facadetest.New().
Script(
ports.Event{Kind: ports.EventRunStarted, Seq: 1},
ports.Event{Kind: ports.EventStepStarted, Seq: 2},
).
WithTerminalCompleted()
Builder methods:
Script(events ...ports.Event) — append raw events to the script. WithTerminalCompleted() — append EventWorkflowCompleted (terminal, closes channel). WithTerminalFailed(err error) — append EventWorkflowFailed with the application.MapError(err) ErrorCode as the event Payload. WithInputRequired(req ports.InputRequest) — append EventInputRequired with req as Payload. The pump goroutine pauses after emitting this event and resumes only when FakeSession.Respond is called. WithHistory(records ...ports.RunRecord) — seed records returned by Fake.History; useful for testing history-display code paths.
Respond Synchronization ¶
When the scripted sequence contains an EventInputRequired event, the ordering contract is:
- Consumer reads EventInputRequired from sess.Events().
- No further event is available on the channel (pump is blocked).
- Consumer calls sess.Respond(ports.InputResponse{...}).
- Pump unblocks and emits the next scripted event.
This models the real FacadeAdapter behavior where the workflow is paused awaiting user input.
Integration with the Conformance Suite ¶
T065 builds a cross-interface conformance suite that exercises all consumer packages (CLI, TUI, HTTP API, ACP) against a single shared Fake. Each consumer test creates a Fake with the scenario under test, calls the consumer entry-point, and asserts the resulting output or state.
Import path:
import "github.com/awf-project/cli/internal/testutil/facadetest"
Contract Compliance ¶
Fake satisfies the five-point port contract verified by internal/domain/ports/facade_contract_test.go:
- Close is idempotent (multiple calls return nil).
- Events channel is closed after Close.
- Run with empty Identifier returns ports.ErrInvalidRequest.
- Run with a cancelled context propagates the context error.
- Respond after Close returns ports.ErrSessionClosed.
TestFakeFacade_SatisfiesPortContract in facadetest_test.go re-runs these five assertions against Fake and FakeSession directly.
Thread Safety ¶
Fake is safe for concurrent calls to Run, History, and the builder methods. Each FakeSession is an independent instance; multiple sessions created from the same Fake do not share state.
FakeSession.Respond and FakeSession.Close are thread-safe and may be called concurrently with Events().
Index ¶
- type Fake
- func (f *Fake) History(_ context.Context, _ ports.HistoryFilter) ([]ports.RunRecord, error)
- func (f *Fake) List(_ context.Context) ([]ports.WorkflowSummary, error)
- func (f *Fake) Resume(ctx context.Context, req ports.ResumeRequest) (ports.RunSession, error)
- func (f *Fake) Run(ctx context.Context, req ports.RunRequest) (ports.RunSession, error)
- func (f *Fake) Script(events ...ports.Event) *Fake
- func (f *Fake) Status(_ context.Context, _ string) (ports.RunStatus, error)
- func (f *Fake) Validate(_ context.Context, _ ports.RunRequest) (ports.ValidationReport, error)
- func (f *Fake) WithHistory(records ...ports.RunRecord) *Fake
- func (f *Fake) WithInputRequired(req ports.InputRequest) *Fake
- func (f *Fake) WithTerminalCompleted() *Fake
- func (f *Fake) WithTerminalFailed(err error) *Fake
- type FakeSession
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Fake ¶
type Fake struct {
// contains filtered or unexported fields
}
Fake is a scriptable test double for ports.WorkflowFacade. Use New() to construct, then chain Script/With* builder methods before calling Run.
func (*Fake) Resume ¶
func (f *Fake) Resume(ctx context.Context, req ports.ResumeRequest) (ports.RunSession, error)
Resume returns a live FakeSession seeded from req.RunID with no scripted events. The session's Events() channel closes immediately (empty script). req.InputOverrides and req.FromStep satisfy the ports.WorkflowFacade contract but are not used by the fake — it always emits the scripted sequence regardless.
func (*Fake) Run ¶
func (f *Fake) Run(ctx context.Context, req ports.RunRequest) (ports.RunSession, error)
Run creates a FakeSession that emits the scripted event sequence. Returns ErrInvalidRequest if req.Identifier is empty. Always succeeds even if ctx is already cancelled — the scripted events are emitted unconditionally.
func (*Fake) Validate ¶
func (f *Fake) Validate(_ context.Context, _ ports.RunRequest) (ports.ValidationReport, error)
Validate returns a valid ValidationReport (zero-value stub).
func (*Fake) WithHistory ¶
WithHistory appends records to the scriptable history returned by History.
func (*Fake) WithInputRequired ¶
func (f *Fake) WithInputRequired(req ports.InputRequest) *Fake
WithInputRequired appends an EventInputRequired event with req as Payload. The FakeSession will pause after emitting this event until Respond is called.
func (*Fake) WithTerminalCompleted ¶
WithTerminalCompleted appends an EventWorkflowCompleted terminal event.
func (*Fake) WithTerminalFailed ¶
WithTerminalFailed appends an EventWorkflowFailed terminal event. The Payload is *ports.EnrichedTerminal carrying the error message, matching the production emitTerminalEvent behavior. All consumers type-assert to *ports.EnrichedTerminal, so the fake must emit the same concrete type (B1).
type FakeSession ¶
type FakeSession struct {
// contains filtered or unexported fields
}
FakeSession emits scripted events on Events() in order. After EventInputRequired, the next event is withheld until Respond is called. Terminal events (EventWorkflowCompleted, EventWorkflowFailed) close the channel.
func (*FakeSession) Close ¶
func (s *FakeSession) Close() error
Close stops event emission and waits for the pump goroutine to exit. Idempotent: multiple calls return nil without panicking.
func (*FakeSession) Events ¶
func (s *FakeSession) Events() <-chan ports.Event
Events returns the channel of scripted events. The channel is closed after a terminal event, context cancellation, or Close.
func (*FakeSession) ID ¶
func (s *FakeSession) ID() string
ID returns the session identifier derived from RunRequest.Identifier.
func (*FakeSession) Respond ¶
func (s *FakeSession) Respond(_ ports.InputResponse) error
Respond unblocks the pump goroutine after an EventInputRequired event. Returns ErrSessionClosed if the session is already closed.
func (*FakeSession) StatusSnapshot ¶
func (s *FakeSession) StatusSnapshot() ports.RunStatus
StatusSnapshot derives a coarse status from the scripted events, mirroring *application.RunSession.StatusSnapshot so interface-layer status overlays (e.g. the HTTP GET /executions/{id} handler) can be exercised against the fake.