Test Case Manager MVP

A lightweight, modern test case management system built for small QA teams. This MVP provides essential test management functionality with a clean, intuitive interface and robust API.

🚀 Features

Core Functionality

• Project Management: Organize test cases by projects
• Test Suites: Group related test cases together
• Test Cases: Detailed test case management with steps, expected results, priorities, and tags
• Test Runs: Execute test suites and track results
• Dashboard: Real-time insights with pass rates and recent activity
• File Attachments: Attach screenshots and documents to test results (PNG/JPG/PDF, max 10MB)

Technical Features

• Authentication: Secure login/logout with NextAuth
• RESTful API: Complete API with OpenAPI 3.0 specification
• Real-time Updates: Live dashboard updates
• Responsive Design: Works on desktop and mobile
• Docker Support: Production-ready containerization
• TypeScript: Full type safety throughout the application

🛠️ Tech Stack

• Frontend/Backend: Next.js 14 (App Router)
• Database: SQLite with Prisma ORM
• Authentication: NextAuth.js with credentials provider
• Styling: Tailwind CSS + Radix UI primitives
• Validation: Zod schemas for type-safe validation
• Testing: Vitest (unit) + Playwright (E2E)
• API Documentation: OpenAPI 3.0

📋 Requirements

• Node.js 18+
• npm or yarn
• SQLite (included with Node.js)

⚡ Quick Start

Local Development

1. Clone and install dependencies

   git clone <repository-url>
   cd test-case-manager-mvp
   npm install

2. Set up environment

   cp .env.example .env.local
   # Edit .env.local with your configuration

3. Initialize database

   npx prisma migrate dev --name init
   npx prisma generate

4. Seed database with demo data

   npm run db:seed

5. Start development server

   npm run dev

6. Access the application

   • Open http://localhost:3000
   • Login with demo credentials:
     • Email: demo@tcm.local
     • Password: Demo123!

Docker Deployment

1. Using Docker Compose (Recommended)

   # Copy environment file
   cp .env.example .env
   
   # Edit .env with production values
   # Set NEXTAUTH_SECRET to a secure random string
   
   # Start the application
   docker compose up -d
   
   # Initialize database (first time only)
   docker compose exec app npx prisma migrate deploy
   docker compose exec app npm run db:seed

2. Using Docker directly

   # Build the image
   docker build -t tcm-mvp .
   
   # Run the container
   docker run -p 3000:3000 \
     -e NEXTAUTH_SECRET="your-secret-here" \
     -e DATABASE_URL="file:./data/prod.db" \
     -v tcm_data:/app/data \
     -v tcm_uploads:/app/uploads \
     tcm-mvp

📁 Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes
│   ├── login/             # Authentication pages
│   ├── projects/          # Project management pages
│   └── layout.tsx         # Root layout
├── components/            # Reusable UI components
│   ├── ui/               # Basic UI components (buttons, cards, etc.)
│   └── layout/           # Layout components
├── lib/                  # Utility functions and configurations
│   ├── auth.ts           # NextAuth configuration
│   ├── db.ts             # Database client
│   ├── utils.ts          # Helper functions
│   └── validations.ts    # Zod schemas
└── types/                # TypeScript type definitions

prisma/
├── schema.prisma         # Database schema
├── seed.ts              # Database seeding script
└── migrations/          # Database migrations

tests/
├── unit/                # Unit tests (Vitest)
└── e2e/                 # End-to-end tests (Playwright)

public/
└── openapi.yaml         # API documentation

🎯 Usage Guide

Demo Data

The seed script creates:

• Demo user: demo@tcm.local / Demo123!
• Sample project "WebShop" with authentication and checkout test suites
• 7 test cases covering common web app scenarios
• Sample test run with mixed results

Creating Your First Project

1. Log in and navigate to Projects page
2. Click "New Project"
3. Enter project name and description
4. Create test suites to organize your test cases
5. Add test cases with detailed steps and expected results

Running Tests

1. Navigate to your project dashboard
2. Click "New Test Run"
3. Select scope (full project or specific suite)
4. Execute test cases and record results
5. View updated pass rates and activity feed

🔧 Development

Available Scripts

# Development
npm run dev              # Start development server
npm run build           # Build for production
npm run start           # Start production server

# Database
npm run prisma:generate # Generate Prisma client
npm run prisma:migrate  # Run database migrations
npm run prisma:studio   # Open Prisma Studio
npm run db:seed         # Seed database with demo data
npm run db:reset        # Reset database (destructive)

# Testing
npm run test:unit       # Run unit tests
npm run test:e2e        # Run E2E tests
npm run test:e2e:ui     # Run E2E tests with UI

# Code Quality
npm run lint            # Run ESLint
npm run format          # Format code with Prettier

Database Schema

Key entities:

