StudyMate Testing Guide

This guide provides comprehensive instructions for running tests across the StudyMate application, including client-side tests, GenAI service tests, and microservices tests.

📋 Table of Contents

Prerequisites
Test Structure Overview
Client Tests (React/TypeScript)
GenAI Service Tests (Python/FastAPI)
Microservices Tests (Kotlin/Spring Boot)
CI/CD Integration
Troubleshooting
Contributing

🛠️ Prerequisites

System Requirements

Node.js: v18.0.0 or higher
npm: v8.0.0 or higher
Python: v3.9 or higher
Java: v17 or higher
Docker: v20.0.0 or higher (for integration tests)

Development Tools

Git: For version control
IDE: VS Code, IntelliJ IDEA, or similar
Terminal: Bash, Zsh, or PowerShell

🏗️ Test Structure Overview

team-3/
├── client/                     # React frontend tests
│   ├── src/test/
│   │   ├── contexts/          # Context provider tests
│   │   ├── lib/               # API service tests
│   │   └── mocks/             # MSW mock handlers
│   ├── vitest.config.ts       # Test configuration
│   └── package.json           # Test dependencies
├── genAi/                     # Python GenAI service tests
│   ├── test_main.py           # FastAPI endpoint tests
│   ├── test_llm.py            # LLM service tests
│   ├── pytest.ini            # Test configuration
│   └── requirements-test.txt  # Test dependencies
├── microservices/             # Kotlin microservices tests
│   ├── auth-service/src/test/
│   ├── document-service/src/test/
│   └── genai-service/src/test/
└── infra/                     # Infrastructure tests
    └── studymate/templates/tests/

🖥️ Client Tests (React/TypeScript)

Setup

Navigate to client directory:
```
cd client
```
Install dependencies:
```
npm install
```

Running Tests

Basic Test Commands

# Run all tests once
npm test

# Run tests in watch mode (recommended for development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Advanced Test Commands

# Run specific test file
npm test -- src/test/lib/api.test.ts

# Run tests matching a pattern
npm test -- --grep "authentication"

# Run tests with verbose output
npm test -- --reporter=verbose

# Run tests and generate HTML coverage report
npm run test:coverage -- --reporter=html

Test Categories

1. Authentication Tests

# Run authentication context tests
npm test -- src/test/contexts/AuthContext.test.tsx

Coverage:

User login/logout flows
Token management
Session persistence
Error handling

2. API Service Tests

# Run API integration tests
npm test -- src/test/lib/api.test.ts

Coverage:

HTTP request/response handling
Authentication headers
Error response processing
Rate limiting

3. Component Tests

# Run component tests (when implemented)
npm test -- src/test/components/

Test Configuration

The client tests use:

Vitest: Fast test runner with ES modules support
React Testing Library: Component testing utilities
MSW: Mock Service Worker for API mocking
jsdom: Browser environment simulation

Mock Configuration

Tests use MSW to mock API responses:

// Mock API responses are defined in:
// src/test/mocks/handlers.ts

Expected Results

✅ Test Files:  2 passed (2)
✅ Tests:      45 passed (45)
📊 Coverage:   80%+ for critical paths
⏱️ Duration:   ~10-15 seconds

🐍 GenAI Service Tests (Python/FastAPI)

Setup

Navigate to GenAI directory:
```
cd genAi
```

Install dependencies:

pip install -r requirements.txt
pip install -r requirements-test.txt

Running Tests

Basic Test Commands

# Run all tests
python -m pytest

# Run with verbose output
python -m pytest -v

# Run with coverage
python -m pytest --cov=. --cov-report=html

# Run specific test file
python -m pytest test_main.py -v

Advanced Test Commands

# Run specific test class
python -m pytest test_main.py::TestHealthEndpoint -v

# Run specific test method
python -m pytest test_main.py::TestHealthEndpoint::test_health_check_success -v

# Run tests in parallel
python -m pytest -n auto

# Run tests with benchmark
python -m pytest --benchmark-only

# Run tests with timeout
python -m pytest --timeout=60

Test Categories

1. FastAPI Endpoint Tests

# Run main API endpoint tests
python -m pytest test_main.py -v

Coverage:

