# Testing Guide
This guide walks you through testing the ADL system components.
## Prerequisites
1. Install dependencies:
```bash
npm install
```
2. Start the GraphQL server:
```bash
npm run start:graphql
```
## Testing GraphQL Backend
### Using cURL
**Test 1: Create an entry**
```bash
curl -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { createADLEntry(input: { author: \"Alice Johnson\", title: \"Use React for Frontend\", decision: \"React provides the best developer experience and component ecosystem for our needs.\", factSheets: [\"Frontend Framework\", \"UI Components\"], status: Proposed }) { id title status } }"
}'
```
**Test 2: List all entries**
```bash
curl -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d '{"query": "{ adlEntries { id title author status } }"}'
```
**Test 3: Get specific entry** (replace ID with actual ID from Test 1)
```bash
curl -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "query { adlEntry(id: \"YOUR_ID_HERE\") { id title decision } }"
}'
```
### Using GraphQL Playground
1. Open http://localhost:4000/graphql in your browser
2. Try the example queries from GRAPHQL-EXAMPLES.md
3. Explore the schema documentation in the right panel
## Testing MCP Server
### Setup
1. Ensure GraphQL server is running
2. Start MCP server in a new terminal:
```bash
npm run start:mcp
```
### Test via JSON-RPC
Create a test file `test-mcp.json`:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
```
Pipe to the MCP server:
```bash
cat test-mcp.json | node mcp-server/server.js
```
### Test with MCP Client
Configure your MCP client (e.g., Claude Desktop) as described in MCP-SETUP.md, then test the tools:
1. "List all ADL entries"
2. "Create a new ADL entry for using PostgreSQL as database"
3. "Show me the entry I just created"
## Testing Web UI
### Manual Testing
1. Start all services:
```bash
npm start
```
2. Open http://localhost:3000 in your browser
3. Test the following workflows:
#### Workflow 1: Create Entry
- Click "➕ New Decision"
- Fill in all fields:
- Author: Your Name
- Title: Test Decision
- Decision: This is a test decision
- Add fact sheets: "Test Sheet 1", "Test Sheet 2"
- Status: Proposed
- Click "Save"
- Verify entry appears in table
#### Workflow 2: Edit Entry
- Click "Edit" on an existing entry
- Modify the title
- Change status to "Approved"
- Click "Save"
- Verify changes appear in table
#### Workflow 3: Delete Entry
- Click "Delete" on an entry
- Confirm deletion
- Verify entry is removed from table
#### Workflow 4: Fact Sheets Management
- Create or edit an entry
- Add multiple fact sheets
- Remove a fact sheet by clicking the × button
- Save and verify
### Browser Console Testing
Open browser console (F12) and run:
```javascript
// Test API connection
fetch('http://localhost:4000/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: '{ adlEntries { id title } }'
})
})
.then(r => r.json())
.then(console.log);
```
## Integration Testing
### Full Stack Test
This tests the complete flow: UI → GraphQL → Database
1. Start all services:
```bash
npm start
```
2. Open http://localhost:3000
3. Create a new entry via UI
4. Verify in GraphQL Playground:
```graphql
query {
adlEntries {
id
title
author
}
}
```
5. Verify in database:
```bash
sqlite3 data/adl.sqlite "SELECT * FROM adl_entries;"
```
### MCP → GraphQL Integration
1. Configure MCP client with ADL server
2. Use MCP to create an entry
3. Verify entry appears in web UI
4. Update entry via UI
5. Verify update via MCP "list all entries"
## Performance Testing
### Load Test GraphQL
Using Apache Bench:
```bash
# Install Apache Bench
# Ubuntu: sudo apt-get install apache2-utils
# macOS: comes pre-installed
# Create test payload
echo '{"query":"{ adlEntries { id title } }"}' > query.json
# Run 100 requests with 10 concurrent
ab -n 100 -c 10 -p query.json -T application/json http://localhost:4000/graphql
```
### Stress Test Database
Create multiple entries:
```bash
for i in {1..100}; do
curl -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d "{\"query\": \"mutation { createADLEntry(input: { author: \\\"User $i\\\", title: \\\"Decision $i\\\", decision: \\\"Test decision $i\\\", factSheets: [\\\"Sheet $i\\\"], status: Proposed }) { id } }\"}"
done
```
## Troubleshooting Tests
### GraphQL Server Not Responding
```bash
# Check if server is running
curl http://localhost:4000/graphql
# Check for port conflicts
netstat -ano | findstr :4000 # Windows
lsof -i :4000 # Linux/Mac
```
### UI Not Loading Data
1. Open browser console (F12)
2. Check for CORS errors
3. Verify GraphQL server is accessible
4. Check network tab for failed requests
### Database Errors
```bash
# Check database file exists
ls -l data/adl.sqlite
# Verify database schema
sqlite3 data/adl.sqlite ".schema"
# Check for locked database
fuser data/adl.sqlite # Linux
```
### MCP Server Issues
1. Check GRAPHQL_URL environment variable
2. Verify GraphQL server is running
3. Test GraphQL endpoint directly
4. Check MCP client logs
## Expected Results
### Successful GraphQL Query
```json
{
"data": {
"adlEntries": [
{
"id": "abc-123",
"title": "Sample Decision",
"author": "John Doe",
"status": "Proposed"
}
]
}
}
```
### Successful MCP Tool Call
```json
{
"content": [
{
"type": "text",
"text": "Successfully created ADL entry:\n{\n \"id\": \"xyz-789\",\n \"title\": \"New Decision\",\n ...\n}"
}
]
}
```
### Successful UI Operation
- Entry appears in table immediately after save
- No console errors
- Timestamps are current
- Status badge displays correctly
## Automated Testing (Future Enhancement)
Consider adding these test frameworks:
1. **Backend**: Jest or Mocha for unit tests
2. **GraphQL**: Apollo Server Testing
3. **UI**: Playwright or Cypress for e2e tests
4. **MCP**: MCP SDK testing utilities
Example test structure:
```
tests/
├── unit/
│ ├── database.test.js
│ ├── resolvers.test.js
│ └── graphql-client.test.js
├── integration/
│ ├── graphql-api.test.js
│ └── mcp-server.test.js
└── e2e/
└── ui-workflow.test.js
```
## Continuous Testing
For development, use watch mode:
```bash
# In one terminal
npm run start:graphql
# In another terminal
npm run start:ui
# Make changes and test immediately
```
## Test Data Cleanup
To reset the database:
```bash
rm data/adl.sqlite
npm run start:graphql # Will recreate the database
```
To backup before testing:
```bash
cp data/adl.sqlite data/adl.sqlite.backup
```
## Security Testing
1. Test input validation:
- Try creating entries with empty fields
- Test with very long strings
- Test with special characters
2. Test error handling:
- Stop GraphQL server and try UI operations
- Invalid entry IDs
- Malformed GraphQL queries
3. SQL injection prevention (SQLite prepared statements handle this)
- Try entries with SQL syntax in title/decision
- Should be safely escaped
## Reporting Issues
When reporting issues, include:
1. Node.js version: `node --version`
2. Operating system
3. Error messages from console
4. Steps to reproduce
5. Expected vs actual behavior
