🧪 Testing Plan for jargons.dev

Related to #55

Overview

The project is an Astro-based dictionary application with GitHub OAuth integration, word editing functionality, and API endpoints. Here's a prioritized testing strategy:

📋 Phase 1: Foundation Tests (High Priority)

1. Utility Functions (src/lib/utils/)

Why start here: Pure functions, no dependencies, easy to test and validate core logic.

utils/index.js - Core Utilities

• ✅ resolveCookieExpiryDate() - Date calculations
• ✅ getRepoParts() - String parsing for GitHub repos
• ✅ normalizeAsUrl() - URL slug generation
• ✅ isObjectEmpty() - Object validation
• ✅ resolveEditorActionFromPathname() - URL parsing
• ✅ capitalizeText() - Text formatting
• ✅ generateBranchName() - Git branch naming
• ✅ buildStatsUrl() - URL construction
• ✅ buildWordPathname() - Path generation
• ✅ buildWordSlug() - Slug creation

utils/crypto.js - Encryption/Decryption

• ✅ encrypt() - Data encryption
• ✅ decrypt() - Data decryption
• ✅ Encryption/decryption round-trip tests
• ✅ Error handling for invalid inputs

2. Constants & Configuration

Why important: Validates core configuration values used throughout app.

constants.js

• ✅ Validate all constants are properly defined
• ✅ GitHub repository details structure
• ✅ Labels configuration
• ✅ Environment-specific values

📋 Phase 2: Business Logic Tests (Medium Priority)

3. Word Management (src/lib/)

Why critical: Core functionality of the dictionary app.

submit-word.js - PR Creation Logic

• ✅ PR title generation (new vs edit)
• ✅ PR body template rendering
• ✅ Label assignment logic
• ✅ Error handling for GitHub API failures
• 🔄 Mock GitHub API calls

word-editor.js - Content Management

• ✅ New word creation
• ✅ Existing word updates
• ✅ File path generation
• ✅ Content formatting
• 🔄 Mock file operations

branch.js - Git Operations

• ✅ Branch creation logic
• ✅ Branch deletion logic
• ✅ Branch name validation
• 🔄 Mock GitHub API calls

fork.js - Repository Management

• ✅ Fork creation logic
• ✅ Fork validation
• ✅ Error handling
• 🔄 Mock GitHub API calls

📋 Phase 3: API Endpoint Tests (High Priority)

4. API Routes (src/pages/api/)

Why critical: External interface, user-facing functionality.

api/dictionary.js - Main Dictionary API

• ✅ POST endpoint (word submission)
  • Authentication validation
  • Input sanitization
  • Word creation flow
  • Word editing flow
  • Error responses
• ✅ DELETE endpoint (branch cleanup)
  • Authentication validation
  • Branch deletion
  • Error handling

api/github/oauth/ - Authentication

• ✅ OAuth authorization flow
• ✅ Callback handling
• ✅ Token validation
• ✅ Error scenarios

api/v1/browse/ - Browse Functionality

• ✅ Dictionary browsing endpoints
• ✅ Pagination logic
• ✅ Search functionality
• ✅ Error handling

📋 Phase 4: Component Tests (Medium Priority)

5. React Components (src/components/islands/)

Why important: User interface validation, but lower priority due to complexity.

Core Interactive Components

• ✅ search.jsx - Search functionality
• ✅ word-editor.jsx - Word editing interface
• ✅ profile.jsx - User profile display
• ✅ recent-searches.jsx - Search history

Test Focus:

• Component rendering
• User interactions
• State management
• Error boundaries

📋 Phase 5: Integration Tests (Lower Priority)

6. End-to-End Workflows

Why later: Complex setup, but validates complete user journeys.

Critical User Flows

• ✅ Complete word submission flow
• ✅ Word editing workflow
• ✅ Authentication flow
• ✅ Search and browse functionality

External Service Integration

• ✅ GitHub API integration
• ✅ OAuth flow with GitHub
• ✅ Repository operations

🛠️ Testing Infrastructure Recommendations

Testing Framework Setup

# Recommended testing stack
npm install --save-dev \
  vitest \              # Fast unit testing
  @testing-library/react \ # React component testing
  @testing-library/jest-dom \ # DOM assertions
  msw \                 # API mocking
  @vitest/ui            # Testing UI

Test Configuration Structure

tests/
├── unit/
│   ├── utils/
│   │   ├── index.test.js
│   │   └── crypto.test.js
│   ├── word-management/
│   │   ├── submit-word.test.js
│   │   ├── word-editor.test.js
│   │   ├── branch.test.js
│   │   └── fork.test.js
│   └── constants/
│       └── constants.test.js
├── integration/
│   ├── api/
│   │   ├── dictionary.test.js
│   │   └── github-oauth.test.js
│   └── components/
│       ├── search.test.jsx
│       └── word-editor.test.jsx
├── e2e/
│   ├── word-submission.test.js
│   └── authentication.test.js
├── fixtures/
│   ├── sample-words.js
│   └── mock-responses.js
└── __mocks__/
    ├── github-api.js
    └── crypto.js

Priority Implementation Order

1. Week 1: Utility functions + Constants (Phase 1)
2. Week 2: Core business logic (Phase 2)
3. Week 3: API endpoints (Phase 3)
4. Week 4: Components + Integration (Phases 4-5)

Testing Best Practices for This Project

• Mock all GitHub API calls to avoid rate limits
• Use test fixtures for consistent word content
• Test error scenarios (network failures, auth issues)
• Validate security aspects (encryption, token handling)
• Test cross-platform compatibility (Windows/Mac/Linux)

🎯 Success Criteria

Coverage Goals

• 90%+ coverage for utility functions
• 80%+ coverage for core business logic
• 70%+ coverage for API endpoints
• 60%+ coverage for React components

Quality Gates

• All tests must pass before merging
• No console errors during test runs
• Performance tests for critical paths
• Security validation for auth flows

Maintenance Strategy

• Tests updated with each new feature
• Regular test suite performance reviews
• Automated test execution in CI/CD
• Test documentation kept current

This plan focuses on the most critical and testable parts first, building confidence in the core functionality before moving to more complex integration scenarios.