Skip to content

feat: publish a stateful fake dokku for embedder tests - #666

Merged
josegonzalez merged 3 commits into
mainfrom
650-dokkutest
Oct 22, 2026
Merged

josegonzalez merged 3 commits into
mainfrom
650-dokkutest

Conversation

@josegonzalez

Copy link
Copy Markdown
Member

The new sdk/dokkutest package is a stateful fake dokku. It holds apps, config, domains, ports, buildpacks, process scale, plugin properties and datastore services with their info and links, answers the commands the core tasks send in the formats their probes parse, applies their changes, records every call, and fails any command it does not model with an error naming it and a failed test. It covers dokku_app, dokku_config, dokku_domains, dokku_ports, dokku_buildpacks, dokku_ps_scale, every property-table dokku_*_property task, dokku_service_create and dokku_service_link, plus the version gate and the parent app or service probes. Handle, HandlePrefix and Fallback answer anything else, and Exit and Unavailable fail a command the way dokku or a missing binary would.

A test drives each covered type through create, refresh (ReadTask and ReadAddress) and destroy, asserting on the resulting state, and a guard test plans, applies, reads and exports every catalog example of every covered task against a seeded fake, failing on any command it does not model. The Makefile and CI test lines now cover ./sdk/..., and the "Testing without a server" section of docs/embedding.md and the sdk package doc describe the fake.

The second commit moves docket's own fakes onto it: the sdk tests and examples that scripted dokku's answers, and the internal/tasks observed fixtures for the tasks the fake models. Failure cases answer the one command they fail with a handler. The observed fixtures for tasks the fake does not model keep their scripted responses, and ExampleContextWithRunner keeps its hand-written runner since it documents that seam.

The fake's engine lives in internal/fakedokku, importing only internal/subprocess, and sdk/dokkutest aliases it and reads the property tables from sdk.Catalog(). A package that imports sdk cannot be used by the in-package tests of internal/tasks without an import cycle, so the engine could not sit in sdk/dokkutest itself. A missing app answers with dokku's exit code 20, as the dokku 0.38.31 devcontainer does, and the fake adds no domains or links on its own.

Closes #650

The task catalog now publishes a `lifecycle` per task naming the state that applies its resource and the state that tears it down, and the sdk exposes it as `sdk.TaskLifecycle` alongside `sdk.TaskInState`, which moves a task into a state with the fields that state refuses reset to their defaults. Apply is `set` when offered and the state's default otherwise, teardown is `clear`, else `absent`, and imperative tasks have none. `dokku_storage_ensure` is the one exception: it offers `absent` but refuses it, so it declares no teardown. Each task's reference page now shows its lifecycle.
@josegonzalez josegonzalez added the enhancement New feature or request label Oct 22, 2026
The new `sdk/dokkutest` package holds apps, config, domains, ports, buildpacks, process scale, plugin properties and datastore services, answers the commands the core tasks send in the formats their probes parse, applies their changes, records every call, and fails any command it does not model. A test drives every covered task type through create, refresh and destroy against it, and another runs every catalog example of those tasks so the fake stays in step with the probes.
The sdk tests and examples that scripted dokku's answers, and the observed fixtures for the tasks the fake models, now seed a fake server instead, so they stay in step with the probes. Failure cases answer the one command they fail with a handler, and the observed fixtures for tasks the fake does not model keep their scripted responses.
@josegonzalez
josegonzalez changed the base branch from main to 640-task-lifecycle October 22, 2026 03:48
@josegonzalez
josegonzalez changed the base branch from 640-task-lifecycle to main October 22, 2026 03:48
@josegonzalez
josegonzalez merged commit 96ac8ce into main Oct 22, 2026
22 checks passed
@josegonzalez
josegonzalez deleted the 650-dokkutest branch October 22, 2026 04:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: publish a stateful fake dokku for embedder tests

1 participant