Files
coder/coderd/templatebuilder_handler_test.go
T
Nick Vigilante c78dca5141 feat: add Coder Quickstart base to the template builder (#27247)
## Summary

Adds the **Coder Quickstart** template as a selectable base in the
[template builder](coderd/templatebuilder) guided wizard. It is a
Docker-based starter that lets a user pick languages and optionally
clone a repo.

## What changed

- **New base package** `coderd/templatebuilder/bases/quickstart/`:
- `base.json`: `id: "quickstart"`, `display_name: "Coder Quickstart"`,
`os: "linux"`.
- `main.tf.tmpl`: a Docker workspace with a language selector, a single
language-install script, an optional Git clone, and workspace presets.
Editors are added via the builder's module step rather than baked into
the base.
- `install-languages.sh.tftpl` and `README.md` (with prerequisites
markers so the builder can extract the prerequisites section).
- **Placement**: the bases endpoint returns a plain list sorted by
display name (with ID as a deterministic tiebreak). The wizard's
base-infra select step prioritizes the Quickstart and Docker starters to
the front on the client, mirroring the existing client-side module
prioritization in `ModuleSelectStep` (shared `sortByPriority` helper).
- **Base/module collision guard**: a base's bundled catalog modules are
derived from its rendered Terraform (`ExtractModuleNames`, cached with
`sync.OnceValues` and filtered to catalog IDs). `validateModules` seeds
its seen-set from that derived set, so a wizard-selected module the base
already renders is rejected with a clear error, and the modules endpoint
omits it so the wizard never offers a colliding module. The base's
Terraform is the single source of truth, so there is no separate
manifest list that can drift.

## Testing

- `go test ./coderd/` (template builder handler: bases ordering, the
`baseSpec` table, the modules-endpoint base filter): pass.
- `go test ./coderd/templatebuilder/` (all-bases render/snapshot, the
collision guard, `TestBaseIncludedModules`, the selector/install-script
drift test): pass.
- `gofmt`, `go vet`, `golangci-lint`: clean.
- Frontend `tsc`, `biome`, and `knip`: clean.

## Review decisions

- **Template scope**: trimmed to infrastructure, a language selector,
and an optional Git clone. The IDE selector was removed; editors are
added via the builder's module step.
- **Placement**: base ordering is presentational, so it lives on the
client base-infra select step rather than in the API.
- **git-clone in the base**: kept for the build-time clone affordance.
The base renders its module source verbatim, so it currently pins the
public registry and does not yet honor a deployment's registry mirror;
that fix is tracked in DOCS-610 and delivered as a stacked follow-up PR
(an in-code note documents the current behavior).
- **Container image**: left hardcoded
(`codercom/enterprise-base:ubuntu`). The quickstart base is the
opinionated path; the Docker base covers custom images. Revisiting a
`container_image` variable is tracked in DOCS-611.

## Review updates (@jeremyruppel)

- **Ordering moved to the client**: deleted the server-side
Quickstart-before-Docker grouping (and its position test); the
base-infra select step now prioritizes bases client-side via a shared
`sortByPriority` helper, following the `ModuleSelectStep` precedent. The
API just returns a stable, name-sorted list.
- **Derive included modules from render**: dropped the
`included_modules` manifest field and the `IncludedModules` struct
field; `BaseIncludedModules` now derives from the rendered base (single
source of truth). Removed `TestBaseIncludedModulesMatchRendered` and
added a direct `TestBaseIncludedModules`.
- **Kept the PR scoped to "add quickstart base"**: reverted
`ExtractAgentResourceName`/`ExtractModuleNames` to the pre-`hclsyntax`
regex extraction and removed the option/preset HCL extractor family; the
selector↔install-script drift test now uses a small regex. The broader
templatebuilder HCL migration and the preset-language subset guard are
tracked in DOCS-735.
- Branch rebased onto `origin/main` (no content changes beyond the
above).

---

Linear:
[DOCS-558](https://linear.app/codercom/issue/DOCS-558/add-coder-quickstart-template-to-template-builder)

> This PR was created with AI assistance (Coder Agents).
2026-08-26 20:29:20 -04:00

403 lines
11 KiB
Go

package coderd_test
import (
"context"
"net/http"
"testing"
"github.com/google/uuid"
"github.com/stretchr/testify/require"
"github.com/coder/coder/v2/coderd/coderdtest"
"github.com/coder/coder/v2/coderd/templatebuilder"
"github.com/coder/coder/v2/codersdk"
"github.com/coder/coder/v2/testutil"
)
func TestTemplateBuilderBases(t *testing.T) {
t.Parallel()
t.Run("OK", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
resp, err := client.TemplateBuilderBases(ctx)
require.NoError(t, err)
require.NotEmpty(t, resp.Bases)
require.Len(t, resp.Bases, len(templatebuilder.BaseTemplateIDs()))
basesByID := make(map[string]codersdk.TemplateBuilderBase, len(resp.Bases))
for _, b := range resp.Bases {
basesByID[b.ID] = b
}
type baseSpec struct {
id string
expectedOS string
expectedVars []string
hasVariables bool
}
specs := []baseSpec{
{
// Quickstart exposes no builder variables today: its base.json
// declares none. Locking that here flags drift if it changes,
// e.g. if it later exposes a container_image selector.
id: "quickstart",
expectedOS: "linux",
hasVariables: false,
},
{
id: "docker",
expectedOS: "linux",
hasVariables: true,
expectedVars: []string{"container_image"},
},
{
id: "kubernetes",
expectedOS: "linux",
hasVariables: true,
expectedVars: []string{"container_image", "namespace", "use_kubeconfig"},
},
{
id: "aws-linux",
expectedOS: "linux",
hasVariables: false,
},
{
id: "aws-windows",
expectedOS: "windows",
hasVariables: false,
},
{
id: "gcp-windows",
expectedOS: "windows",
hasVariables: true,
expectedVars: []string{"project_id"},
},
}
for _, spec := range specs {
b, ok := basesByID[spec.id]
require.True(t, ok, "base %q missing from response", spec.id)
require.NotEmpty(t, b.Name, "base %q should have a name", spec.id)
require.NotEmpty(t, b.Icon, "base %q should have an icon", spec.id)
require.Equal(t, spec.expectedOS, b.OS, "base %q OS mismatch", spec.id)
require.NotNil(t, b.Variables, "base %q should have non-nil variables slice", spec.id)
if spec.hasVariables {
require.NotEmpty(t, b.Variables, "base %q should have variables", spec.id)
varNames := make(map[string]bool, len(b.Variables))
for _, v := range b.Variables {
varNames[v.Name] = true
}
for _, expected := range spec.expectedVars {
require.True(t, varNames[expected],
"base %q should have variable %q", spec.id, expected)
}
} else {
require.Empty(t, b.Variables, "base %q should have no variables", spec.id)
}
}
})
t.Run("Sorted", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
resp, err := client.TemplateBuilderBases(ctx)
require.NoError(t, err)
require.NotEmpty(t, resp.Bases)
// Bases are returned sorted by display name (with ID as a deterministic
// tiebreak), so the whole list is in non-decreasing name order.
for i := 1; i < len(resp.Bases); i++ {
require.LessOrEqual(t, resp.Bases[i-1].Name, resp.Bases[i].Name,
"bases should be sorted by display name")
}
})
t.Run("DisabledReturns404", func(t *testing.T) {
t.Parallel()
dv := coderdtest.DeploymentValues(t)
dv.TemplateBuilder.Disabled = true
client := coderdtest.New(t, &coderdtest.Options{
DeploymentValues: dv,
})
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
_, err := client.TemplateBuilderBases(ctx)
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusNotFound, sdkErr.StatusCode())
})
}
func TestTemplateBuilderModules(t *testing.T) {
t.Parallel()
t.Run("OK", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
resp, err := client.TemplateBuilderModules(ctx, "")
require.NoError(t, err)
require.NotEmpty(t, resp.Modules)
for _, m := range resp.Modules {
require.NotEmpty(t, m.ID)
require.NotEmpty(t, m.Version)
}
})
t.Run("FilteredByBase", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
resp, err := client.TemplateBuilderModules(ctx, "docker")
require.NoError(t, err)
for _, m := range resp.Modules {
if len(m.CompatibleOS) > 0 {
require.Contains(t, m.CompatibleOS, "linux",
"module %q should be compatible with linux when filtered by docker base", m.ID)
}
}
})
t.Run("BaseExcludesIncludedModules", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
// The quickstart base bundles the git-clone module, so the module
// list for that base must omit git-clone to avoid a collision. The
// docker base does not bundle it, so it stays available there.
quickstartResp, err := client.TemplateBuilderModules(ctx, "quickstart")
require.NoError(t, err)
require.NotEmpty(t, quickstartResp.Modules,
"quickstart should still offer modules other than the ones it bundles")
for _, m := range quickstartResp.Modules {
require.NotEqual(t, "git-clone", m.ID,
"git-clone should be excluded for the quickstart base")
}
dockerResp, err := client.TemplateBuilderModules(ctx, "docker")
require.NoError(t, err)
var dockerHasGitClone bool
for _, m := range dockerResp.Modules {
if m.ID == "git-clone" {
dockerHasGitClone = true
break
}
}
require.True(t, dockerHasGitClone,
"git-clone should remain available for bases that do not bundle it")
})
t.Run("ComputedVariablesExcluded", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
resp, err := client.TemplateBuilderModules(ctx, "")
require.NoError(t, err)
// The embedded code-server module has agent_id with computed=true.
// It must not appear in the API response.
var found bool
for _, m := range resp.Modules {
if m.ID == "code-server" {
found = true
for _, v := range m.Variables {
require.NotEqual(t, "agent_id", v.Name,
"computed variable agent_id must not appear in API response")
}
}
}
require.True(t, found, "code-server module must be in the catalog")
})
t.Run("UnknownBaseReturns400", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
_, err := client.TemplateBuilderModules(ctx, "nonexistent")
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
})
t.Run("DisabledReturns404", func(t *testing.T) {
t.Parallel()
dv := coderdtest.DeploymentValues(t)
dv.TemplateBuilder.Disabled = true
client := coderdtest.New(t, &coderdtest.Options{
DeploymentValues: dv,
})
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
_, err := client.TemplateBuilderModules(ctx, "")
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusNotFound, sdkErr.StatusCode())
})
}
func TestTemplateBuilderSession(t *testing.T) {
t.Parallel()
t.Run("WizardEntry", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := client.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
SessionID: uuid.New(),
EventType: codersdk.TemplateBuilderSessionEventWizardEntry,
})
require.NoError(t, err)
})
t.Run("ComposeCompletion", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := client.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
SessionID: uuid.New(),
EventType: codersdk.TemplateBuilderSessionEventComposeCompletion,
BaseTemplateID: "docker",
ModuleIDs: []string{"code-server", "git-clone"},
DurationSeconds: 42.5,
Success: true,
})
require.NoError(t, err)
})
t.Run("MissingSessionID", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := client.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
EventType: codersdk.TemplateBuilderSessionEventWizardEntry,
})
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
})
t.Run("InvalidEventType", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := client.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
EventType: "invalid_event",
})
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
})
t.Run("DisabledReturns404", func(t *testing.T) {
t.Parallel()
dv := coderdtest.DeploymentValues(t)
dv.TemplateBuilder.Disabled = true
client := coderdtest.New(t, &coderdtest.Options{
DeploymentValues: dv,
})
_ = coderdtest.CreateFirstUser(t, client)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := client.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
EventType: codersdk.TemplateBuilderSessionEventWizardEntry,
})
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusNotFound, sdkErr.StatusCode())
})
t.Run("MemberCannotSubmit", func(t *testing.T) {
t.Parallel()
client := coderdtest.New(t, nil)
admin := coderdtest.CreateFirstUser(t, client)
memberClient, _ := coderdtest.CreateAnotherUser(t, client, admin.OrganizationID)
ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
defer cancel()
err := memberClient.TemplateBuilderSession(ctx, codersdk.TemplateBuilderSessionRequest{
EventType: codersdk.TemplateBuilderSessionEventWizardEntry,
})
require.Error(t, err)
var sdkErr *codersdk.Error
require.ErrorAs(t, err, &sdkErr)
require.Equal(t, http.StatusNotFound, sdkErr.StatusCode())
})
}