# How to Run the Tests in kenn-io/agentsview: Complete Makefile and Go Testing Guide

> Easily run tests in kenn-io/agentsview. Execute the full Go test suite with make test or use make test-short for quick unit tests. Master Go testing in this comprehensive guide.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Run `make test` in the repository root to execute the full Go test suite with SQLite/FTS5 support, or use `make test-short` for quick unit tests without integration dependencies.**

The `kenn-io/agentsview` repository uses a conventional **Make-based workflow** to orchestrate its comprehensive test suite. All test commands are defined in the **Makefile** at the repository root, which automatically handles build tags, CGO configuration, and Docker service orchestration for integration testing.

## Prerequisites and Build Configuration

Before executing any test target, the Makefile runs two prerequisite steps automatically. The **`pricing-snapshot`** target restores a cached LiteLLM pricing snapshot required for cost calculation tests, while **`ensure-embed-dir`** guarantees that the embedded frontend assets directory exists for tests verifying the SPA bundle.

The repository requires **CGO** for SQLite and FTS5 support. The Makefile sets `CGO_ENABLED=1` automatically for all test targets, so you do not need to export this manually.

## Running Unit Tests

For standard development workflows, use the primary test targets:

**`make test`** executes all Go tests with the `fts5` build tag enabled. This includes unit tests across `internal/db`, `internal/server`, `internal/parser`, and other packages. According to the source code in the Makefile, this is the canonical command for CI pipelines and normal development.

**`make test-short`** runs the same test suite but passes the `-short` flag to `go test`, skipping long-running or integration-heavy tests. Use this for rapid feedback during local editing cycles.

Unit tests live alongside production code, such as [`internal/db/db_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/db_test.go) for database layer validation and [`internal/web/embed_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/web/embed_test.go) for verifying the Go `embed` directive correctly bundles the SPA into the binary.

## Integration Testing with Docker

Integration tests for external services require Docker Compose and are gated by specific build tags. The **[`docker-compose.test.yml`](https://github.com/kenn-io/agentsview/blob/main/docker-compose.test.yml)** file defines the temporary services for these test suites.

**PostgreSQL Tests**

Run `make test-postgres` to start a temporary PostgreSQL container via `docker compose -f docker-compose.test.yml up -d --wait`, then execute the PostgreSQL-specific tests with the `-tags "fts5,pgtest"` flag. These tests verify PG sync, push, and read-only store logic in [`internal/postgres/integration_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/integration_test.go).

**S3 Backend Tests**

Run `make test-s3` to spin up an S3-compatible test container and execute the S3 discovery tests with `-tags "fts5,s3test"`. This validates the S3 back-end integration logic.

**SSH Integration Tests**

Run `make test-ssh` to start an SSH container and run all SSH-related integration tests with `-tags "fts5,sshtest"`. This validates remote session import functionality via the SSH back-end.

## End-to-End UI Testing

The frontend uses **Playwright** for end-to-end testing against the built SPA.

**`make e2e`** executes the full Playwright test suite located in `frontend/e2e/*.test.ts` against the running application.

**`make e2e-duckdb`** runs the same UI tests but forces the DuckDB backend by setting `AGENTSVIEW_E2E_BACKEND=duckdb`, providing smoke-testing coverage for the DuckDB-served UI.

## Running Specific Tests Manually

While the Makefile handles orchestration, you can run specific test files directly using standard `go test` commands with the appropriate build tags:

```bash
go test -tags "fts5,pgtest" ./internal/postgres -run TestPush

```

This approach is useful for debugging individual test cases in [`internal/postgres/integration_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/postgres/integration_test.go) or other specific packages without running the full suite.

## Summary

- The **`Makefile`** at the repository root defines all test workflows for `kenn-io/agentsview`.
- Run **`make test`** for the full suite including SQLite/FTS5 tests, or **`make test-short`** for quick unit tests only.
- Use **`make test-postgres`**, **`make test-s3`**, and **`make test-ssh`** for Docker-based integration tests with specific build tags (`pgtest`, `s3test`, `sshtest`).
- Execute **`make e2e`** for Playwright UI tests, and **`make e2e-duckdb`** to test against the DuckDB backend.
- The Makefile automatically handles prerequisites (`pricing-snapshot`, `ensure-embed-dir`) and sets `CGO_ENABLED=1` for SQLite support.

## Frequently Asked Questions

### Do I need to install Docker to run all tests in agentsview?

Docker is required only for integration tests. You can run unit tests with `make test` or `make test-short` without Docker, but any target involving PostgreSQL, S3, or SSH (`make test-postgres`, `make test-s3`, `make test-ssh`) requires Docker Compose to spin up temporary service containers.

### What build tags are required when running go test manually?

The core tests require the `fts5` tag for SQLite full-text search support: `-tags "fts5"`. For specific integration tests, append the relevant tag: `pgtest` for PostgreSQL, `s3test` for S3, or `sshtest` for SSH. For example: `go test -tags "fts5,pgtest" ./internal/postgres`.

### Why does the Makefile set CGO_ENABLED=1 automatically?

The `kenn-io/agentsview` application uses SQLite with the FTS5 extension, which requires CGO to interface with the C library. The Makefile ensures `CGO_ENABLED=1` is exported for all test targets so you don't need to configure this environment variable manually.

### How do I run only the frontend tests without the Go backend?

Use `make e2e` to run the Playwright tests in `frontend/e2e/*.test.ts`. This command builds the application and runs the UI tests against it. To test specifically against DuckDB, use `make e2e-duckdb` which sets the `AGENTSVIEW_E2E_BACKEND=duckdb` environment variable before executing the test suite.