• User: Application users with authentication
• Project: Top-level organization unit
• TestSuite: Groups of related test cases
• TestCase: Individual test cases with steps, expected results
• TestRun: Execution instances of test suites
• TestResult: Results for each test case in a run
• AuditLog: Activity tracking for compliance and history

API Documentation

The complete API specification is available at /openapi.yaml when running the application. Key endpoints:

• POST /api/auth/register - User registration
• GET/POST /api/projects - Project management
• GET/POST /api/projects/{id}/suites - Test suite management
• POST /api/runs - Create test runs
• PATCH /api/runs/{runId}/results/{caseId} - Update test results
• POST /api/uploads - File uploads

Environment Variables

# Database
DATABASE_URL="file:./dev.db"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-key-change-in-production"

# App Configuration
ENABLE_REGISTRATION=true        # Allow new user registration
UPLOAD_MAX_SIZE_MB=10          # Maximum upload file size
UPLOAD_DIR="./uploads"         # File upload directory

🧪 Testing

Unit Tests

npm run test:unit

Covers utility functions, validation schemas, and business logic.

End-to-End Tests

npm run test:e2e

Tests critical user journeys:

• User registration and login
• Project creation and management
• Test case creation and execution
• Dashboard functionality

Test Coverage

• Authentication flows
• Project/suite/case CRUD operations
• Test execution and result recording
• File upload functionality
• Dashboard analytics

🔒 Security

• Password Hashing: bcrypt with salt rounds
• Session Management: NextAuth.js secure sessions
• Input Validation: Zod schemas on all API endpoints
• File Upload Security: Type and size restrictions
• CSRF Protection: Built-in with NextAuth
• SQL Injection Protection: Prisma ORM parameterized queries

📊 Performance

• Database Optimization: Proper indexing on frequently queried fields
• N+1 Query Prevention: Prisma includes for efficient data fetching
• Client-side Caching: React Query for API state management
• Bundle Optimization: Next.js automatic code splitting
• Image Optimization: Next.js Image component

🔍 Monitoring

• Health Check: /api/health endpoint for container orchestration
• Audit Logging: All user actions tracked in database
• Error Handling: Comprehensive error responses and logging
• Performance Monitoring: Built-in Next.js analytics ready

🚀 Production Deployment

Docker Compose (Recommended)

1. Set production environment variables in .env
2. Ensure NEXTAUTH_SECRET is a secure random string
3. Run docker compose up -d
4. Initialize database with docker compose exec app npx prisma migrate deploy

Manual Deployment

1. Build the application: npm run build
2. Set up production database
3. Run migrations: npx prisma migrate deploy
4. Start the application: npm start

Environment Considerations

• Use a secure NEXTAUTH_SECRET in production
• Consider using PostgreSQL for higher loads
• Set up proper backup procedures for SQLite
• Configure reverse proxy for HTTPS
• Monitor disk space for uploads and database growth

🎨 Customization

Theming

The application uses Tailwind CSS with CSS custom properties for theming. Modify src/app/globals.css to customize colors and appearance.

Adding Features

• New API endpoints: Add to src/app/api/
• New pages: Add to src/app/
• New components: Add to src/components/
• Database changes: Modify prisma/schema.prisma and create migrations

📝 Assumptions & Limitations

Current Limitations

• Single-tenant (no multi-tenancy)
• Basic role system (authenticated users only)
• File uploads stored locally (not cloud storage)
• SQLite database (suitable for small-medium teams)
• No real-time collaboration features

Assumptions Made

• Small team usage (2-20 people)
• English-only interface
• Basic reporting needs (pass/fail rates)
• Standard web browsers (modern Chrome/Firefox/Safari)
• Self-hosted deployment preferred

Future Enhancements (Not in MVP)

• Advanced analytics and reporting
• Integration with CI/CD systems
• Real-time collaboration features
• Advanced user roles and permissions
• Cloud storage for attachments
• Export to external systems (Jira, etc.)

🐛 Troubleshooting

Common Issues

"Database locked" error

• Ensure only one instance is running
• Check file permissions on database file

File upload failures

• Verify UPLOAD_DIR exists and is writable
• Check file size and type restrictions

Authentication issues

• Verify NEXTAUTH_SECRET is set
• Check NEXTAUTH_URL matches deployment URL

Database migration errors

• Backup database before migrations
• Run npx prisma db push for development schema sync

Getting Help

1. Check the Issues page
2. Review the OpenAPI specification at /openapi.yaml
3. Enable debug logging by setting NODE_ENV=development

🤝 Contributing

This is an MVP focused on core functionality. Contributions should align with the simple, focused nature of the project.

📄 License

MIT License - see LICENSE file for details.

---

Test Case Manager MVP - Built with ❤️ for QA teams who need simple, effective test management.