Health check endpoint
Session management endpoints
Chat functionality
Summary generation
Quiz and flashcard creation
Error handling

2. LLM Service Tests

# Run LLM service tests
python -m pytest test_llm.py -v

Coverage:

LLM initialization
Prompt processing
Document summarization
Flashcard generation
Resource cleanup

3. Integration Tests

# Run integration tests
python -m pytest -m integration -v

Test Configuration

The GenAI tests use:

pytest: Python testing framework
pytest-asyncio: Async test support
pytest-mock: Mocking utilities
httpx: HTTP client testing
FastAPI TestClient: API testing

Mock Configuration

Tests use comprehensive mocking:

# Mock external dependencies
@patch('main.StudyLLM')
@patch('main.save_document')

Expected Results

✅ Test Files:  2 passed (2)
✅ Tests:      28 passed, 5 failed (33 total)
📊 Coverage:   84% success rate
⏱️ Duration:   ~60-90 seconds

☕ Microservices Tests (Kotlin/Spring Boot)

Setup

Navigate to microservice directory:

cd microservices/auth-service
# or
cd microservices/document-service
# or  
cd microservices/genai-service

Ensure Java 17 is installed:
```
java --version
```

Running Tests

Basic Test Commands

# Run all tests
./gradlew test

# Run with detailed output
./gradlew test --info

# Run specific test class
./gradlew test --tests "AuthControllerTest"

# Run tests continuously
./gradlew test --continuous

Advanced Test Commands

# Run integration tests only
./gradlew integrationTest

# Run with coverage report
./gradlew test jacocoTestReport

# Run with test report
./gradlew test testReport

# Clean and test
./gradlew clean test

Test Categories

1. Controller Tests

# Test REST API endpoints
./gradlew test --tests "*ControllerTest"

2. Service Layer Tests

# Test business logic
./gradlew test --tests "*ServiceTest"

3. Repository Tests

# Test data access layer
./gradlew test --tests "*RepositoryTest"

Test Configuration

The microservices tests use:

JUnit 5: Testing framework
Spring Boot Test: Spring testing utilities
Testcontainers: Database testing
MockMvc: Web layer testing

Expected Results

✅ Build:      SUCCESS
✅ Tests:      All tests pass (when implemented)
📊 Coverage:   Target 80%+
⏱️ Duration:   ~30-60 seconds per service

🚀 CI/CD Integration

GitHub Actions

The project includes automated testing in CI/CD:

# .github/workflows/test.yml
name: Test Suite
on: [push, pull_request]
jobs:
  client-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: cd client && npm ci
      - run: cd client && npm test
  
  genai-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - run: cd genAi && pip install -r requirements.txt requirements-test.txt
      - run: cd genAi && python -m pytest
  
  microservices-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '17'
      - run: cd microservices/auth-service && ./gradlew test

Pre-commit Hooks

Enable automatic testing before commits:

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files

Test Coverage Requirements

Minimum Coverage: 80%
Critical Paths: 95%
New Code: 90%

🔧 Troubleshooting

Common Issues

1. Client Tests Failing

Problem: Tests timeout or fail to run

Error: Test timeout after 60000ms

Solution:

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Update test timeout
npm test -- --timeout 120000

2. GenAI Tests Import Errors

Problem: Module not found errors

ModuleNotFoundError: No module named 'langchain_openai'

Solution:

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

# Use virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt requirements-test.txt

3. Microservices Tests Build Errors

Problem: Gradle build fails

Task :test FAILED

Solution:

# Clean and rebuild
./gradlew clean build

# Check Java version
java --version

# Update Gradle wrapper
./gradlew wrapper --gradle-version 8.5

Environment Variables

Some tests require environment variables:

# For GenAI tests
export OPEN_WEBUI_API_KEY_CHAT=test-key
export OPEN_WEBUI_API_KEY_GEN=test-key
export WEAVIATE_HOST=localhost
export WEAVIATE_PORT=8083

# For client tests
export VITE_API_BASE_URL=http://localhost:3000

Database Setup

For integration tests requiring databases:

# Start test database with Docker
docker run -d --name test-postgres -p 5432:5432 -e POSTGRES_DB=testdb -e POSTGRES_USER=test -e POSTGRES_PASSWORD=test postgres:15

