integration-tests - SKILL.md Agent Skill

name: integration-tests description: Setup Python virtual environment and run integration tests with gltest

Run Integration Tests

Setup the Python environment, start the studio, and run integration tests for GenLayer Studio.

Prerequisites

Python 3.12 installed
virtualenv installed (pip install virtualenv)
Docker and Docker Compose installed

Step 1: Start the Studio

The studio must be running before executing integration tests.

# Stop any existing containers and rebuild
docker-compose down && docker-compose up --build

Wait for all services to be healthy before proceeding.

Step 2: Setup Virtual Environment (first time or reset)

In a separate terminal:

# Remove existing venv if present
rm -rf .venv

# Create new venv with Python 3.12
virtualenv -p python3.12 .venv

# Activate
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install all dependencies
pip install -r requirements.txt
pip install -r requirements.test.txt
pip install -r backend/requirements.txt

# Set Python path
export PYTHONPATH="$(pwd)"

Step 3: Run Integration Tests

# Activate venv (if not already)
source .venv/bin/activate
export PYTHONPATH="$(pwd)"

# Run all integration tests (serial)
gltest --contracts-dir . tests/integration

# Run tests in parallel (4 workers) - excludes test_validators.py
gltest --contracts-dir . tests/integration -n 4 --ignore=tests/integration/test_validators.py

# Run validator CRUD tests separately (must run serially)
gltest --contracts-dir . tests/integration/test_validators.py

# Run faster with leader-only mode (skips validator consensus)
gltest --contracts-dir . tests/integration --leader-only

# Run specific test file
gltest --contracts-dir . tests/integration/test_specific.py

# Run with verbose output
gltest --contracts-dir . tests/integration -v

# Run specific test function
gltest --contracts-dir . tests/integration/test_file.py::test_function_name

Parallel Execution Notes

Use -n 4 to run tests in parallel with 4 workers (pytest-xdist)
test_validators.py must be excluded from parallel runs (--ignore) because it tests validator CRUD operations and needs exclusive access to the validator state
Run test_validators.py separately after parallel tests complete

Quick Commands

Full Setup (first time)

# Terminal 1: Start studio
docker-compose down && docker-compose up --build

# Terminal 2: Setup and run tests
rm -rf .venv && \
virtualenv -p python3.12 .venv && \
source .venv/bin/activate && \
pip install --upgrade pip && \
pip install -r requirements.txt && \
pip install -r requirements.test.txt && \
pip install -r backend/requirements.txt && \
export PYTHONPATH="$(pwd)" && \
gltest --contracts-dir . tests/integration

Quick Run (after initial setup, studio already running)

source .venv/bin/activate && export PYTHONPATH="$(pwd)" && gltest --contracts-dir . tests/integration

Parallel Run (4 workers)

source .venv/bin/activate && export PYTHONPATH="$(pwd)" && \
gltest --contracts-dir . tests/integration -n 4 --ignore=tests/integration/test_validators.py && \
gltest --contracts-dir . tests/integration/test_validators.py

Fast Run (leader-only mode)

source .venv/bin/activate && export PYTHONPATH="$(pwd)" && gltest --contracts-dir . tests/integration --leader-only

Troubleshooting

Studio Not Running

# Check if containers are up
docker-compose ps

# Check container logs
docker-compose logs -f backend

Connection Refused Errors

The studio needs time to initialize. Wait for all services to be healthy:

# Watch container status
docker-compose ps

# Check backend health
curl http://localhost:4000/health

Python 3.12 Not Found

# Check available Python versions
which python3.12

# On macOS with Homebrew
brew install python@3.12

gltest Command Not Found

# Make sure venv is activated
source .venv/bin/activate

# Reinstall test dependencies
pip install -r requirements.test.txt

Import Errors

# Ensure PYTHONPATH is set
export PYTHONPATH="$(pwd)"

# Verify from project root
pwd  # Should be genlayer-studio

Test Timeouts

Integration tests may timeout if the studio is under load. Try:

# Run with leader-only for faster execution
gltest --contracts-dir . tests/integration --leader-only

# Run a single test file to isolate issues
gltest --contracts-dir . tests/integration/test_specific.py -v