logos-storage-docs-obsidian/10 Notes/Running tests with gotestsum.md

A summary of running different test scenarios with gotestsum based on an example

gotestsum Command Patterns

1. Only Selected Test

# Run a specific test function
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloader_BasicSingleArchive$" -count 1

# Run specific testify test
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloader_BasicSingleArchive_Testify$" -count 1

# Run multiple archives testify test
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloader_MultipleArchives_Testify$" -count 1

2. Only Selected Test Suite

# Run the entire testify suite (all methods in the suite)
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloaderSuite" -count 1

# Run a specific test method within the suite
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloaderSuite/TestBasicSingleArchive" -count 1

3. All Tests for Given Package

# Run all tests in communities package
gotestsum --packages="./communities" -f testname --rerun-fails -- -count 1

# Alternative syntax (same result)
gotestsum --packages="./communities" -f testname --rerun-fails

# Run all tests with verbose output
gotestsum --packages="./communities" -f testname --rerun-fails -- -v -count 1

4. Integration Tests

# Run only integration tests (using build tags)
gotestsum --packages="./communities" -f testname --rerun-fails -- -tags=integration -run "Integration" -count 1

# Run integration tests with timeout (since they may take longer)
gotestsum --packages="./communities" -f testname --rerun-fails -- -tags=integration -run "Integration" -timeout=60s -count 1

# Run integration tests with specific environment variables
CODEX_HOST=localhost CODEX_API_PORT=8080 gotestsum --packages="./communities" -f testname --rerun-fails -- -tags=integration -run "Integration" -count 1

Advanced gotestsum Patterns

Filter by Pattern (Multiple Tests)

# Run all archive downloader tests (both standard and testify)
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "ArchiveDownloader" -count 1

# Run only testify tests
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "Testify" -count 1

# Run all CodexClient tests
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "CodexClient" -count 1

Output Formats

# Different output formats
gotestsum --packages="./communities" -f dots         # Dots progress
gotestsum --packages="./communities" -f pkgname      # Show package names
gotestsum --packages="./communities" -f testname     # Show test names (recommended)
gotestsum --packages="./communities" -f standard-quiet  # Minimal output

Multiple Packages

# Run tests across multiple packages
gotestsum --packages="./communities,./cmd/upload,./cmd/download" -f testname --rerun-fails -- -count 1

# Run all packages recursively
gotestsum --packages="./..." -f testname --rerun-fails -- -count 1

Race Detection and Coverage

# Run with race detection
gotestsum --packages="./communities" -f testname --rerun-fails -- -race -count 1

# Run with coverage
gotestsum --packages="./communities" -f testname --rerun-fails -- -cover -count 1

# Run with both race detection and coverage
gotestsum --packages="./communities" -f testname --rerun-fails -- -race -cover -count 1

Key gotestsum Advantages

1. Better Output Formatting: Clean, colored output with test names
2. Automatic Retry: --rerun-fails reruns failed tests automatically
3. JUnit XML Output: --junitfile=results.xml for CI/CD integration
4. JSON Output: --jsonfile=results.json for parsing
5. Watch Mode: --watch to rerun tests on file changes
6. Parallel Execution: Better handling of parallel test output

Complete Examples for Your Project

# Quick test of archive downloader functionality
gotestsum --packages="./communities" -f testname --rerun-fails -- -run "ArchiveDownloader" -count 1

# Full test suite with coverage
gotestsum --packages="./communities" -f testname --rerun-fails -- -cover -count 1

# Integration tests (when you have a Codex node running)
gotestsum --packages="./communities" -f testname --rerun-fails -- -tags=integration -timeout=60s -count 1

# Development workflow with watch mode
gotestsum --packages="./communities" -f testname --watch -- -count 1

The key difference from go test is that gotestsum provides much better visual feedback, automatic retry capabilities, and better CI/CD integration options while using the same underlying Go test infrastructure.

Logs

In your tests you can include custom logs.

go test -v prints them without an issue, but for gotestsum to do the same you have to use standard-verbose format option:

gotestsum --packages="./communities" -f standard-verbose --rerun-fails -- -run "TestCodexArchiveDownloaderSuite" -v -count 1
=== RUN   TestCodexArchiveDownloaderSuite
=== RUN   TestCodexArchiveDownloaderSuite/TestBasicSingleArchive
    codex_archive_downloader_testify_test.go:112: ✅ Basic single archive download test passed (testify version)
    codex_archive_downloader_testify_test.go:113:    - All mock expectations satisfied
    codex_archive_downloader_testify_test.go:114:    - Callback invoked: true
=== RUN   TestCodexArchiveDownloaderSuite/TestMultipleArchives
    codex_archive_downloader_testify_test.go:190: ✅ Multiple archives test passed (suite version)
    codex_archive_downloader_testify_test.go:191:    - Completed 3 out of 3 archives
--- PASS: TestCodexArchiveDownloaderSuite (0.20s)
    --- PASS: TestCodexArchiveDownloaderSuite/TestBasicSingleArchive (0.10s)
    --- PASS: TestCodexArchiveDownloaderSuite/TestMultipleArchives (0.10s)
PASS
ok      go-codex-client/communities     0.205s

DONE 3 tests in 0.205s

Compare this output with -f testname:

gotestsum --packages="./communities" -f testname --rerun-fails -- -run "TestCodexArchiveDownloaderSuite" -count 1
PASS communities.TestCodexArchiveDownloaderSuite/TestBasicSingleArchive (0.10s)
PASS communities.TestCodexArchiveDownloaderSuite/TestMultipleArchives (0.10s)
PASS communities.TestCodexArchiveDownloaderSuite (0.20s)
PASS communities

DONE 3 tests in 0.205s

Notice that the test suite itself is also counted as a test - this is one we see DONE 3 tests instead of DONE 2 tests.