Skip to content

TESTING.md

Latest commit

 

History

History
292 lines (214 loc) · 5.55 KB

TESTING.md

File metadata and controls

292 lines (214 loc) · 5.55 KB

pgtrace testing guide

This guide covers testing pgtrace components and running the system.

Quick Setup

Use the automated setup script:

./scripts/test-setup.sh

This script will:

  • Check prerequisites (Rust, Elixir, PostgreSQL)
  • Set up database (Docker or local)
  • Run migrations
  • Build all components
  • Verify setup

Manual Setup

1. Database Setup

Option A: Docker Compose

# Start Docker containers
docker-compose up -d

# Run migrations
export PGPASSWORD=postgres
for file in store/migrations/*.sql; do
  psql -h localhost -p 5433 -U postgres -d pgtrace_store -f "$file"
done

Option B: Local PostgreSQL

# Create database
createdb pgtrace_store

# Run migrations
for file in store/migrations/*.sql; do
  psql -d pgtrace_store -f "$file"
done

2. Build Components

# Agent
cd agent
cargo build --release

# CLI
cd ../cli
cargo build --release

# Server
cd ../server
mix deps.get
mix compile

Running Tests

Basic Smoke Tests

Run the basic test script:

./scripts/test-basic.sh

Or run tests manually:

# Set database connection
export PGTRACE_STORE_DSN="postgres://postgres:postgres@localhost:5433/pgtrace_store"

# Test CLI
cd cli
cargo run --release -- doctor

# Test database connection
psql "$PGTRACE_STORE_DSN" -c "SELECT COUNT(*) FROM pgtrace.nodes;"

Unit Tests

# Rust tests
cd agent && cargo test
cd ../cli && cargo test

# Elixir tests
cd server && mix test

Integration Tests

Test Agent

  1. Configure agent (see agent/pgtrace-agent.yaml.example):
node_id: "test-node-1"
source:
  dsn: "postgres://postgres:postgres@localhost:5434/postgres"
store:
  dsn: "postgres://postgres:postgres@localhost:5433/pgtrace_store"
  1. Start source database (if using Docker):
docker-compose up -d postgres-source
  1. Run agent:
cd agent
cargo run --release -- run --config pgtrace-agent.yaml
  1. Verify data is being collected:
# In another terminal
psql "postgres://postgres:postgres@localhost:5433/pgtrace_store" -c "SELECT COUNT(*) FROM pgtrace.events;"
psql "postgres://postgres:postgres@localhost:5433/pgtrace_store" -c "SELECT * FROM pgtrace.nodes;"

Test CLI

cd cli
export PGTRACE_STORE_DSN="postgres://postgres:postgres@localhost:5433/pgtrace_store"

# Doctor command
cargo run --release -- doctor

# Tail events (if agent is running)
cargo run --release -- tail --node test-node-1 --window 5m

# Incident snapshot
cargo run --release -- incident --node test-node-1 --at "now" --window 10m

# Lock chains
cargo run --release -- locks --node test-node-1 --at now

Test Server

  1. Configure database in server/config/config.exs

  2. Start server:

cd server
mix phx.server
  1. Test API endpoints:
# Health check
curl http://localhost:4000/api/v1/health

# Timeline
curl "http://localhost:4000/api/v1/nodes/test-node-1/timeline?from=2026-01-13T00:00:00Z&to=2026-01-13T23:59:59Z"

# Spikes
curl "http://localhost:4000/api/v1/nodes/test-node-1/spikes?from=2026-01-13T00:00:00Z&to=2026-01-13T23:59:59Z&metric=waits"
  1. Test UI:
# Open in browser
open http://localhost:4000

Test Scenarios

Scenario 1: Lock Storm

Simulate a lock storm to test lock edge detection:

-- Session 1
BEGIN;
LOCK TABLE some_table IN ACCESS EXCLUSIVE MODE;

-- Session 2 (in another terminal)
BEGIN;
SELECT * FROM some_table;  -- Will wait

Run agent and check:

cargo run --release -- locks --node test-node-1 --at now

Scenario 2: Query Regression

Generate query load:

-- Run heavy query repeatedly
SELECT pg_sleep(1);

Check query statistics:

cargo run --release -- query --node test-node-1 --qhash <qhash> --window 15m

Scenario 3: Marker Correlation

Insert marker via SQL:

INSERT INTO pgtrace.markers (node_id, ts, label, meta, source)
VALUES ('test-node-1', now(), 'test deployment', '{"version": "1.0.0"}'::jsonb, 'manual');

Or via API:

curl -X POST http://localhost:4000/api/v1/markers \
  -H "Content-Type: application/json" \
  -d '{"node_id": "test-node-1", "label": "test deployment", "meta": {"version": "1.0.0"}}'

Verification Checklist

Database migrations run successfully All components compile without errors CLI doctor command works Database connection successful Agent can connect to source database Agent can write to store database Server starts without errors API endpoints respond UI loads in browser

Troubleshooting Tests

Database Connection Issues

# Check PostgreSQL is running
pg_isready -h localhost -p 5433

# Test connection
psql "postgres://postgres:postgres@localhost:5433/pgtrace_store" -c "SELECT 1"

# Check tables
psql "postgres://postgres:postgres@localhost:5433/pgtrace_store" -c "\dt pgtrace.*"

Agent Not Collecting Data

  • Check source database connection
  • Verify agent has required permissions
  • Check agent logs for errors
  • Verify node_id is configured correctly

CLI Errors

  • Verify PGTRACE_STORE_DSN is set
  • Check database connection
  • Ensure migrations have been run
  • Check user has pgtrace_reader role

Server Errors

  • Check database configuration in config.exs
  • Verify migrations are run
  • Check logs: mix phx.server shows errors
  • Ensure all dependencies are installed: mix deps.get

Performance Testing

For performance testing, see docs/OPERATIONS.md.

Continuous Testing

For CI/CD integration:

# In CI script
./scripts/test-setup.sh
./scripts/test-basic.sh
cd agent && cargo test
cd ../cli && cargo test
cd ../server && mix test