# Testing Methodologies Standards for TypeScript

This document outlines the standards for testing TypeScript code to ensure quality, reliability, and maintainability. It covers unit, integration, and end-to-end testing strategies, with a focus on modern approaches and patterns in the TypeScript ecosystem.

## 1. General Testing Principles

These principles apply to all types of testing and are essential for creating a robust and reliable codebase.

### 1.1. Write Tests That Are Independent and Repeatable

* **DO THIS:** Ensure that tests can be run in any order without affecting each other. Use mock data and isolated environments to avoid external dependencies.

* **DON'T DO THIS:** Rely on shared mutable state between tests. This leads to flaky tests that pass or fail unpredictably.

**WHY:** Independent tests provide consistent results, making debugging easier.

"""typescript

// DO THIS: Mock dependencies

import { UserService } from './user.service';

import { UserRepository } from './user.repository';

import { User } from './user.model';

jest.mock('./user.repository');

describe('UserService', () => {

let userService: UserService;

let userRepositoryMock: jest.Mocked;

beforeEach(() => {

userRepositoryMock = {

getUserById: jest.fn(),

saveUser: jest.fn(),

} as jest.Mocked;

userService = new UserService(userRepositoryMock);

});

it('should get a user by ID', async () => {

const mockUser: User = { id: 1, name: 'Test User' };

userRepositoryMock.getUserById.mockResolvedValue(mockUser);

const user = await userService.getUserById(1);

expect(user).toEqual(mockUser);

expect(userRepositoryMock.getUserById).toHaveBeenCalledWith(1);

});

// DON'T DO THIS: Rely on database state

// Bad example: Test modifies a database record used by another test

"""

### 1.2. Write Tests That Are Fast

* **DO THIS:** Optimize tests to run quickly by avoiding unnecessary I/O operations or complex computations.

* **DON'T DO THIS:** Perform slow operations like initializing databases or making external API calls in unit tests. Use integration tests and end-to-end tests for these scenarios.

**WHY:** Fast tests encourage frequent test runs, reducing the time to catch and fix bugs.

"""typescript

// DO THIS: Use in-memory data structures for unit tests

import { calculateSum } from './math.utils';

describe('calculateSum', () => {

it('should calculate the sum of two numbers', () => {

expect(calculateSum(2, 3)).toBe(5);

});

// DON'T DO THIS: Complex setup in each test case

"""

### 1.3. Aim for High Code Coverage

* **DO THIS:** Strive to cover as much of your codebase as possible with tests, aiming for over 80% coverage. Use code coverage tools to identify gaps in your test suite.

* **DON'T DO THIS:** Equate high coverage with quality. Ensure tests assert the correct behavior and handle edge cases.

**WHY:** High code coverage reduces the risk of undetected bugs.

### 1.4. Use Meaningful Assertions

* **DO THIS:** Write assertions that clearly specify the expected outcome of the test. Use descriptive messages to make debugging easier.

* **DON'T DO THIS:** Use generic assertions that don't provide specific information about the failure.

**WHY:** Clear assertions help pinpoint the cause of a test failure quickly.

"""typescript

// DO THIS: Specific assertion

test('should return the correct greeting message', () => {

const result = greet('Alice');

expect(result).toBe('Hello, Alice!');

});

// DON'T DO THIS: Vague assertion

test('should return a string', () => {

const result = greet('Alice');

expect(typeof result).toBe('string'); // Not very specific

});

"""

### 1.5 Follow the Arrange-Act-Assert (AAA) Pattern

* **DO THIS:** Structure your tests to have a clear "Arrange", "Act", and "Assert" sections.

* **DON'T DO THIS:** Mix the stages, making the test hard to reason about.

**WHY:** Makes the test logic more understandable and easier to maintain.

"""typescript

describe('User Authentication', () => {

it('should authenticate a user with valid credentials', async () => {

// Arrange

const username = 'testuser';

const password = 'password123';

const userRepository = {

findUserByUsername: jest.fn().mockResolvedValue({ username, password }),

};

const authService = new AuthService(userRepository as any);

// Act

const result = await authService.authenticate(username, password);

// Assert

expect(result).toBe(true);

});

"""

## 2. Unit Testing

Unit tests focus on testing individual units (e.g., functions, classes) in isolation.

### 2.1. Use Mocking to Isolate Units

* **DO THIS:** Use mocking libraries like Jest or Sinon to simulate the behavior of dependencies.

* **DON'T DO THIS:** Directly use real dependencies in unit tests, as this couples the test to external systems.

