Files
summercms/docs/plugins/testing.md
Jakub Zych 38f7f3a777 feat(surf): AssembleRouter builds the router and handler once; the router stops the MCP endpoint it mounted (quick-261118-lbt)
- surf.AssembleRouter returns the router and the compiled handler from
  one build, so an mcp.enabled app is not built twice; Assemble keeps
  its signature and is implemented on top of it
- serve uses AssembleRouter with a deferred Router.Close
- pier.Pier.Close stops the session reaper and the Redis warm-up; the
  router that mounted the endpoint owns it
- ExampleAssembleRouter, routing/testing docs and the surf/pier READMEs
2026-11-18 15:44:56 +01:00

3.0 KiB

title, description, section, order
title description section order
Testing plugins Test plugins with go test, run database tests against real PostgreSQL containers, replay API parity fixtures and keep documentation examples running. plugins 40

Testing plugins

SummerCMS uses the standard Go test tooling. There is no separate test runner and no PHPUnit bootstrap: a plugin's tests are _test.go files next to its code, and go test runs them.

Running tests

Run every test in the module from its root:

go vet ./...
go test ./...

Tests that need Docker, such as database tests, skip themselves in short mode. Use it for a fast loop:

go test -short ./...

In an application with local plugins in a go.work workspace, run the tests of one plugin by its directory, for example go test ./plugins/acme/blog/....

Unit tests without a database

Most plugin code runs without a database. Build a container with backpack.New, call your plugin's Register and Boot, and assert on what it published. Drive HTTP handlers with net/http/httptest: surf.AssembleRouter builds the same handler serve uses, together with its route table and admin prefix from one build, so a test can send requests to your routes without listening on a port; defer r.Close() on the returned router so its rate-limit store stops. Call console commands in-process with bonfire.Call.

Full-boot tests may call t.Parallel(): party.Activate gives each application its own plugin instances, so two applications booted in one test binary do not share plugin state, provided your plugin keeps its per-application state on its struct and not in package variables. Column-encryption keys are the exception: they are process-wide, and the last lagoon.PublishEncryptionKeys wins.

Database tests

SummerCMS supports PostgreSQL only, so database tests run against real PostgreSQL rather than an SQLite stand-in. The framework's own tests start a postgres:16-alpine container through testcontainers-go and create a fresh database per test. Follow the same pattern in plugin tests:

  • skip the test when testing.Short reports true;
  • migrate a fresh database per test with lagoon.Migrate, so tests do not depend on each other.

Docker must be running for these tests.

API parity tests

When you port an existing backend, its real responses are the acceptance test. tide records request and response fixtures from the reference backend and replays them against your port, reporting differences after masking IDs and timestamps. The summer parity:record, summer parity:replay, summer parity:proxy and summer parity:broadcasts commands wrap it.

Examples in the documentation

Every Go code block in these docs is a copy of an Example function or a marked region of a test that go test ./... runs. If you change a framework API and forget an example, go test fails. Write your plugin's examples the same way: an Example function with an // Output: comment is compiled, run and compared by go test, so it cannot go stale.