yacov qa-vision-scout .cursorrules file for TypeScript

# Cursor Rules for Project

## Project Overview

Project Name: TestHub

Description: TestHub is an internal web-based tool for the QA department to test new copies of websites. It automates comparison of new webpage designs and functionalities against a baseline version and assesses their responsiveness across various operating systems and devices using the Browserstack API. It provides an intuitive dashboard with data visualization using Three.js, D3.js, and P5.js.

Tech Stack:

*   **Frontend**: Next.js 14 (app router), TypeScript, Tailwind CSS, shadcn/UI, Radix UI, Lucide Icons.
*   **Visualization**: Three.js, D3.js, P5.js.
*   **Backend**: Supabase.
*   **Authentication**: Supabase.
*   **API Integration**: Browserstack SDK API
*   **AI Tools**: Claude AI, ChatGPT, Gemini API (for screenshots visual tests), @antiwork/shortest package for automated testing

Key Features:

*   Compare webpage layout and functions with baseline versions.
*   Evaluate responsiveness using Browserstack API.
*   Intuitive dashboard with enhanced visualization.

## Project Structure

### Root Directory:

Contains main configuration files and documentation.

### /frontend:

Contains all frontend-related code, including components, styles, and assets.

/components:

*   Navbar
*   ComparisonModule
*   DeviceTester
*   Dashboard
*   ReportGenerator

/assets:

*   Icons (Lucide Icons)
*   Images (for UI)

/styles:

*   Tailwind CSS configuration
*   Global stylesheets

### /backend:

Contains all backend-related code, including API routes and database models.

/controllers:

*   ComparisonController
*   ResponsivenessChecker

/models:

*   UserModel
*   TestModel

/routes:

*   ApiRoutes for comparison and responsiveness
*   AuthRoutes for user authentication

### /config:

Configuration files for environment variables and application settings.

### /tests:

Contains unit and integration tests for both frontend and backend.

## Development Guidelines

### Coding Standards:

*   Use TypeScript for typed JavaScript support.
*   Follow Tailwind CSS best practices for styling.
*   Ensure readability and maintainability of code.

### Component Organization:

*   Components to be modular and reusable.
*   Separation of concerns: logic in controllers, views in components.

## Cursor IDE Integration

### Setup Instructions:

1.  Clone the repository.
2.  Navigate to project directory and install dependencies using `npm install`.
3.  Set up environment variables as per the `/config` documentation.
4.  Use Supabase CLI for local database setup.

### Key Commands:

*   `npm run dev`: Run the project in development mode.
*   `npm run build`: Build the project for production.
*   `npm test`: Run all tests.

## Additional Context

### User Roles:

*   **QA Tester**: Can run tests and view results.
*   **Departmental Manager**: Full access, manage schedules and reports.
*   **Customer Support Staff**: Read-only access.
*   **Administrator**: Full platform access.

### Accessibility Considerations:

*   Ensure visualizations are accessible with text alternatives.
*   Consider keyboard navigation and screen reader compatibility in the UI design.

## Testing Best Practices

### API Integration Testing

1. **Native vs Third-Party Fetch**:
   * Prefer native `fetch` over third-party implementations like `node-fetch` when working with modern Node.js
   * Ensure type compatibility between mock implementations and actual API types
   * Remove unnecessary dependencies that duplicate built-in functionality

2. **Mock Implementation**:
   * Create a centralized mock utility file (e.g., `test-utils.ts`)
   * Implement proper type definitions for mock functions
   * Use consistent mock patterns across all test files
   * Avoid setting global mocks in multiple places

3. **Test Structure**:
   * Keep test setup DRY by using shared utilities
   * Use descriptive test names that indicate the scenario being tested
   * Include both happy path and error cases
   * Test rate limiting and error handling scenarios

4. **Async Testing**:
   * Properly handle async/await in test cases
   * Use appropriate timeout values in test configuration
   * Ensure mock implementations resolve promptly
   * Avoid unnecessary Promise chaining

5. **Mock Response Handling**:
   * Create helper functions for generating mock responses
   * Maintain consistent response structures
   * Include all required fields in mock data
   * Use realistic data that matches production scenarios

### Debugging Strategies

1. **Systematic Approach**:
   * Start with type compatibility issues
   * Check for dependency conflicts
   * Verify mock implementations
   * Review test timeouts and configuration

2. **Common Issues to Check**:
   * Type mismatches between mock and actual implementations
   * Missing or incorrect mock reset logic
   * Improper async/await usage
   * Unnecessary dependencies causing conflicts

3. **Performance Considerations**:
   * Remove slow or unnecessary network calls in tests
   * Use appropriate timeout values
   * Implement efficient mock responses
   * Avoid unnecessary file operations during tests

### Code Organization

1. **Test File Structure**:
   * Group related tests together
   * Maintain consistent file naming
   * Keep test files close to implementation files
   * Use clear and consistent import ordering

2. **Mock Organization**:
   * Centralize mock implementations
   * Share common test utilities
   * Maintain type safety in mocks
   * Document mock behavior and requirements

3. **Configuration Management**:
   * Use appropriate test runner configuration
   * Set realistic timeout values
   * Configure coverage reporting
   * Maintain consistent environment variables

### Lessons Learned

1. **What Worked Well**:
   * Centralized mock utilities
   * Proper type definitions
   * Consistent test patterns
   * Clear error handling

2. **What to Avoid**:
   * Multiple global mock assignments
   * Mixing different fetch implementations
   * Unnecessary dependencies
   * Overcomplicated mock setups

3. **Best Practices**:
   * Start with native implementations when available
   * Keep mocks simple and type-safe
   * Maintain consistent patterns across tests
   * Document test requirements and setup