stcapp

🧪 STC API Testing Suite

“Every endpoint is a threshold, every test a ritual of validation.”

This testing suite provides comprehensive validation for all STC (Structural Tension Chart) API endpoints. Each test category mirrors the application’s architectural patterns and ensures the complete API ecosystem functions as intended.

🏗️ Test Structure

``` tests/ ├── README.md # This guide ├── run-all-tests.sh # Master test runner ├── setup/ # Database & initialization tests ├── master-charts/ # Chart CRUD operation tests
├── actions/ # Action management tests ├── compositions/ # Musical composition tests ├── auth/ # Authentication tests ├── integration/ # Full workflow tests └── utils/ # Testing utilities ```

🌊 Testing Philosophy

Ritual-Based Testing

Each test follows the Structural Tension pattern:

• Goal: What the endpoint should accomplish
• Current Reality: What we’re testing against
• Action: The API call itself

Memory-Aware Validation

Tests remember state across calls, ensuring:

• Database setup persists for subsequent tests
• Created entities can be referenced in later tests
• Cleanup happens gracefully

🚀 Quick Start

Prerequisites

The test suite relies on a running PostgreSQL instance. Set the DATABASE_URL environment variable to point to your database before launching the server.

export DATABASE_URL=postgres://user:pass@localhost:5432/stcapp_test

# Install dependencies if needed
pnpm install

# Easiest: start the server and run all tests automatically
./scripts/run-tests-with-server.sh

# Manual approach (in separate terminals)
npm run dev           # start the dev server
./tests/run-all-tests.sh

# Run specific test category
./tests/setup/test-setup.sh
./tests/master-charts/test-master-charts.sh
./tests/actions/test-actions.sh

📊 Test Categories

1. Setup Tests (/setup/)

• Database table creation
• Default user creation
• Sample data seeding
• Database reset capabilities

2. Master Charts Tests (/master-charts/)

• List all charts
• Get specific chart with actions
• Create new chart
• Update chart properties
• Delete chart

3. Actions Tests (/actions/)

• List actions (all, by chart, by parent)
• Create top-level actions
• Create nested sub-actions
• Update action properties
• Delete actions
• Test telescopic hierarchy

4. Compositions Tests (/compositions/)

• List musical compositions
• Create new compositions with ABC notation
• Validate notation parsing

5. Auth Tests (/auth/)

• Check authentication status
• Validate session handling

6. Integration Tests (/integration/)

• Complete workflow: Setup → Chart → Actions → Compositions
• Error handling scenarios
• Data consistency validation

🎯 Expected Outcomes

After running the complete test suite, you should have:

• ✅ Fully initialized database
• ✅ Sample master charts with nested actions
• ✅ Musical compositions with ABC notation
• ✅ Validated authentication flow
• ✅ Confirmed all CRUD operations work correctly

🧬 Testing as Living Documentation

These tests serve as both validation and specification. Each curl command demonstrates:

• Expected request format
• Required headers and authentication
• Sample request bodies
• Expected response structures

The tests become a living API reference that stays current with the codebase.