# How to Run the Tests in AgentsView: Complete Guide to Go Testing with Makefile Targets

> Learn how to run tests in AgentsView using Makefile targets. Discover `make test` for the full suite & `make test-short` for fast unit tests. Ensure fts5 build tag is met for SQLite.

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

---

**AgentsView uses Makefile targets to run its Go test suite, with `make test` executing the full suite and `make test-short` running only fast unit tests, both requiring the `fts5` build tag for SQLite full-text search functionality.**

The kenn-io/agentsview repository is a Go-based application that uses SQLite with full-text search, PostgreSQL, and S3 backends. Understanding how to run the tests in AgentsView is essential for validating changes to the session management, database layers, or CLI commands. The test suite leverages standard Go testing patterns with Testify assertions, wrapped in Make targets that handle build dependencies and Docker-based integration environments.

## Prerequisites for Running AgentsView Tests

Before executing any test commands, ensure your environment meets the following requirements:

- **Go 1.22+** installed and available in your PATH
- **CGO_ENABLED=1** set in your environment (required for the SQLite driver)
- **Docker** installed and running (only required for integration tests like PostgreSQL, S3, or SSH)

The repository uses CGO to compile the SQLite driver, and the `fts5` build tag enables full-text search capabilities in the database layer.

## Running the Core Unit Test Suite

The primary entry points for testing are the `make test` and `make test-short` targets defined in the root `Makefile`. These targets automatically handle preprocessing steps like generating the Lite LLM pricing snapshot and ensuring the embedded frontend directory exists.

### Execute the Full Test Suite with `make test`

The **`make test`** target runs the complete unit test suite across all packages. According to the source code at [Makefile lines 52-55](https://github.com/kenn-io/agentsview/blob/main/Makefile#L52-L55), this target:

1. Generates the pricing snapshot
2. Prepares the embedded frontend directory
3. Executes `go test -tags "fts5" ./... -v -count=1`

```bash
make test

```

This command includes the **`fts5`** build tag, which is mandatory for compiling the SQLite full-text search extensions used throughout the codebase. The `-count=1` flag ensures tests run fresh without cache interference.

### Run Fast Tests Only with `make test-short`

For rapid iteration during development, use **`make test-short`** to skip long-running or integration-heavy tests:

```bash
make test-short

```

This target passes the `-short` flag to the Go test runner, executing:

```bash
go test -tags "fts5" ./... -short -count=1

```

Use this when you need quick feedback on logic changes without waiting for the full suite to complete.

## Running Integration Tests

AgentsView includes integration tests that require external services. These tests use Docker containers to spin up temporary dependencies and are guarded by specific build tags.

### PostgreSQL Integration Tests

The **`make test-postgres`** target, defined at [Makefile lines 77-84](https://github.com/kenn-io/agentsview/blob/main/Makefile#L77-L84), automatically starts a PostgreSQL container, waits for it to become ready, and runs tests with the `pgtest` build tag:

```bash
make test-postgres

```

This command handles the entire lifecycle: container creation, health checks, test execution, and cleanup. You do not need to manually manage the Docker container.

### Additional Backend Tests

The repository also provides targets for other integration scenarios:

- **`make test-s3`** – Tests S3-compatible storage backends
- **`make test-ssh`** – Tests SSH connection handling

Each target follows the same pattern of spinning up Docker containers, running tagged tests, and tearing down resources.

## End-to-End Testing with Playwright

For frontend validation, AgentsView uses Playwright to run browser-based end-to-end tests:

```bash
make e2e

```

This command executes the test specifications located in `frontend/e2e/`, such as [`frontend/e2e/session-list.spec.ts`](https://github.com/kenn-io/agentsview/blob/main/frontend/e2e/session-list.spec.ts), validating the user interface against a running backend instance.

## Manual Test Execution and Build Configuration

While Make targets handle most workflows, you can run tests manually for specific packages or debugging scenarios.

### Running Specific Test Files

To execute a single test file with verbose output, use the same flags the Makefile provides:

```bash
go test -tags fts5 ./internal/db -run TestSessionCRUD -v

```

This example targets the session CRUD tests in [`internal/db/sessions_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions_test.go). The **`fts5`** tag remains mandatory even when running individual tests.

### Preparing Build Dependencies Manually

If you need to run tests without the `make test` wrapper, manually trigger the prerequisite build steps:

```bash
make pricing-snapshot ensure-embed-dir

```

The `pricing-snapshot` target downloads the latest Lite LLM pricing data, while `ensure-embed-dir` prepares the frontend assets for embedding into the Go binary.

## Test Structure and Key Files

Understanding the test layout helps you locate relevant tests when contributing:

- **`internal/db/*_test.go`** – Unit tests for database operations using Testify assertions (e.g., [`internal/db/sessions_test.go`](https://github.com/kenn-io/agentsview/blob/main/internal/db/sessions_test.go))
- **`cmd/agentsview/*_test.go`** – CLI-level tests for commands like `serve`, `pg`, and `session` handling (e.g., [`cmd/agentsview/session_test.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/session_test.go))
- **`frontend/e2e/*`** – Playwright specifications for browser automation (e.g., [`frontend/e2e/session-list.spec.ts`](https://github.com/kenn-io/agentsview/blob/main/frontend/e2e/session-list.spec.ts))

The CI pipeline invokes the same `make` targets described above, ensuring local test results match the continuous integration environment.

## Summary

- **Use `make test`** to run the complete unit test suite with SQLite full-text search support via the `fts5` build tag
- **Use `make test-short`** for rapid feedback with only fast tests enabled
- **Integration tests** require Docker and use specific targets like `make test-postgres`, which automatically manages container lifecycles
- **CGO_ENABLED=1** is mandatory for SQLite compilation; without it, tests will fail to build
- **Frontend validation** uses `make e2e` with Playwright specs located in `frontend/e2e/`
- Reference [Makefile lines 52-55](https://github.com/kenn-io/agentsview/blob/main/Makefile#L52-L55) and [lines 77-84](https://github.com/kenn-io/agentsview/blob/main/Makefile#L77-L84) for the exact command definitions

## Frequently Asked Questions

### Do I need Docker to run the tests in AgentsView?

Docker is only required for integration tests. You can run the full unit test suite with `make test` or `make test-short` without Docker. However, to run PostgreSQL, S3, or SSH integration tests, Docker must be running locally as the Makefile targets automatically spin up temporary containers.

### What does the `fts5` build tag do in AgentsView tests?

The **`fts5`** build tag enables SQLite full-text search version 5 support, which AgentsView requires for its search functionality. All test commands must include `-tags fts5` or use the Make targets that automatically inject this flag. Without it, the code will fail to compile due to missing FTS extensions.

### How do I run a single test function instead of the entire suite?

Use the `-run` flag with a regular expression matching your test function name. For example:

```bash
go test -tags fts5 ./internal/db -run TestSessionCRUD -v

```

This executes only the `TestSessionCRUD` function in the `internal/db` package, using the required `fts5` build tag and verbose output.

### Why does `make test` fail with SQLite-related errors?

SQLite errors during `make test` typically indicate that **CGO_ENABLED=1** is not set in your environment. The SQLite driver requires CGO to compile C bindings. Ensure you have a C compiler available (usually installed with Go) and that `CGO_ENABLED=1` is exported before running tests.