Integration Testing Guide

This document explains how to run integration tests against a live API server.

Overview

The integration test suite (src/api/__tests__/integration.test.ts) performs real HTTP requests against a live API server to test the complete integration between the frontend and backend. Unlike unit tests that use mocks, these tests verify actual API functionality.

⚠️ Important Warnings

Use only against test/development databases - These tests create, modify, and delete real data
Never run against production - Destructive tests will modify your production data
API server must be running - Tests require a live API endpoint
Sequential execution - Tests run sequentially to avoid data conflicts

Setup

1. Environment Configuration

Create a .env.integration.local file (copy from .env.integration):

# API Configuration
VITE_API_BASE_URL=http://127.0.0.1:8000/api

# Test User Credentials (optional)
VITE_TEST_EMAIL=test@example.com
VITE_TEST_PASSWORD=password123

# Enable destructive tests (WARNING: Only for test databases!)
VITE_RUN_DESTRUCTIVE_TESTS=false

2. API Server Setup

Ensure your API server is running and accessible at the configured URL:

# Example: Start Laravel development server
php artisan serve

3. Test Database

CRITICAL: Use a dedicated test database, not your production database!

# Example: Configure Laravel for testing
cp .env .env.testing
# Edit .env.testing to use test database
DB_DATABASE=inventory_test

Running Integration Tests

Quick Start Commands

For PowerShell (Windows)

# Read-only tests (safe for any environment)
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="user@example.com"; $env:VITE_TEST_PASSWORD="password"; npx vitest run --config vitest.integration.config.ts

# Full CRUD tests (test database only!)
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="user@example.com"; $env:VITE_TEST_PASSWORD="password"; $env:VITE_RUN_DESTRUCTIVE_TESTS="true"; npx vitest run --config vitest.integration.config.ts --reporter=verbose

# Watch mode for development
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="user@example.com"; $env:VITE_TEST_PASSWORD="password"; npx vitest --config vitest.integration.config.ts

For Bash/Linux/macOS

# Read-only tests (safe for any environment)
VITE_API_BASE_URL="http://127.0.0.1:8000/api" VITE_TEST_EMAIL="user@example.com" VITE_TEST_PASSWORD="password" npx vitest run --config vitest.integration.config.ts

# Full CRUD tests (test database only!)
VITE_API_BASE_URL="http://127.0.0.1:8000/api" VITE_TEST_EMAIL="user@example.com" VITE_TEST_PASSWORD="password" VITE_RUN_DESTRUCTIVE_TESTS="true" npx vitest run --config vitest.integration.config.ts --reporter=verbose

Using NPM Scripts

Alternatively, use the predefined npm scripts:

Read-Only Tests (Safe)

These tests only perform GET requests and are safe to run against any environment:

# Run read-only integration tests
npm run test:integration

Destructive Tests (Dangerous)

These tests create, update, and delete data. Only run against test databases!

# Run all integration tests including destructive operations
npm run test:integration:destructive

Watch Mode

Monitor integration tests during development:

# Run in watch mode (read-only by default)
npm run test:integration:watch

Custom Configuration with NPX

Override environment variables for specific test runs using npx directly:

PowerShell Examples

# Test against different API endpoint
$env:VITE_API_BASE_URL="http://localhost:3000/api"; $env:VITE_TEST_EMAIL="test@example.com"; $env:VITE_TEST_PASSWORD="password123"; npx vitest run --config vitest.integration.config.ts

# Test with different credentials
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="admin@example.com"; $env:VITE_TEST_PASSWORD="admin123"; npx vitest run --config vitest.integration.config.ts

# Run only specific test suites
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="user@example.com"; $env:VITE_TEST_PASSWORD="password"; npx vitest run --config vitest.integration.config.ts --grep "Countries"

Bash Examples

# Test against different API endpoint
VITE_API_BASE_URL="http://localhost:3000/api" VITE_TEST_EMAIL="test@example.com" VITE_TEST_PASSWORD="password123" npx vitest run --config vitest.integration.config.ts

# Enable destructive tests temporarily
VITE_RUN_DESTRUCTIVE_TESTS=true npm run test:integration

Test Categories

1. Read-Only Tests

API Connectivity: Verify API server is accessible
Data Retrieval: Test GET endpoints for all entities
Authentication: Test login/logout functionality
Error Handling: Test 404 and validation error responses

2. CRUD Tests (Destructive)

When VITE_RUN_DESTRUCTIVE_TESTS=true, additional tests run:

Create: Test POST endpoints for all entities
Update: Test PUT/PATCH endpoints
Delete: Test DELETE endpoints
Validation: Test API validation rules
Relationships: Test entity relationships

3. Error Handling Tests

404 Errors: Non-existent resource handling
422 Validation: Invalid data submission
401 Authentication: Unauthorized access
Network Errors: Connection failures

Test Output

Integration tests provide detailed console output:

✅ API server is accessible
✅ Authentication successful
📊 Found 5 countries
✅ Country created: TST
✅ Country retrieved: TST
✅ Country updated: TST
✅ Country deleted: TST
🧹 Cleaning up created test resources...

Troubleshooting

API Server Not Accessible

❌ API server is not accessible: connect ECONNREFUSED

Solution: Ensure API server is running at the configured URL

Authentication Fails

⚠️ Authentication failed, continuing with public endpoints only

Solution: Check credentials in .env.integration.local

Validation Errors

422 Validation Error: The id field is required

Solution: Check API specification for required fields

Database Constraint Errors

500 Internal Server Error: FOREIGN KEY constraint failed

Solution: Ensure test database is properly migrated and seeded

PowerShell Environment Variable Issues

If npm scripts fail in PowerShell with environment variable errors:

# Error: 'VITE_RUN_DESTRUCTIVE_TESTS' is not recognized as a command

Solution: Use npx directly with PowerShell environment variable syntax:

# Instead of this (doesn't work in PowerShell):
npm run test:integration:destructive

# Use this (works correctly):
$env:VITE_API_BASE_URL="http://127.0.0.1:8000/api"; $env:VITE_TEST_EMAIL="user@example.com"; $env:VITE_TEST_PASSWORD="password"; $env:VITE_RUN_DESTRUCTIVE_TESTS="true"; npx vitest run --config vitest.integration.config.ts

Vitest Not Found Error

# Error: vitest: The term 'vitest' is not recognized

Solution: Use npx to run vitest:

# Instead of:
vitest run --config vitest.integration.config.ts

# Use:
npx vitest run --config vitest.integration.config.ts

Authentication Token Issues

If authentication works but subsequent requests fail with 401:

✅ Authentication successful
❌ Request failed with status code 401