Test Infrastructure

Table of Contents

• Overview
• Test Struct & Bootstrapping
• Component Reference
  • Storyteller sup/lib/storyteller/storyteller.go
  • Asserter sup/lib/asserter/asserter.go
  • WebDriver sup/lib/web_driver/web_driver.go
  • GrownStater sup/srv/staters/grown_stater.go
  • WebDriverAsserter sup/lib/asserter/web_driver_asserter.go
  • SupFilesystem sup/lib/support/sup_filesystem.go
  • Logger src/lib/logger/logger.go
  • WebServer src/lib/web_server/web_server.go
• How They Work Together
• Annotated Skeleton Test

Overview

The test stack combines BDD narrative, browser automation, an isolated in-memory database, and an in-memory filesystem.

All components are injected via a single call to helpers.SetupTest.

Test Struct & Bootstrapping

type MyTest struct {
    Storyteller       *storyteller.Storyteller
    Asserter          *asserter.Asserter
    WebDriver         *web_driver.WebDriver
    WebServer         *web_server.WebServer
    GrownStater       *staters.GrownStater
    WebDriverAsserter *asserter.WebDriverAsserter
    SupFilesystem     *support.SupFilesystem
    Logger            *logger.Logger
}
helpers.SetupTest(this, testing)
ctx := helpers.SetupTest(this, testing)

• Creates an isolation scene: in-memory SQLite, memory filesystem, mock exec/HTTP client, deterministic time.
• Uses reflection to walk every exported field of this and resolves it from the DI Container/Canister by field name
• Returns a context.Context that carries *testing.T
• Rule: Every field in the test struct must be a pointer or interface. Struct-valued fields are skipped by the resolver.

Component Reference

Storyteller sup/lib/storyteller/storyteller.go

Storyteller`s sole purpose is to produce an easy-to-read test output.

If SUP_STORYTELLER_WRITER ENV variable is set to file, it writes the output in docs/stories/FILE_PATH.txt

Note that it does NOT perform any actual test action.

Note: Consecutive calls of the same kind (Given, When, Then) are auto-prefixed in the output with “And”.

• Rule: Call SetAutoScenario or SetScenario before any other narrative method.

Asserter sup/lib/asserter/asserter.go

Purpose: Low-level value assertions for non-browser tests.

All methods take ctx context.Context as their first argument.

On failure: writes tmp/last-test-fail.json, logs to the console with a caller link, and calls t.FailNow().

Port: read from the PORT environment variable; falls back to 8032.

WebDriver sup/lib/web_driver/web_driver.go

Purpose: Browser automation via ChromeDP. Also manages the WebServer lifecycle.

Note: Must variants don’t return errors but panic instead.

• Session management

• Navigation & waiting

• Interaction

• Reading page state

• Utilities

Rule: The session must be started before any other WebDriver call. The driver panics if Data.Initialized == false.

GrownStater sup/srv/staters/grown_stater.go

Purpose: Populates the in-memory database with a realistic application ecosystem before the browser session starts.

Rule: Call GrownStater.GoToDefaultStage before WebDriver.StartSession so that data exists when the HTTP server begins serving requests.

WebDriverAsserter sup/lib/asserter/web_driver_asserter.go

Purpose: Browser-aware assertions — waits first, then asserts; takes a screenshot on failure.

ARIA role constants are in the gitlab.com/blue-lila/kitcla/aria package (e.g. aria.AriaRoleButton, aria.AriaRoleHeading).

Failure reporting delegates to Asserter.MakeReport, so the same JSON report file and t.FailNow() flow applies as with the plain Asserter.

SupFilesystem sup/lib/support/sup_filesystem.go

Purpose: Thin wrapper around OperatingSystemIpl. During isolated tests this is backed by an in-memory mock, so filesystem operations never touch the real disk.

• Path helpers

• File operations

• Environment operations

Rule: Prefer Must* variants in test bodies to fail fast on unexpected OS errors.

Logger src/lib/logger/logger.go

Purpose: Structured, contextual logging shared by all components.

Levels: Debug, Info, Warn, Error.

Note: It is rare to call Logger directly in tests: components use it internally. It is useful when tracing unexpected behavior: this.Logger.Info(ctx, "debug marker")

WebServer src/lib/web_server/web_server.go

Purpose: Wraps net/http.Server together with the Gin router.

Note: Test authors do not call WebServer directly — its lifecycle is managed by WebDriver.StartSession and WebDriver.StopSession.

How They Work Together

• Key coupling points

StartSession returns a new context — always reassign: ctx = this.WebDriver.StartSession(ctx)

GrownStater must run before StartSession so the HTTP server serves real data on the very first request.

WebDriverAsserter delegates to Asserter — failure produces the same JSON report file and t.FailNow() call as a plain Asserter failure.

Annotated Skeleton Test

A minimal working acceptance test showing the correct call order:

package my_feature

import (
    "__PROJECT_NAME__/src/lib/logger"
    "__PROJECT_NAME__/src/lib/web_server"
    "__PROJECT_NAME__/sup/helpers"
    "__PROJECT_NAME__/sup/lib/asserter"
    "__PROJECT_NAME__/sup/lib/storyteller"
    "__PROJECT_NAME__/sup/lib/support"
    "__PROJECT_NAME__/sup/lib/web_driver"
    "__PROJECT_NAME__/sup/srv/staters"
    "testing"

    "gitlab.com/blue-lila/kitcla/aria"
)

type MyFeatureTest struct {
    Storyteller       *storyteller.Storyteller
    Asserter          *asserter.Asserter
    WebDriver         *web_driver.WebDriver
    WebServer         *web_server.WebServer
    GrownStater       *staters.GrownStater
    WebDriverAsserter *asserter.WebDriverAsserter
    SupFilesystem     *support.SupFilesystem
    Logger            *logger.Logger
}

func TestMyFeature(testing *testing.T) {
    this := &MyFeatureTest{}
    ctx := helpers.SetupTest(this, testing)
    this.Storyteller.SetAutoScenario(ctx)

    this.Storyteller.As("User")
    this.Storyteller.Given("a grown state")
    this.GrownStater.GoToDefaultStage(ctx)

    this.Storyteller.Given("a web session")
    ctx = this.WebDriver.StartSession(ctx)
    defer func() { this.WebDriver.StopSession(ctx) }()

    this.Storyteller.When("I navigate to the home page")
    this.WebDriver.MustNavigate(ctx, "/app")
    this.WebDriver.MustWaitForText(ctx, "Home")

    this.Storyteller.Then("I see the Home header")
    this.WebDriverAsserter.AssertText(ctx, "Home")
    this.WebDriverAsserter.AssertTextOn(ctx, "Home", aria.AriaRoleHeading)
}