**WHY:** Mocking simplifies the test setup and makes the test execution predictable.

"""typescript

// DO THIS: Mocking dependencies

import { EmailService } from './email.service';

import { sendWelcomeEmail } from './user.utils';

jest.mock('./email.service');

describe('sendWelcomeEmail', () => {

it('should send a welcome email to the user', async () => {

const mockEmailService = EmailService as jest.Mocked;

mockEmailService.sendEmail.mockResolvedValue(undefined);

await sendWelcomeEmail('test@example.com', 'Test User');

expect(mockEmailService.sendEmail).toHaveBeenCalledWith(

'test@example.com',

'Welcome',

'Welcome, Test User!'

);

});

"""

### 2.2. Test Boundary Conditions and Edge Cases

* **DO THIS:** Include tests that cover boundary conditions, such as empty inputs, maximum values, or invalid inputs.

* **DON'T DO THIS:** Only test the happy path. This increases the risk of bugs in production.

**WHY:** Testing edge cases ensures your code handles unexpected inputs gracefully.

"""typescript

// DO THIS: Test edge cases

import { divide } from './math.utils';

describe('divide', () => {

it('should divide two numbers correctly', () => {

expect(divide(10, 2)).toBe(5);

});

it('should throw an error when dividing by zero', () => {

expect(() => divide(10, 0)).toThrowError('Cannot divide by zero');

});

it('should return 0 when dividing zero by a number', () => {

expect(divide(0, 5)).toBe(0);

});

"""

### 2.3. Leverage TypeScript's Type System in Tests

* **DO THIS:** Use TypeScript's type system to write type-safe tests. Define types for mock data and expected results.

* **DON'T DO THIS:** Use "any" or "unknown" excessively in tests, as this defeats the purpose of using TypeScript.

**WHY:** Type-safe tests catch type-related errors early.

"""typescript

// DO THIS: Use types in tests

import { User, createUser } from './user.model';

describe('createUser', () => {

it('should create a user with the given name and email', () => {

const userData: Omit = {

name: 'Test User',

email: 'test@example.com',

};

const user: User = createUser(userData);

expect(user.name).toBe(userData.name);

expect(user.email).toBe(userData.email);

expect(user.id).toBeDefined();

});

"""

### 2.4. Test Private Methods (Use with Caution)

* **DO THIS:** Avoid testing private methods directly, but if necessary, use techniques like accessing them through bracket notation or making them protected and creating a derived class for testing.

* **DON'T DO THIS:** Refactor code solely to make private methods testable. Consider the design implications.

**WHY:** Testing private methods can tightly couple tests to implementation details, making refactoring difficult, but sometimes testing them is crucial to ensure functionality.

"""typescript

// Testing private methods, a rare case where it's justified

class MyClass {

private add(a: number, b: number): number{

return a + b;

}

public performOperation(a: number, b:number): number {

return this.add(a,b) * 2;

}

describe('MyClass', () => {

it('should add two numbers correctly (testing private method)', () => {

const myClass = new MyClass();

// Accessing private method using bracket notation (use sparingly)

const result = (myClass as any).add(5, 3);

expect(result).toBe(8);

});

it('should perform the operation', ()=>{

const myClass = new MyClass();

const result = myClass.performOperation(5,3);

expect(result).toBe(16);

});

"""

## 3. Integration Testing

Integration tests verify the interaction between different parts of a system or application.

### 3.1. Choose Appropriate Scenarios

* **DO THIS:** Identify critical interactions between modules and write tests to verify these interactions.

* **DON'T DO THIS:** Attempt to test every possible interaction. Focus on essential scenarios that impact the system's overall behavior.

**WHY:** Integration tests ensure different parts of the system work together as expected.

### 3.2. Use Test Databases or Mocked External Services

* **DO THIS:** Set up a dedicated test database or use mocked external services to avoid affecting production data.

* **DON'T DO THIS:** Run integration tests against production databases. This can lead to data corruption or unintended side effects.

**WHY:** Isolated environments ensure predictable test results. Setting up a test database with seeding can be achieved using tools like Docker and custom scripts.

