e2e/

E2E Testing with Playwright

This directory holds the browser end-to-end tests for GoatFlow. They use playwright-go and Chromium. Every test file has the e2e build tag, so normal go test ./... runs skip them.

Layout

tests/e2e/
├── config/        # config.go: reads BASE_URL, credentials, HEADLESS etc. from the environment
├── helpers/       # browser.go, auth.go, fixtures.go: browser setup, login, HTMX waits
├── playwright/    # second suite: 17 test files (admin pages, customer portal, ticket search, ...)
├── auth_test.go   # authentication
├── api_test.go    # API checks
├── queues_test.go # queue management
├── smoke_test.go  # basic smoke test
└── ...            # 14 more test files (admin groups, plugins, 2FA, customer tickets, ...)

Running the tests

Both suites run in the goatflow-playwright-go container (built from Dockerfile.playwright-go). They run against the test stack, never the dev backend.

make test-stack-up                                # build and start backend-test, runner-test, customer-fe-test
make test-e2e-playwright-go                       # tests/e2e/playwright
make test-e2e-go                                  # tests/e2e (all tests)
make test-e2e-go TEST='Groups|Queues'             # go test -run pattern
make test-e2e TEST='Login'                        # same as test-e2e-go; TEST is required
make test-e2e-playwright-go ARGS='-run TestAdminGroupsUI'

make test also runs make test-e2e-playwright-go after the unit tests.

Each run rebuilds the image first (make e2e-image). The image does not contain the source tree. The repository is bind-mounted at /workspace, so source changes never need a rebuild. Tests use -count=1, so results are never cached.

Settings the Makefile passes to the container

SLOW_MO, SCREENSHOTS and VIDEOS are passed through from your environment or the make command line, for example make test-e2e-go TEST='Groups' VIDEOS=true SLOW_MO=250.

A localhost or 127.0.0.1 BASE_URL switches the container to the host network. The customer portal URL then becomes http://localhost:$(TEST_CUSTOMER_FE_PORT) (default 18082). Example:

make test-e2e-go BASE_URL=http://localhost:18081

Port 18081 is TEST_BACKEND_PORT, the host port docker-compose.test.yaml publishes for backend-test.

Why /tmp is a tmpfs

TMPDIR is /tmp inside the container, a tmpfs of E2E_TMPFS_SIZE. Playwright runs Chromium with --disable-dev-shm-usage, so the browser keeps its shared memory there as files. go test also builds its test binaries there. Keeping this off the bind-mounted repository stops pages failing with net::ERR_INSUFFICIENT_RESOURCES or "Page crashed" when the repository disk is nearly full.

Test output

Paths are relative to the package directory, because go test runs each package in its own directory:

test-results/ is in .gitignore.

Writing tests

Basic test structure

//go:build e2e

func TestFeature(t *testing.T) {
    // Setup browser. NewBrowserHelper fails the test if BASE_URL/login does not answer.
    browser := helpers.NewBrowserHelper(t)
    err := browser.Setup()
    require.NoError(t, err)
    defer browser.TearDown()

    // Login if needed
    auth := helpers.NewAuthHelper(browser)
    err = auth.LoginAsAdmin()
    require.NoError(t, err)

    t.Run("Subtest", func(t *testing.T) {
        err := browser.NavigateTo("/page")
        require.NoError(t, err)

        button := browser.Page.Locator("button#submit")
        err = button.Click()
        require.NoError(t, err)

        result := browser.Page.Locator(".result")
        text, _ := result.TextContent()
        assert.Contains(t, text, "Success")
    })
}

Good practice

1. Add data-testid attributes to elements you need to select.
2. Call browser.WaitForHTMX() after actions that send an HTMX request.
3. Delete any test data your test creates.
4. Group related checks with t.Run().

CI

.github/workflows/test.yml runs make lint-platform and then make test. make test starts the test stack and runs make test-e2e-playwright-go as one of its steps. To run the same E2E steps by hand:

make test-stack-up
make test-e2e-playwright-go
make test-e2e-go

Troubleshooting