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

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 for database layer validation and 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 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.

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:

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

This approach is useful for debugging individual test cases in 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.

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