"""typescript

// Example showing how to setup an integration test using testcontainers

// Dockerfile (simplified)

// FROM postgres:latest

// ENV POSTGRES_USER=test

// ENV POSTGRES_PASSWORD=test

// ENV POSTGRES_DB=testdb

// Jest test

import { PostgreSqlContainer } from 'testcontainers';

import { DataSource } from 'typeorm';

describe('Database Integration Test', () => {

let container: PostgreSqlContainer;

let dataSource: DataSource;

beforeAll(async () => {

container = await new PostgreSqlContainer()

.withDatabase('testdb')

.withUsername('test')

.withPassword('test')

.start();

dataSource = new DataSource({

type: 'postgres',

host: container.getHost(),

port: container.getMappedPort(5432),

username: 'test',

password: 'test',

database: 'testdb',

entities: [], // Your entities

synchronize: true, // Auto-create schema for testing

});

await dataSource.initialize();

});

afterAll(async () => {

await dataSource.destroy();

await container.stop();

});

it('should be able to connect to the database', async () => {

expect(dataSource.isInitialized).toBe(true);

// Now you can perform actual database operations using dataSource

// And assert the expected result

});

"""

### 3.3. Verify Data Consistency

* **DO THIS:** Check that data is correctly persisted and retrieved from databases or external systems.

* **DON'T DO THIS:** Only verify the immediate result of an interaction. Ensure that the data remains consistent over time.

**WHY:** Data consistency is crucial for maintaining the integrity of the system.

"""typescript

// DO THIS: Verify data consistency

import { UserService } from './user.service';

import { UserRepository } from './user.repository';

import { User } from './user.model';

describe('UserService Integration', () => {

let userService: UserService;

let userRepository: UserRepository;

beforeEach(() => {

userRepository = new UserRepository(); // Assuming it connects to a test DB

userService = new UserService(userRepository); //Real UserRepository, test DB.

});

it('should create and retrieve a user', async () => {

const userData: Omit = { name: 'Test User', email: 'test@example.com' };

const createdUser = await userService.createUser(userData);

const retrievedUser = await userService.getUserById(createdUser.id);

expect(retrievedUser).toEqual(createdUser); //Check they are the same

});

"""

### 3.4 Handling Asynchronous Operations in Integration Tests

* **DO THIS:** Use "async/await" or Promises to correctly handle asynchronous operations when testing integrations that involve databases, external APIs, or message queues.

* **DON'T DO THIS:** Forget to await asynchronous calls or fail to handle rejections, which can lead to incomplete tests or unhandled errors.

**WHY:** Prevents flaky and unreliable tests by correctly awaiting the completion of async tasks.

"""typescript

// Example: Integration test with asynchronous database retrieval

it('should retrieve a user asynchronously', async () => {

const userId = 123;

const mockUser = { id: userId, name: 'Async User' };

// Mock the userRepository's getUserById method to simulate async retrieval

userRepositoryMock.getUserById.mockResolvedValue(mockUser);

// Act: Call the service method that retrieves the user

const retrievedUser = await userService.getUserById(userId);

// Assert: Verify that the retrieved user matches the expected user

expect(retrievedUser).toEqual(mockUser);

expect(userRepositoryMock.getUserById).toHaveBeenCalledWith(userId);

});

"""

## 4. End-to-End (E2E) Testing

E2E tests simulate real user scenarios by testing the entire application from start to finish.

### 4.1. Use a Testing Framework

* **DO THIS:** Use a testing framework like Cypress, Playwright, or Puppeteer to automate browser interactions.

* **DON'T DO THIS:** Manually test the application. This is error-prone and time-consuming.

**WHY:** Automation reduces the cost of E2E testing and improves test coverage.

### 4.2. Focus on Key User Flows

* **DO THIS:** Identify critical user flows, such as login, registration, or checkout, and write E2E tests to verify they work correctly.

* **DON'T DO THIS:** Attempt to test every possible user interaction. Prioritize the most important flows.

**WHY:** Focusing on key flows ensures the application is usable for the majority of users.

### 4.3. Use Realistic Test Data

* **DO THIS:** Use realistic test data to simulate real-world scenarios. This includes user accounts, products, and orders.

* **DON'T DO THIS:** Use unrealistic or incomplete data, as this can lead to false positives or negatives.

**WHY:** Realistic data ensures that tests accurately reflect the application's behavior in production. Consider using a seeding strategy to populate test data.

### 4.4. Clean Up After Tests

* **DO THIS:** Clean up any data created during the test execution, such as deleting user accounts or resetting the database.

* **DON'T DO THIS:** Leave the application in an inconsistent state after the tests have finished.

**WHY:** Cleaning up ensures that subsequent tests are not affected by previous runs.

