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

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, this target:

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

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:

make test-short

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

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, automatically starts a PostgreSQL container, waits for it to become ready, and runs tests with the pgtest build tag:

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:

make e2e

This command executes the test specifications located in frontend/e2e/, such as 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:

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

This example targets the session CRUD tests in 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:

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)
• cmd/agentsview/*_test.go – CLI-level tests for commands like serve, pg, and session handling (e.g., cmd/agentsview/session_test.go)
• frontend/e2e/* – Playwright specifications for browser automation (e.g., 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 and lines 77-84 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}