# Start Weaviate for GenAI tests
docker run -d --name test-weaviate -p 8083:8080 cr.weaviate.io/semitechnologies/weaviate:1.30.3

📊 Test Reports

Coverage Reports

View test coverage reports:

# Client coverage
cd client && npm run test:coverage
# Open: coverage/index.html

# GenAI coverage
cd genAi && python -m pytest --cov=. --cov-report=html
# Open: htmlcov/index.html

# Microservices coverage
cd microservices/auth-service && ./gradlew test jacocoTestReport
# Open: build/reports/jacoco/test/html/index.html

Test Result Reports

Generate detailed test reports:

# Client test report
cd client && npm test -- --reporter=json > test-results.json

# GenAI test report
cd genAi && python -m pytest --junitxml=test-results.xml

# Microservices test report
cd microservices/auth-service && ./gradlew test testReport

🤝 Contributing

Writing New Tests

Client Tests

// src/test/components/MyComponent.test.tsx
import { describe, it, expect } from 'vitest'
import { render, screen } from '@testing-library/react'
import MyComponent from '../../components/MyComponent'

describe('MyComponent', () => {
  it('should render correctly', () => {
    render(<MyComponent />)
    expect(screen.getByText('Hello World')).toBeInTheDocument()
  })
})

GenAI Tests

# test_new_feature.py
import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

class TestNewFeature:
    def test_new_endpoint(self):
        response = client.get("/new-endpoint")
        assert response.status_code == 200
        assert response.json() == {"message": "success"}

Microservices Tests

// NewFeatureTest.kt
@SpringBootTest
class NewFeatureTest {
    @Test
    fun `should handle new feature request`() {
        // Test implementation
        assertThat(result).isNotNull()
    }
}

Test Guidelines

Follow AAA Pattern: Arrange, Act, Assert
Use Descriptive Names: should_return_error_when_user_not_found
Mock External Dependencies: APIs, databases, file systems
Test Edge Cases: Empty inputs, null values, boundary conditions
Keep Tests Independent: Each test should run in isolation

Performance Testing

For performance testing:

# Client performance tests
cd client && npm run test:performance

# GenAI benchmark tests
cd genAi && python -m pytest --benchmark-only

# Load testing with k6
k6 run load-test.js

📚 Additional Resources

🆘 Support

If you encounter issues:

Check this guide for common solutions
Review test logs for specific error messages
Check GitHub Issues for known problems
Contact the team via Slack or email

Happy Testing! 🧪

FilesExpand file tree

README-TESTING.md

Latest commit

History

README-TESTING.md

File metadata and controls

StudyMate Testing Guide

📋 Table of Contents

🛠️ Prerequisites

System Requirements

Development Tools

🏗️ Test Structure Overview

🖥️ Client Tests (React/TypeScript)

Setup

Running Tests

Basic Test Commands

Advanced Test Commands

Test Categories

1. Authentication Tests

2. API Service Tests

3. Component Tests

Test Configuration

Mock Configuration

Expected Results

🐍 GenAI Service Tests (Python/FastAPI)

Setup

Running Tests

Basic Test Commands

Advanced Test Commands

Test Categories

1. FastAPI Endpoint Tests

2. LLM Service Tests

3. Integration Tests

Test Configuration

Mock Configuration

Expected Results

☕ Microservices Tests (Kotlin/Spring Boot)

Setup

Running Tests

Basic Test Commands

Advanced Test Commands

Test Categories

1. Controller Tests

2. Service Layer Tests

3. Repository Tests

Test Configuration

Expected Results

🚀 CI/CD Integration

GitHub Actions

Pre-commit Hooks

Test Coverage Requirements

🔧 Troubleshooting

Common Issues

1. Client Tests Failing

2. GenAI Tests Import Errors

3. Microservices Tests Build Errors

Environment Variables

Database Setup

📊 Test Reports

Coverage Reports

Test Result Reports

🤝 Contributing

Writing New Tests

Client Tests

GenAI Tests

Microservices Tests

Test Guidelines

Performance Testing

📚 Additional Resources

🆘 Support