Skip to content

INTEGRATION_QA_GUIDE.md

Latest commit

 

History

History
308 lines (248 loc) · 7.79 KB

INTEGRATION_QA_GUIDE.md

File metadata and controls

308 lines (248 loc) · 7.79 KB

Integration QA Testing Guide

Overview

This guide provides comprehensive testing instructions for SprintIQ's integration system, covering GitHub, Slack, and Linear integrations.

Prerequisites

1. Development Environment

# Start the development server
npm run dev

# Verify both servers are running:
# - Frontend: http://localhost:3000
# - Backend: http://localhost:4000

2. Test API Keys (Required for Production Testing)

GitHub Personal Access Token

  1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
  2. Create token with these scopes:
    • repo (Repository access)
    • read:user (Read user profile)
    • user:email (Access user email)
  3. Copy token (format: ghp_xxxxxxxxxxxxxxxxxxxx)

Slack Bot Token

  1. Create Slack App at https://api.slack.com/apps
  2. Go to OAuth & Permissions
  3. Add Bot Token Scopes:
    • channels:read
    • chat:write
    • users:read
    • team:read
  4. Install app to workspace
  5. Copy Bot User OAuth Token (format: xoxb-xxxxxxxxxxxxx)

Linear API Key

  1. Go to Linear → Settings → API → Personal API Keys
  2. Create new API key with read/write permissions
  3. Copy API key (format: lin_api_xxxxxxxxxxxxx)

Test Scenarios

Scenario 1: Integration Page Loading and Display

Expected Behavior

  • Integration page loads without errors
  • Only GitHub, Slack, and Linear integrations are displayed
  • Each integration shows proper status (Available/Installed)
  • Search and filtering work correctly

Test Steps

  1. Navigate to /integrations
  2. Verify page loads within 2-3 seconds
  3. Check only 3 integrations are shown (not all 7)
  4. Verify integration cards show:
    • Name and description
    • Install/Configure button
    • Status indicator

Success Criteria

  • ✅ Page loads quickly
  • ✅ Only GitHub, Slack, Linear shown
  • ✅ No console errors
  • ✅ UI is responsive

Scenario 2: GitHub Integration Configuration

Test Steps

  1. Click "Configure" on GitHub integration
  2. Configuration modal opens
  3. Enter GitHub Personal Access Token
  4. Click "Test Connection"
  5. Verify connection result
  6. Click "Save & Connect" if test successful

Expected API Calls

// Configuration save
POST /api/integrations/github/configure
{
  "apiKeys": {
    "token": "ghp_your_token_here"
  },
  "testConnection": false
}

// Connection test
POST /api/integrations/github/test

// Status update
GET /api/integrations/status

Success Criteria

  • ✅ Modal opens correctly
  • ✅ Form validation works
  • ✅ Test connection validates token
  • ✅ Success message appears
  • ✅ Status updates to "Connected"

Scenario 3: Slack Integration Configuration

Test Steps

  1. Click "Configure" on Slack integration
  2. Enter Slack Bot Token
  3. Test connection
  4. Save configuration

Expected Fields

  • Bot User OAuth Token (required)

Success Criteria

  • ✅ Token validation works
  • ✅ Connection test succeeds
  • ✅ Integration status updates

Scenario 4: Linear Integration Configuration

Test Steps

  1. Click "Configure" on Linear integration
  2. Enter Linear API Key
  3. Test connection
  4. Save configuration

Expected Fields

  • API Key (required)

Success Criteria

  • ✅ API key validation works
  • ✅ Connection test succeeds
  • ✅ Integration status updates

Scenario 5: Error Handling

Test Invalid API Keys

  1. Enter invalid GitHub token (e.g., "invalid_token")
  2. Click "Test Connection"
  3. Verify error message shows
  4. Ensure token is not saved

Test Missing Required Fields

  1. Leave API key field empty
  2. Click "Save & Connect"
  3. Verify validation error appears

Test Network Errors

  1. Stop development server
  2. Try to configure integration
  3. Verify appropriate error message

Scenario 6: Integration Status Persistence

Test Steps

  1. Configure all three integrations
  2. Refresh page
  3. Verify statuses persist
  4. Check database records

Database Verification

-- Check saved integrations
SELECT provider, testStatus, isActive, createdAt 
FROM integration_api_keys 
WHERE userId = 'your-user-id';

Scenario 7: Disconnect Integration

Test Steps

  1. Configure an integration
  2. Click "Disconnect" or similar action
  3. Verify integration status resets
  4. Confirm API keys are removed from database

API Testing with curl (Authentication Required)

Get Integration Status

curl -X GET http://localhost:3000/api/integrations/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Configure GitHub Integration

curl -X POST http://localhost:3000/api/integrations/github/configure \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "apiKeys": {
      "token": "ghp_your_github_token"
    },
    "testConnection": true
  }'

Test Integration Connection

curl -X POST http://localhost:3000/api/integrations/github/test \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Manual Testing Checklist

Pre-Testing Setup

  • Development server running
  • Database migrations applied
  • Test API keys ready
  • Browser dev tools open

GitHub Integration

  • Configuration modal opens
  • Field validation works
  • Invalid token shows error
  • Valid token shows success
  • Status updates correctly
  • Database record created

Slack Integration

  • Configuration modal opens
  • Bot token field validates
  • Connection test works
  • Status updates correctly
  • Database record created

Linear Integration

  • Configuration modal opens
  • API key field validates
  • Connection test works
  • Status updates correctly
  • Database record created

Error Scenarios

  • Network errors handled gracefully
  • Invalid credentials rejected
  • Missing fields validated
  • User feedback clear and helpful

Performance

  • Page loads under 3 seconds
  • API calls complete quickly
  • No memory leaks in browser
  • Responsive on mobile devices

Common Issues and Solutions

Authentication Errors

  • Issue: "Authentication failed" on API calls
  • Solution: Ensure user is logged in with Supabase
  • Debug: Check browser dev tools for session token

Database Connection Errors

  • Issue: "Database connection failed"
  • Solution: Verify DATABASE_URL in .env
  • Debug: Check server logs for Prisma errors

Integration Test Failures

  • Issue: Valid API keys fail connection test
  • Solution: Check environment variables and API key scopes
  • Debug: Review integration service logs

Status Not Updating

  • Issue: Integration shows as disconnected after setup
  • Solution: Check testStatus in database
  • Debug: Verify status endpoint returns correct data

Automated Testing

Run Test Suite

# Run with test tokens
node qa-integration-test.js

# Run with production tokens (set environment variables first)
GITHUB_TEST_TOKEN=ghp_xxx SLACK_TEST_TOKEN=xoxb_xxx LINEAR_TEST_TOKEN=lin_xxx \
node qa-integration-test.js --production

Expected Results

  • Status endpoint accessible
  • Configuration endpoints working
  • Validation properly rejecting invalid input
  • Test connections working with valid tokens

Reporting Issues

When reporting integration issues, include:

  1. Step-by-step reproduction instructions
  2. Browser console errors
  3. Network tab showing API calls
  4. Server logs (if accessible)
  5. Database state (integration_api_keys table)
  6. Environment information (OS, browser, Node version)

Production Deployment Checklist

Before deploying to production:

  • All manual tests pass
  • Automated tests pass
  • Error handling comprehensive
  • Security review completed
  • Performance acceptable
  • Mobile responsiveness verified
  • Documentation updated