"""typescript

// Example Cypress test (Cypress uses JavaScript/TypeScript)

describe('User Registration', () => {

it('should register a new user successfully', () => {

cy.visit('/register');

cy.get('#name').type('Test User');

cy.get('#email').type('test@example.com');

cy.get('#password').type('password123');

cy.get('#confirmPassword').type('password123');

cy.get('button[type="submit"]').click();

cy.url().should('include', '/dashboard');

cy.contains('Welcome, Test User!').should('be.visible');

});

afterEach(() => {

// Clean up by deleting the user account

cy.request('DELETE', '/api/users/test@example.com'); //Assuming a DELETE API

});

"""

## 5. Testing Tools and Libraries

* **Jest:** A popular testing framework with built-in mocking and assertion capabilities.

* **Mocha:** A flexible testing framework that can be combined with assertion libraries like Chai and mocking libraries like Sinon.

* **Cypress:** An E2E testing framework specifically designed for web applications.

* **Playwright:** A framework for reliable end-to-end testing for web apps. Supports Chromium, Firefox and Webkit

* **Puppeteer:** A Node library that provides a high-level API to control Chrome or Chromium.

* **Testcontainers:** A library that provides lightweight, throwaway instances of databases, message brokers, and more. Ideal for integration testing.

* **Supertest:** A library for testing HTTP APIs.

## 6. Continuous Integration (CI)

* **DO THIS:** Integrate your tests into a CI/CD pipeline to automatically run tests on every code change.

* **DON'T DO THIS:** Rely on manual test runs.

* **WHY:** Automating tests catches bugs early and prevents them from reaching production.

## 7. Testing React specific components with TypeScript

Testing React components that are written in TypeScript introduces a few nuances.

### 7.1 Use Testing Library

* **DO THIS**: Use React Testing Library instead of Enzyme. React Testing Library encourages testing components from a user's perspective.

* **DON'T DO THIS**: Write tests that rely on implementation details.

"""typescript

import React from 'react';

import { render, screen } from '@testing-library/react';

import userEvent from '@testing-library/user-event';

import MyComponent from './MyComponent';

describe('MyComponent', () => {

it('should display the correct message', () => {

render();

expect(screen.getByText('Hello, World!')).toBeInTheDocument();

});

it('should call the onClick handler when the button is clicked', async () => {

const handleClick = jest.fn();

render();

await userEvent.click(screen.getByText('Click Me!'));

expect(handleClick).toHaveBeenCalledTimes(1);

});

// DON'T DO THIS - Testing implementation details.

// This test will break if you change the className of the element.

it('should have the correct class name', () => {

render();

expect(screen.getByText('Class Name Test')).toHaveClass('my-component');

});

"""

### 7.2 Mocking Modules (Properly)

* **DO THIS**: When your React component imports external modules, mock them appropriately.

* **DON'T DO THIS**: Directly import and use real modules in your tests, resulting in integration tests rather than isolated unit tests.

"""typescript

jest.mock('./api', () => ({ // Mock the entire module

fetchData: jest.fn(() => Promise.resolve({ data: 'mocked data' })), }));

it('fetches data correctly', async () => { const { findByText } = render(); expect(await findByText('mocked data')).toBeInTheDocument();});

"""

### 7.3 Testing Component State Changes

* **DO THIS:** Test state changes thoroughly, including initial state, state updates based on user interactions, and state-dependent rendering.

* **DON'T DO THIS:** Assume state updates correctly without verifying the changes in the rendered output.

"""typescript

import React, { useState } from 'react';

import { render, screen, fireEvent } from '@testing-library/react';

function Counter() {

const [count, setCount] = useState(0);

return (

<p>Count: {count}</p>

setCount(count + 1)}>Increment

);

}

test('increments the count when the button is clicked', () => {

render();

const button = screen.getByText('Increment');

const countDisplay = screen.getByText('Count: 0');

fireEvent.click(button);

expect(countDisplay).toHaveTextContent('Count: 1');

fireEvent.click(button);

expect(countDisplay).toHaveTextContent('Count: 2'); // Verify multiple increments

});

"""

This comprehensive document provides a solid foundation for establishing effective testing methodologies in TypeScript projects, ensuring code quality, reliability, and maintainability. Remember that this is a living document that should be updated as the TypeScript ecosystem evolves and new best practices emerge.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Testing Methodologies Standards for TypeScript

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

TypeScript Performance Optimization Standards: Best Practices for Efficient Applications

pnpm over npm

Storybook (v9.0.18+) Guidelines for Angular (v18+)

Code Style and Conventions Standards for TypeScript

Core Architecture Standards for TypeScript