# Performance Optimization Standards for TDD
This document outlines the coding standards for performance optimization within a Test-Driven Development (TDD) environment. It's designed to guide developers in writing efficient, responsive, and resource-conscious applications while adhering to TDD principles. These standards are intended to be used in conjunction with other TDD best practices focusing on code quality, readability, and maintainability.
## 1. Introduction to Performance Optimization in TDD
### 1.1. The Importance of Performance
Performance is a critical attribute of any software system. Slow applications lead to poor user experience, increased operational costs (more server resources), and reduced competitiveness. Efficient code utilizes resources effectively, responds quickly to user input, and scales well under load.
### 1.2. TDD and Performance: A Balanced Approach
While TDD primarily focuses on verifying functionality through automated tests, performance should be considered throughout development. Don't fall into the trap of completely ignoring performance until the end. Integrate performance considerations into the TDD cycle by:
* Writing tests that implicitly assess performance through assertions about acceptable execution times (early performance indicators).
* Profiling code regularly to identify bottlenecks and optimize code accordingly *while* ensuring that existing tests still pass.
* Refactoring code for performance *after* tests have been written and passed, preventing premature optimization.
### 1.3 Key Principles
* **Measure, Don't Guess:** Always use profiling tools to identify performance bottlenecks, rather than relying on intuition.
* **Write Testable Code:** Design code that is easily profiled and measured.
* **Refactor Early, Refactor Often:** Address performance issues early in the development cycle while the codebase is more manageable.
* **Maintain Test Coverage:** Ensure that all performance-related changes are covered by unit and integration tests to prevent regressions.
* **Balance Performance with Readability:** Performance gains should not come at the expense of code clarity and maintainability.
* **Avoid Premature Optimization:** Only optimize code after identifying actual performance bottlenecks using profiling tools.
## 2. Architecture and Design Considerations
### 2.1. Choosing the Right Data Structures and Algorithms
**Standard:** Select data structures and algorithms appropriate for the problem's specific performance characteristics.
* **Do This:** Use "HashMap" for fast lookups, "ArrayList" for indexed access, or specialized data structures like "TreeMap" for sorted data, based on the use case and performance profile.
* **Don't Do This:** Use inefficient algorithms (e.g., nested loops for searching an array) when more efficient alternatives exist (e.g., using a "HashSet" for constant-time lookups).
**Why:** Using the right data structures and algorithms can drastically reduce the time complexity of operations, leading to significant performance improvements.
**Example (Java):**
"""java
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class DataStructureExample {
// Inefficient: Linear search in an unsorted list
public boolean containsValueLinear(List list, String value) {
for (String item : list) {
if (item.equals(value)) {
return true;
}
}
return false;
}
// Efficient: Constant-time lookup using a HashMap
public boolean containsValueConstant(Map map, String value) {
return map.containsKey(value);
}
// Test for the above methods.
public static void main(String[] args) {
DataStructureExample example = new DataStructureExample();
List list = new ArrayList<>();
Map map = new HashMap<>();
//Add data to the list and map.
list.add("apple");
list.add("banana");
list.add("orange");
map.put("apple", "fruit");
map.put("banana", "fruit");
map.put("orange", "fruit");
//Test methods
long startTime = System.nanoTime();
boolean linearResult = example.containsValueLinear(list, "banana");
long endTime = System.nanoTime();
long linearDuration = (endTime - startTime); //divide by 1000000 for milliseconds.
startTime = System.nanoTime();
boolean constantResult = example.containsValueConstant(map, "banana");
endTime = System.nanoTime();
long constantDuration = (endTime - startTime); //divide by 1000000 for milliseconds.
System.out.println("Linear Search result: " + linearResult + " Time:" + linearDuration);
System.out.println("Constant Search result: " + constantResult + " Time:" + constantDuration);
}
}
"""
**Anti-Pattern:** Using a "List" for frequent lookups when a "HashSet" or "HashMap" would provide significantly better performance.
### 2.2. Minimizing Network and I/O Operations
**Standard:** Reduce the number and size of network requests and I/O operations.
* **Do This:** Implement caching mechanisms (e.g., using a caching library or in-memory caches), batch multiple requests into a single one (e.g., using bulk APIs), and compress data before sending it over the network.
* **Don't Do This:** Make frequent small requests to a database or API when a single larger request could retrieve the same data. Neglect caching frequently accessed data.
**Why:** Network and I/O operations are often the most expensive operations in an application. Minimizing them can significantly improve response times.
**Example (Python - using "requests" library and caching):**
"""python
import requests
import cachetools
# Create a cache with a maximum size of 100 items and time to live (TTL) of 600 seconds (10 minutes)
@cachetools.cached(cache=cachetools.TTLCache(maxsize=100, ttl=600))
def get_data_from_api(url):
"""
Fetches data from the API, caching the results for a specified duration.
"""
try:
response = requests.get(url)
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error fetching data from {url}: {e}") # Log the error
return None # Handle the error appropriately
# Example usage:
api_url = "https://api.example.com/data" # Replace with an actual api
# First call: data is fetched from the API
data = get_data_from_api(api_url)
if data:
print(f"First call: {data}")
# Subsequent calls within the TTL: data is retrieved from the cache
data = get_data_from_api(api_url)
if data:
print(f"Second call (cached): {data}")
"""
**Anti-Pattern:** Repeatedly querying a database for the same data without caching, resulting in unnecessary I/O overhead.
### 2.3. Asynchronous Processing
**Standard:** Offload long-running or blocking operations to background threads or asynchronous tasks.
* **Do This:** Use message queues (e.g., RabbitMQ, Kafka), task queues (e.g., Celery), or asynchronous programming frameworks (e.g., "asyncio" in Python, CompletableFuture in Java) to handle tasks that don't require immediate results.
* **Don't Do This:** Block the main thread while performing computationally intensive tasks, network requests, or file I/O.
**Why:** Asynchronous processing prevents the application from becoming unresponsive while performing time-consuming operations improving perceived performance and responsiveness.
**Example (Python - using "asyncio"):**
"""python
import asyncio
import time
async def fetch_data(url):
"""Simulates fetching data from a URL asynchronously."""
print(f"Fetching data from {url}...")
await asyncio.sleep(2) # Simulate network latency
print(f"Data fetched from {url}")
return f"Data from {url}"
async def main():
"""Runs multiple asynchronous tasks concurrently."""
urls = ["https://example.com/api/data1", "https://example.com/api/data2", "https://example.com/api/data3"]
tasks = [fetch_data(url) for url in urls]
results = await asyncio.gather(*tasks) # Run tasks concurrently
print(f"All results: {results}")
if __name__ == "__main__":
start_time = time.time()
asyncio.
danielsogl
Created Mar 6, 2025
# Component Design Standards for TDD
This document outlines the coding standards for component design within a Test-Driven Development (TDD) environment. It aims to guide developers in creating reusable, maintainable, and testable components while adhering to the principles of TDD. These standards are designed to be used directly by developers and also to provide context for AI coding assistants.
## 1. Introduction to Component Design in TDD
In TDD, component design is not an afterthought but rather an integral part of the development process. The tests drive the design, ensuring that components are focused, loosely coupled, and easy to test. This section sets the stage for the detailed standards that follow.
### 1.1. Importance of Component Design in TDD
Well-designed components are crucial for:
* **Testability:** Loosely coupled components enable focused unit tests, simplifying the verification of individual component behavior.
* **Maintainability:** Clear component boundaries reduce the complexity of code changes, making it easier to evolve the system over time. Refactoring becomes safer with comprehensive test coverage.
* **Reusability:** Properly designed components can be easily reused in different parts of the application or in other projects, saving development time and effort.
* **Performance:** Although not the primary driver, thoughtful component design can aid in creating code that is more performant when the whole system is taken into account.
* **Clarity:** Well-defined components, tests, and documentation are able to improve clarity for any new developers to the team.
### 1.2. TDD Cycle and Component Design
The TDD cycle (Red-Green-Refactor) significantly impacts component design.
* **Red (Write a failing test):** This compels us to consider the *interface* of the component before its *implementation*. What does the component *do*, not *how* does it do it?
* **Green (Make the test pass):** Focuses on implementing the minimal amount of code required to fulfill the test's requirements. Avoid over-engineering.
* **Refactor (Improve the code):** This is where component design shines. It allows us to improve the structure, remove duplication, and enhance readability while retaining the demonstrated functionality and behaviour of the component.
## 2. Core Principles for Component Design in TDD
These principles guide the creation of well-structured components that are easy to test, maintain, and reuse.
### 2.1. Single Responsibility Principle (SRP)
* **Do This:** Ensure each component has *one*, and only one, reason to change.
* **Don't Do This:** Create components that handle multiple unrelated tasks. These are harder to test and maintain.
* **Why:** SRP promotes modularity and reduces the likelihood that a change in one part of the system will affect unrelated parts. This enhances testability and maintainability.
"""python
# Good: Separate classes for order processing and email notification
class OrderProcessor:
def process_order(self, order):
# Process the order details
return True
class EmailNotifier:
def send_confirmation(self, order):
# Send order confirmation email
return True
# Bad: Single class responsible for both order processing and email notification
class OrderManager: # Violates SRP
def process_order(self, order):
# Process the order details
self.send_confirmation(order) # Contains email logic
def send_confirmation(self, order):
# Send order confirmation email
return True
"""
### 2.2. Open/Closed Principle (OCP)
* **Do This:** Design components that are open for extension but closed for modification. Use abstractions (interfaces, abstract classes) to allow new functionality to be added without altering existing code.
* **Don't Do This:** Modify existing component code directly to add new functionality. This can introduce bugs and break existing functionality.
* **Why:** OCP reduces the risk of introducing bugs when adding new features. It encourages the use of polymorphism and dependency injection, making components more flexible and reusable.
"""python
# Good: Shape interface and concrete implementations
from abc import ABC, abstractmethod
class Shape(ABC): # Abstraction
@abstractmethod
def area(self):
pass
class Rectangle(Shape): # Extension without Modification
def __init__(self, width, height):
self.width = width
self.height = height
def area(self):
return self.width * self.height
class Circle(Shape): # Extension without Modification
def __init__(self, radius):
self.radius = radius
def area(self):
return 3.14159 * self.radius * self.radius
# Bad: Modifying existing code to add new shape logic
class AreaCalculator: # Violates OCP
def calculate_area(self, shape_type, dimensions):
if shape_type == "rectangle":
# Rectangle area calculation
pass
elif shape_type == "circle":
# Circle area calculation (Adding new shape requires modifying this function)
pass
"""
### 2.3. Liskov Substitution Principle (LSP)
* **Do This:** Ensure that subtypes can be used interchangeably with their base types without altering the correctness of the program.
* **Don't Do This:** Create subtypes that violate the behavior expected of their base types.
* **Why:** LSP ensures that inheritance is used correctly, leading to more robust and predictable code. It simplifies testing and reduces the risk of unexpected behavior.
"""python
# Good: Subclass adheres to the contract of superclass
class Bird:
def fly(self):
return "Flying"
class Sparrow(Bird):
def fly(self): # maintains same behaviour as Bird
return "Sparrow flying"
# Bad: Subclass violates the contract of the superclass
class Square:
def __init__(self, side):
self._side = side
def set_width(self, width):
self._side = width
def set_height(self, height):
self._side = height
def get_area(self):
return self._side * self._side
class Rectangle(Square): # Rectangle violates LSP, because a rectangle does not HAVE to have equal sides
def set_width(self, width):
self._side = width
def set_height(self, height):
self._side = height
"""
### 2.4. Interface Segregation Principle (ISP)
* **Do This:** Design interfaces that are specific to the needs of the clients that use them. Avoid creating large, monolithic interfaces that force clients to implement methods they don't need.
* **Don't Do This:** Create "fat" interfaces that have many methods, some of which may be irrelevant to certain clients.
* **Why:** ISP reduces coupling and improves cohesion. It allows clients to depend only on the methods they actually use, making the system more flexible and maintainable.
"""python
# Good: Separate interfaces for different client needs
from abc import ABC, abstractmethod
class Worker(ABC):
@abstractmethod
def work(self):
pass
class Eater(ABC):
@abstractmethod
def eat(self):
pass
class Human(Worker, Eater):
def work(self):
return "Human working"
def eat(self):
return "Human eating"
# Bad: Single interface forces clients to implement unnecessary methods
class IWorker(ABC): # Fat interface
@abstractmethod
def work(self):
pass
@abstractmethod
def eat(self):
pass
class Robot(IWorker): # Forced to implement eat even though it isn't required
def work(self):
return "Robot working"
def eat(self):
raise NotImplementedError("Robots don't eat")
"""
### 2.5. Dependency Inversion Principle (DIP)
* **Do This:** Depend on abstractions, not concretions. High-level modules should not depend on low-level modules. Both should depend on abstractions.
* **Don't Do This:** High-level modules depending directly on low-level modules.
* **Why:** DIP reduces coupling and improves modularity. It makes it easier to change the implementation of a component without affecting its clients.
"""python
# Good: High-level module depends on abstraction
from abc import ABC, abstractmethod
class Switchable(ABC): # Abstraction
@abstractmethod
def turn_on(self):
pass
@abstractmethod
def turn_off(self):
pass
class LightBulb(Switchable):
def turn_on(self):
return "LightBulb: on..."
def turn_off(self):
return "LightBulb: off..."
class ElectricPowerSwitch: # High-level module does not depend on LightBulb. Abstraction.
def __init__(self, client: Switchable):
self.client = client
self.on = False
def press(self):
if self.on:
self.client.turn_off()
self.on = False
else:
self.client.turn_on()
self.on = True
# Bad: High-level module depends on concretion
class LightBulb_Bad:
def turn_on(self):
return "LightBulb: on..."
def turn_off(self):
return "LightBulb: off..."
class ElectricPowerSwitch_Bad: # High-level module (ElectricPowerSwitch) now directly coupled to the low-level module (LightBulb)
def __init__(self, client: LightBulb_Bad):
self.client = client
self.on = False
def press(self):
if self.on:
self.client.turn_off()
self.on = False
else:
self.client.turn_on()
self.on = True
"""
## 3. TDD-Specific Component Design Practices
These practices are specifically geared toward component design within a TDD workflow.
### 3.1. Starting with the Test (Red Phase)
* **Do This:** Write a test that defines the *expected behavior* of the component *before* writing any implementation code. This forces you to think about the component's interface and responsibilities.
* **Don't Do This:** Start coding the component's implementation first, and then write tests afterward. This often leads to poorly designed, difficult-to-test components.
* **Why:** Starting with the test ensures that the component is designed to be testable and that it meets the specific requirements of the application. It also aids in defining the API of the component with minimal bias toward implementation details.
"""python
# Example: Test for a simple calculator component
import unittest
class TestCalculator(unittest.TestCase):
def test_add(self):
calculator = Calculator()
self.assertEqual(calculator.add(2, 3), 5) # Write this test FIRST
class Calculator: #Implemented AFTER the test is written. Forces you to write tests before methods in the class. The focus is on the expected function.
def add(self, x, y):
return x + y
"""
### 3.2. Test-Driven APIs
* **Do This:** Use tests to drive the development of your component's API. Each test should focus on a specific aspect of the API, such as input validation, error handling, or return values.
* **Don't Do This:** Design the API based on intuition or guesswork. This can lead to APIs that are difficult to use or that do not meet the needs of the application. Design the full system based on API.
* **Why:** Test-driven APIs are more likely to be well-designed, easy to use, and meet the specific requirements of the application. They are also fully documented by the tests themselves.
"""python
# Example: Test-driven API for a user authentication component
import unittest
class TestUserAuthentication(unittest.TestCase):
def test_authenticate_valid_user(self):
auth = UserAuthentication()
self.assertTrue(auth.authenticate("valid_user", "password"))
def test_authenticate_invalid_user(self):
auth = UserAuthentication()
self.assertFalse(auth.authenticate("invalid_user", "password"))
class UserAuthentication: # Test drives the creation of the authentication function
def authenticate(self, username, password):
if username == "valid_user" and password == "password":
return True
else:
return False
"""
### 3.3. Mocking and Dependency Injection
* **Do This:** Use mocking frameworks to isolate components under test. Inject dependencies into components to make them more testable and flexible. Use existing frameworks where possible.
* **Don't Do This:** Create tight coupling between components, making it difficult to test them in isolation.
* **Why:** Mocking and dependency injection allow you to test components in isolation, without relying on external dependencies. This leads to more reliable and faster tests. It also promotes loose coupling, which is a key principle of good component design.
"""python
# Example: Using a mock to test a component that depends on a database
import unittest
from unittest.mock import Mock
class UserService:
def __init__(self, db_service):
self.db_service = db_service
def get_user(self, user_id):
return self.db_service.get_user(user_id)
class TestUserService(unittest.TestCase):
def test_get_user(self):
mock_db = Mock() # DB mock to isolate component for testing
mock_db.get_user.return_value = {"id": 1, "name": "Test User"}
user_service = UserService(mock_db)
user = user_service.get_user(1)
self.assertEqual(user["name"], "Test User")
"""
### 3.4. Refactoring for Component Design
* **Do This:** Use the refactor phase of TDD to improve the design of your components. Look for opportunities to apply the SOLID principles, reduce duplication, and improve readability. Consider DRY (Don't Repeat Yourself).
* **Don't Do This:** Neglect the refactor phase. This leads to technical debt and makes the code harder to maintain over time.
* **Why:** Refactoring is an essential part of TDD. It allows you to continuously improve the design of your components, making them more maintainable, reusable, and testable. The Green phase ensures you refactor with confidence and minimal risk, as your existing tests should all still pass if refactoring is done correctly.
"""python
# Example: Refactoring to extract a common method
class OrderProcessor: # Refactor to remove duplicate code
def process_order(self, order):
# ...
self._send_notification(order, "Order processed")
def cancel_order(self, order):
# ...
self._send_notification(order, "Order cancelled")
def _send_notification(self, order, message): # common method
# Send order notification (DRY)
pass
"""
## 4. Modern Approaches and Patterns
Incorporate these patterns and approaches to build robust and scalable systems.
### 4.1. Microservices Architecture
* **Do This:** Design components as independent, deployable services. Use APIs for communication between microservices.
* **Don't Do This:** Build monolithic applications where components are tightly coupled and deployed as a single unit.
* **Why:** They enable independent scaling and deployment, fault isolation, and technology diversity.
### 4.2. Event-Driven Architecture
* **Do This:** Design components to react to events. Use message queues or event buses for asynchronous communication.
* **Don't Do This:** Rely on synchronous, request-response patterns for all interactions between components.
* **Why:** Event-Driven Architectures makes the application more responsive, scalable, and resilient.
### 4.3. Domain-Driven Design (DDD)
* **Do This:** Align component design with the business domain. Model components around domain entities and concepts. Use ubiquitous language.
* **Don't Do This:** Design components based solely on technical considerations.
* **Why:** DDD helps ensure that the software accurately reflects the business requirements, making it easier to understand and maintain.
### 4.4. CQRS (Command Query Responsibility Segregation)
* **Do This:** Separate the read and write operations of a data store or component. Use separate models for commands (write) and queries (read).
* **Don't Do This:** Use the same model for both reading and writing data.
* **Why:** CQRS allows you to optimize the read and write paths independently, improving performance and scalability.
### 4.5. Functional Programming
* **Do This:** Design components as pure functions that have no side effects. Use immutable data structures.
* **Don't Do This:** Create components that rely on mutable state and side effects, making them harder to test and reason about.
* **Why:** Promotes clearer, more testable code since the component's behaviours are deterministic and contained.
## 5. Common Anti-Patterns and Mistakes
Avoid these common pitfalls to ensure that component design remains effective, maintainable, and aligned with TDD principles.
### 5.1. God Components
* **Description:** A component that knows too much or does too much.
* **Solution:** Apply the Single Responsibility Principle to break down the component into smaller, more focused components.
### 5.2. Tight Coupling
* **Description:** Components that are highly dependent on each other.
* **Solution:** Use dependency injection, interfaces, and abstractions to decouple components.
### 5.3. Shotgun Surgery
* **Description:** A change in one part of the system requires changes in many other parts.
* **Solution:** Apply the Open/Closed Principle and encapsulate changes within well-defined components.
### 5.4. Premature Optimization
* **Description:** Optimizing code before it is necessary.
* **Solution:** Focus on writing clear, testable code first. Optimize only when performance bottlenecks are identified through profiling. Write tests to measure performance before refactoring.
### 5.5. Ignoring Test Coverage
* **Description:** Not writing enough tests to cover all aspects of the component. Aim for high test coverage (80%+)
* **Solution:** Always prioritize writing comprehensive tests to cover all possible scenarios and edge cases. Use coverage tools to identify gaps and correct it by creating new tests and logic. Also, consider mutation testing.
## 6. Technology-Specific Details
This section provides specific examples tailored for different technologies (Python, Java, JavaScript, etc.), highlighting the nuances that differentiate good code from great code in each ecosystem. (Examples included will be limited to Python due to space, but structure should address how you would incorporate other modern popular languages)
### 6.1. Python-Specific Considerations
* **Do This:** Leverage Python's dynamic typing and duck typing to create flexible and reusable components. Use decorators for cross-cutting concerns. Use type hints for improved code clarity and maintainability where appropriate.
"""python
# Example: Using a decorator for caching
import functools
def cache(func):
@functools.wraps(func)
def wrapper(*args, **kwargs):
if args in wrapper.cache:
return wrapper.cache[args]
else:
result = func(*args, **kwargs)
wrapper.cache[args] = result
return result
wrapper.cache = {}
return wrapper
"""
### 6.2. Java-Specific Considerations
(Placeholder: This section would contain Java-specific details, e.g., using Spring Framework for dependency injection, leveraging the Java Collections Framework, etc.)
### 6.3. JavaScript-Specific Considerations
(Placeholder: This section would contain JavaScript-specific details, e.g., using React components, leveraging ES6+ features, using testing frameworks like Jest or Mocha, etc.)
### 6.4 C#-Specific Considerations
(Placeholder: This section would contain C#-specific details, e.g., using .NET's built-in dependency injection and testing framework)
## 7. Conclusion
Adhering to these component design standards within a TDD workflow will lead to more maintainable, testable, and reusable code. By embracing these principles and practices, developers can build robust and scalable systems that meet the evolving needs of the business. When in doubt, always strive to write tests that drive the design of your components, promoting modularity, loose coupling, and clear responsibilities. Continuous refactoring, guided by a comprehensive test suite, will ensure that the code remains clean, efficient, and easy to understand. This document should be kept up-to-date with the latest developments in TDD.
danielsogl
Created Mar 6, 2025
# Core Architecture Standards for TDD
This document outlines the core architectural standards for Test-Driven Development (TDD). Adhering to these standards improves code quality, maintainability, and testability. These standards are designed to be used by developers and as context for AI coding assistants, ensuring consistency and best practices across the development lifecycle. The goal is to ensure that architectural decisions are strongly aligned with the testability demands of TDD.
## 1. Architectural Principles and Patterns
### 1.1. Fundamental Principles
* **Do This:** Apply SOLID principles at the architectural level. Specifically, strive for single responsibility at multiple levels of abstraction (e.g. modules, packages, services), open/closed principle in framework design or component architecture.
* **Don't Do This:** Create monolithic applications with tightly coupled components. This makes testing difficult and hinders future modifications.
* **Why:** SOLID principles promote loosely coupled, modular designs that facilitate independent testing of components.
* **Do This:** Prioritize separation of concerns (SoC). Architect your application by dividing it into distinct sections, each addressing a specific concern.
* **Don't Do This:** Mix unrelated functionalities within a single module or class. This leads to code that is hard to understand, test, and maintain.
* **Why:** Separation of concerns improves code organization and allows for isolated testing and easier modification of individual features.
* **Do This:** Embrace the Dependency Inversion Principle (DIP). Abstractions should not depend on details; details should depend on abstractions.
* **Don't Do This:** Hardcode concrete dependencies. This makes classes difficult to test in isolation.
* **Why:** DIP enables the use of dependency injection and mocking, allowing tests to control dependencies and verify interactions.
* **Do This:** Ensure the architecture facilitates testability and maintainability. Tests should be easy to write, run, and understand.
* **Don't Do This:** Defer testability considerations to the later phases of development, assuming that tests can always be added later with minimal refactoring.
* **Why:** This makes systems more robust, easier to maintain, and ensures comprehensive testing throughout the development process.
### 1.2. Architectural Patterns Tailored for TDD
* **Do This:** Favor a layered architecture. Typically, this involves a presentation layer, an application layer, a domain layer, and an infrastructure layer each serving a specific purpose.
* **Don't Do This:** Directly accessing the database from the presentation logic. Violating layers boundaries makes it extremely difficult to thoroughly test at the layer level.
* **Why:** Layered Architecture allows for a clear separation of concerns. Each layer can be tested independently using mocks or stubs.
"""python
# Example of Layered Architecture in Python (simplified web application)
# Infrastructure Layer (Data Access)
class UserRepository:
def get_user_by_id(self, user_id):
# Database logic to retrieve user
pass
# Domain Layer (Business Logic)
class UserService:
def __init__(self, user_repository: UserRepository):
self.user_repository = user_repository
def get_user_profile(self, user_id):
user = self.user_repository.get_user_by_id(user_id)
# Additional business logic
return user
# Application Layer (API Endpoints)
from flask import Flask, jsonify
app = Flask(__name__)
user_repository = UserRepository()
user_service = UserService(user_repository)
@app.route("/users/<int:user_id>", methods=['GET'])
def get_user(user_id):
user = user_service.get_user_profile(user_id)
return jsonify(user)
if __name__ == '__main__':
app.run(debug=True)
# Example Test (testing the Application Layer, mocking the domain layer). Note this example uses pytest.
import pytest
from unittest.mock import MagicMock
from your_app import get_user, user_service # Adjust import
@pytest.fixture
def mock_user_service(monkeypatch):
mock = MagicMock()
monkeypatch.setattr(your_app, 'user_service', mock) # adjust import
return mock
def test_get_user_success(mock_user_service):
mock_user_service.get_user_profile.return_value = {"id": 1, "name": "Test User"}
response = get_user(1) # Assume this returns Flask's response object
assert response.status_code == 200
assert response.get_json() == {"id": 1, "name": "Test User"}
"""
* **Do This:** Consider Hexagonal Architecture (Ports and Adapters). Place the core business logic at the center, surrounded by ports (interfaces) and adapters (implementations).
* **Don't Do This:** Directly couple the core business logic to external technologies (e.g., databases or UI frameworks).
* **Why:** Hexagonal Architecture separates the domain logic from the infrastructure, enabling easier testing with mock adapters and simplifies swapping out external dependencies.
"""java
// Example of Hexagonal Architecture in Java
// Port (Interface)
interface UserRepository {
User getUserById(String userId);
}
// Adapter (Implementation)
class PostgresUserRepository implements UserRepository {
@Override
public User getUserById(String userId) {
// Implementation using Postgres database
return new User(); //dummy. replace with DB fetch
}
}
// Domain (Core Business Logic)
class UserService {
private final UserRepository userRepository;
public UserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
public User getUserProfile(String userId) {
return userRepository.getUserById(userId);
// Add business logic
}
}
// Test using a mock adapter. Demonstrates flexibility of swapping implementations through ports.
import org.junit.jupiter.api.Test;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;
class UserServiceTest {
@Test
void getUserProfile_shouldReturnUser_whenUserExists() {
// Arrange
UserRepository mockUserRepository = mock(UserRepository.class);
User expectedUser = new User(); //replace with some populated User class
when(mockUserRepository.getUserById("123")).thenReturn(expectedUser);
UserService userService = new UserService(mockUserRepository);
// Act
User actualUser = userService.getUserProfile("123");
// Assert
assertEquals(expectedUser, actualUser);
verify(mockUserRepository).getUserById("123"); // Verify the method was called
}
}
"""
* **Do This:** When developing microservices apply the strangler fig pattern to iteratively migrate from an older monolithic architecture to a new microservices-based architecture.
* **Don't Do This:** Attempt a "big bang" rewrite by rebuilding an entire application as microservices at once.
* **Why:** This allows for incremental building and rollout. Old functionality remains in place until the new microservice is thoroughly tested and ready for production.
### 1.3. Project Structure & Organization
* **Do This:** Structure your project according to architectural layers or modules, keeping test code alongside the corresponding source code. A common practice is to have "src/" and "tests/" directories at the root level, mirroring package structures within each.
* **Don't Do This:** Place all tests in a single, monolithic "tests/" directory. This becomes unwieldy and difficult to navigate as the project grows.
* **Why:** This organization improves discoverability and helps maintain a clear relationship between code and its corresponding tests.
"""
project-root/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ ├── com/
│ │ │ │ └── example/
│ │ │ │ ├── domain/
│ │ │ │ │ ├── User.java
│ │ │ │ │ └── UserService.java
│ │ │ │ ├── infrastructure/
│ │ │ │ │ └── UserRepository.java
│ │ │ │ └── api/
│ │ │ │ └── UserController.java
├── tests/
│ ├── test/
│ │ ├── java/
│ │ │ ├── com/
│ │ │ │ └── example/
│ │ │ │ ├── domain/
│ │ │ │ │ └── UserServiceTest.java
│ │ │ │ ├── infrastructure/
│ │ │ │ │ └── UserRepositoryTest.java
│ │ │ │ └── api/
│ │ │ │ └── UserControllerTest.java
├── pom.xml (Maven project)
"""
* **Do This:** Use meaningful package and class names. Reflect the domain and functionality.
* **Don't Do This:** Use generic names like "Util" or "Manager" without specific contexts.
* **Why:** Improves code readability and maintainability across the project.
* **Do This:** Keep modules small and cohesive. A module should have a focused responsibility and a well-defined interface.
* **Don't Do This:** Create "god classes" or modules that try to do too much.
* **Why:** Small modules are easier to understand, test, and reuse. This increases development speed and significantly lowers debugging costs.
## 2. TDD Workflow and Integration with Architecture
### 2.1. Red-Green-Refactor Cycle
* **Do This:** Strictly adhere to the Red-Green-Refactor cycle. Write a failing test first (Red), implement the minimum amount of code to make the test pass (Green), and then refactor the code to improve its design (Refactor).
* **Don't Do This:** Write code without a failing test, or skip the refactoring step.
* **Why:** The Red-Green-Refactor cycle ensures that code is written to satisfy specific requirements and that it is continuously improved.
### 2.2. Test Pyramid
* **Do This:** Follow the test pyramid: Aim for many unit tests, fewer integration tests, and even fewer end-to-end tests. Focus the majority of testing efforts on unit tests.
* **Don't Do This:** Rely heavily on end-to-end tests at the expense of unit tests. This leads to slow and brittle test suites.
* **Why:** Unit tests are faster to write and execute and provide more precise feedback. Integration tests verify interactions between components, while end-to-end tests ensure the application works as a whole.
### 2.3. Integrating Tests with Build and CI/CD pipelines
* **Do This:** Integrate tests into the build process and CI/CD pipeline. Ensure that all tests pass before deploying any code.
* **Don't Do This:** Defer running tests to manual execution or skip tests in the CI/CD pipeline to speed up deployments.
* **Why:** Continuous testing ensures that any regressions are detected early and that the application remains in a working state.
"""yaml
# Example of CI/CD Pipeline with Tests (GitHub Actions)
name: CI/CD
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'temurin'
- name: Grant execute permission for gradlew
run: chmod +x gradlew
- name: Run Tests with Gradle
run: ./gradlew test
- name: Build with Gradle
run: ./gradlew build
- name: Upload a Build Artifact
uses: actions/upload-artifact@v3
with:
name: Package
path: build/libs/
"""
## 3. Testing Techniques and Tools
### 3.1. Unit Testing
* **Do This:** Write focused unit tests that isolate and verify the behavior of individual classes or functions.
* **Don't Do This:** Write overly complex unit tests that test multiple aspects of a component at once.
* **Why:** Focused unit tests are easier to understand, maintain, and debug.
"""java
// Example of Focused Unit Test (Java with JUnit)
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
class StringUtils {
public static String reverseString(String input) {
return new StringBuilder(input).reverse().toString();
}
}
class StringUtilsTest {
@Test
void reverseString_shouldReturnReversedString() {
String input = "hello";
String expected = "olleh";
String actual = StringUtils.reverseString(input);
assertEquals(expected, actual);
}
@Test
void reverseString_shouldReturnEmptyString_whenInputIsEmpty() {
String input = "";
String expected = "";
String actual = StringUtils.reverseString(input);
assertEquals(expected, actual);
}
}
"""
### 3.2. Mocking and Stubbing
* **Do This:** Use mocking frameworks to isolate classes under test and control their dependencies.
* **Don't Do This:** Mock everything. Only mock dependencies that are external or complex to set up.
* **Why:** Mocking enables testing in isolation and verifying interactions between components.
"""python
# Example of Mocking in Python using pytest and unittest.mock
import pytest
from unittest.mock import MagicMock
class EmailService:
def send_email(self, recipient, message):
# Implementation to send an email
print(f"Sending email to {recipient}: {message}")
class UserService:
def __init__(self, email_service: EmailService):
self.email_service = email_service
def register_user(self, username, email):
# Logic to register user
self.email_service.send_email(email, f"Welcome, {username}!")
return {"username": username, "email": email}
@pytest.fixture
def mock_email_service():
return MagicMock()
def test_register_user_sends_email(mock_email_service):
user_service = UserService(mock_email_service)
user = user_service.register_user("testuser", "test@example.com")
mock_email_service.send_email.assert_called_once_with("test@example.com", "Welcome, testuser!")
assert user == {"username": "testuser", "email": "test@example.com"}
#Another Example
import unittest
from unittest.mock import patch
def add(x, y):
return x + y
class TestAdd(unittest.TestCase):
@patch('__main__.add')
def test_add(self, mock_add):
mock_add.return_value = 5
result = add(2, 3)
self.assertEqual(result, 5) # Assert that the mock was used and returned 5
mock_add.assert_called_with(2, 3) # assert that the proper arguments were utilized
"""
### 3.3. Integration Testing
* **Do This:** Write integration tests to verify the interaction between different components or modules.
* **Don't Do This:** Test the complete system in integration tests. Focus on verifying specific interactions.
* **Why:** Integration tests ensure that components work correctly together.
### 3.4. End-to-End Testing
* **Do This:** Use end-to-end testing to ensure the entire application works as expected from the user's perspective.
* **Don't Do This:** Rely solely on end-to-end tests. They are slow and difficult to debug.
* **Why:** End-to-end tests provide confidence that the application delivers the expected functionality.
## 4. Technology Specific Details
### 4.1. Java and Spring Boot
* **Do This:** Use Spring's testing support ("@SpringBootTest", "@MockBean") for integration and unit testing. These annotations and classes provide convenient ways to load application contexts and mock dependencies.
* **Don't Do This:** Manually create and manage Spring application contexts in tests unless absolutely necessary. Spring's testing support simplifies this process.
* **Why:** Spring's testing framework integrates seamlessly with JUnit and provides powerful features for testing Spring applications. Using these features results in cleaner, more maintainable tests.
"""java
@SpringBootTest // Loads the full application context
class MyServiceIntegrationTest {
@Autowired
private MyService myService;
@MockBean // Replaces the real bean with a mock
private Dependency dependency;
@Test
void testSomething() {
// Configure the mock
when(dependency.doSomething()).thenReturn("mockedResult");
// Call the service method
String result = myService.performAction();
// Assert the result and verify interactions
assertEquals("expectedResult", result);
verify(dependency).doSomething();
}
}
"""
### 4.2 Python Testing with Pytest
* **Do This:** Use pytest fixtures for setup and teardown in tests. Fixtures help manage test resources and dependencies in a clean and reusable manner.
* **Don't Do This:** Directly instantiate objects or manage resources within test functions. This makes tests harder to read and maintain.
* **Why:** Pytest fixtures promote clean test code and facilitate the creation of reusable test components.
"""python
# Example of Test using Pytest Fixtures
import pytest
from unittest.mock import MagicMock
class DatabaseConnection: #Dummy DB connector class
def connect(self):
return True
def disconnect(self):
return True
@pytest.fixture
def mock_db_connection():
connection = MagicMock(spec=DatabaseConnection) # create a "fake" Database connector class
connection.connect.return_value = True
yield connection
connection.disconnect()
def test_database_interaction(mock_db_connection):
# Your test logic here, using the mocked database connection
mock_db_connection.connect.assert_called_once() # assert that the db connected
"""
### 4.3 Javascript testing with Jest
* **Do This:** Use Jest's mocking utilities ("jest.mock()", "jest.spyOn()") to mock dependencies and verify function calls. This makes it easier to isolate units of code and ensures they behave as expected.
* **Don't Do This:** Manually mock dependencies by creating mock objects and functions. Jest provides built-in utilities that simplify this process.
* **Why:** Using Jest's mocking utilities results in cleaner and more maintainable tests. They also provide enhanced features for verifying function calls and interactions.
"""javascript
// Example of Mocking in Jest
// myModule.js
export const fetchData = async () => {
const response = await fetch('/api/data');
const data = await response.json();
return data;
};
// myModule.test.js
import { fetchData } from './myModule';
global.fetch = jest.fn(() => // Mock the global fetch function
Promise.resolve({
json: () => Promise.resolve({ key: 'mocked value' }),
})
);
test('fetchData should return mocked value', async () => {
const result = await fetchData();
expect(result).toEqual({ key: 'mocked value' });
expect(fetch).toHaveBeenCalledTimes(1);
});
"""
## 5. Common Anti-Patterns and Mistakes
* **Long Setup:** Tests with excessive setup code become difficult to read and maintain. Simplify test setup by using helper functions or fixtures.
* **Testing Implementation Details:** Tests should focus on verifying behavior, not implementation details. Avoid asserting on private methods or internal state.
* **Ignoring Edge Cases:** Always test edge cases and boundary conditions to ensure code handles unexpected input correctly.
* **Insufficient Assertions:** When running tests in Green after Red, tests with too few assertions may pass without sufficiently validating. Use multiple assertions to make sure all aspects have been validated to the requirements.
By adhering to these core architecture standards, development teams can leverage TDD to build robust, maintainable, and testable software applications. This comprehensive guide serves as a valuable resource for developers and AI coding assistants to ensure consistency and best practices throughout the development lifecycle.
danielsogl
Created Mar 6, 2025
# State Management Standards for TDD
This document outlines coding standards for managing application state, data flow, and reactivity within a Test-Driven Development (TDD) environment. The focus is on ensuring maintainability, performance, security, and testability of state management solutions, embracing modern approaches and patterns.
## 1. Core Principles of State Management in TDD
### 1.1. Unidirectional Data Flow
**Do This:** Embrace unidirectional data flow patterns like Flux, Redux, or their reactive counterparts (e.g., RxJS-based state management, Vuex). Data should flow in a single direction, making state changes predictable and traceable.
**Don't Do This:** Avoid two-way data binding or direct state mutations within components/services. These practices create implicit dependencies and make debugging and testing significantly harder.
**Why:** Unidirectional data flow simplifies testing because each state change is triggered by a specific action and results in a predictable new state. This makes it easier to write specific, isolated tests. Additionally, it prevents unexpected side effects, improving code reliability and decreasing debugging time.
**Code Example (Redux Style - TypeScript/JavaScript):**
"""typescript
// actions.ts
export const INCREMENT = 'INCREMENT';
interface IncrementAction {
type: typeof INCREMENT;
}
export const increment = (): IncrementAction => ({
type: INCREMENT,
});
export type AppActions = IncrementAction;
// reducer.ts
interface AppState {
count: number;
}
const initialState: AppState = {
count: 0,
};
export const appReducer = (state: AppState = initialState, action: AppActions): AppState => {
switch (action.type) {
case INCREMENT:
return { ...state, count: state.count + 1 };
default:
return state;
}
};
// component.ts (Example using React Hooks)
import React, { useReducer } from 'react';
import { appReducer, AppActions } from './reducer';
import { increment } from './actions';
interface Props {}
const CounterComponent: React.FC<Props> = () => {
const [state, dispatch] = useReducer(appReducer, { count: 0 });
const handleIncrement = () => {
dispatch(increment());
};
return (
<div>
<p>Count: {state.count}</p>
<button onClick={handleIncrement}>Increment</button>
</div>
);
};
export default CounterComponent;
// Test example (Jest/Enzyme or React Testing Library)
import { appReducer, AppActions } from './reducer';
import { increment } from './actions';
describe('appReducer', () => {
it('should increment the count', () => {
const initialState = { count: 0 };
const action: AppActions = increment();
const newState = appReducer(initialState, action);
expect(newState.count).toBe(1);
});
it('should return the current state if action is unknown', () => {
const initialState = { count: 0 };
const action = { type: 'UNKNOWN' };
const newState = appReducer(initialState, action as any); // Explicit cast to 'any' since 'action' isn't properly typed
expect(newState).toBe(initialState);
});
});
"""
### 1.2. Immutability
**Do This:** Treat state as immutable. Use techniques like "Object.assign({}, state, change)" or the spread operator ("{...state, ...change}") to create new state objects instead of directly modifying the existing ones. For complex data structures, consider leveraging immutable data libraries (e.g., Immutable.js).
**Don't Do This:** Directly modify state objects (e.g., "state.property = newValue").
**Why:** Immutability simplifies change detection, enables time-travel debugging, and makes testing easier. It avoids side effects and unexpected behavior when multiple parts of the application share the same state. React (and many other frameworks) are heavily optimized for immutable state.
**Code Example (Immutability with Spread Operator):**
"""typescript
interface User {
id: number;
name: string;
email: string;
}
interface UserState {
users: User[];
}
const initialState: UserState = {
users: [{ id: 1, name: 'John Doe', email: 'john.doe@example.com' }],
};
const updatedUser = { id: 1, name: 'Jane Doe', email: 'jane.doe@example.com' };
const updatedState: UserState = {
...initialState,
users: initialState.users.map((user) => (user.id === updatedUser.id ? { ...user, ...updatedUser } : user)),
};
// Test Example
describe('UserState', () => {
it('should update a user immutably', () => {
const initialState: UserState = {
users: [{ id: 1, name: 'John Doe', email: 'john.doe@example.com' }],
};
const updatedUser = { id: 1, name: 'Jane Doe', email: 'jane.doe@example.com' };
const updatedState: UserState = {
...initialState,
users: initialState.users.map((user) => (user.id === updatedUser.id ? { ...user, ...updatedUser } : user)),
};
expect(updatedState.users[0].name).toBe('Jane Doe');
expect(initialState.users[0].name).toBe('John Doe'); // Ensure original state wasn't mutated
});
});
"""
### 1.3. Single Source of Truth
**Do This:** Designate one place in your application as the single source of truth for your state. This could be a Redux store, a MobX observable, or a Vuex store.
**Don't Do This:** Duplicate state across multiple components or services. This leads to inconsistencies and makes it difficult to manage updates.
**Why:** A single source of truth ensures consistency and simplifies debugging. Changes to the state are centralized and easy to track. It also significantly simplifies testing, allowing you to focus on the state management logic without worrying about side effects.
**Code Example (Simple Shared State with Context - React):**
"""typescript
// StateContext.tsx
import React, { createContext, useState, useContext } from 'react';
interface AppState {
theme: 'light' | 'dark';
}
interface StateContextProps {
state: AppState;
toggleTheme: () => void;
}
const StateContext = createContext<StateContextProps | undefined>(undefined);
export const StateProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
const [theme, setTheme] = useState<AppState['theme']>('light');
const toggleTheme = () => {
setTheme((prevTheme) => (prevTheme === 'light' ? 'dark' : 'light'));
};
const value: StateContextProps = {
state: { theme },
toggleTheme,
};
return <StateContext.Provider value={value}>{children}</StateContext.Provider>;
};
export const useStateContext = () => {
const context = useContext(StateContext);
if (!context) {
throw new Error('useStateContext must be used within a StateProvider');
}
return context;
};
// Component using the context
// ThemeToggler.tsx
import React from 'react';
import { useStateContext } from './StateContext';
const ThemeToggler: React.FC = () => {
const { state, toggleTheme } = useStateContext();
return (
<div>
<p>Current Theme: {state.theme}</p>
<button onClick={toggleTheme}>Toggle Theme</button>
</div>
);
};
export default ThemeToggler;
// Test Example (Testing the Context Provider and consumer)
import { render, screen, fireEvent } from '@testing-library/react';
import { StateProvider, useStateContext } from './StateContext';
import ThemeToggler from './ThemeToggler';
describe('StateContext', () => {
it('should provide initial state and allow updates', () => {
const TestComponent = () => {
const { state, toggleTheme } = useStateContext();
return (
<div>
<p>Theme: {state.theme}</p>
<button onClick={toggleTheme}>Toggle</button>
</div>
);
};
render(
<StateProvider>
<TestComponent />
</StateProvider>
);
expect(screen.getByText('Theme: light')).toBeInTheDocument();
fireEvent.click(screen.getByText('Toggle'));
expect(screen.getByText('Theme: dark')).toBeInTheDocument();
});
it('should throw an error if used outside StateProvider', () => {
const TestComponent = () => {
useStateContext(); // Intentionally called outside the provider
return null;
};
const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {}); // Suppress React's error message momentarily
expect(() => render(<TestComponent />)).toThrowError('useStateContext must be used within a StateProvider');
consoleErrorSpy.mockRestore();
});
});
"""
### 1.4. Explicit Actions and Mutations
**Do This:** Use explicit actions to initiate state changes. In Redux, these are actions dispatched to the store. In Vuex, these are mutations committed to the store.
**Don't Do This:** Directly modify the state within components or services without going through defined actions or mutations.
**Why:** Explicit actions and mutations provide a clear audit trail of how the state changes over time. This is invaluable for debugging and understanding application behavior. Tests can be written to verify that specific actions trigger the correct state transitions.
**Code Example (Vuex/Redux similarities using actions):**
"""typescript
// Vuex store example - mutations trigger state changes
// store.ts
import Vue from 'vue';
import Vuex from 'vuex';
Vue.use(Vuex);
interface State {
count: number;
}
const store = new Vuex.Store<State>({
state: {
count: 0,
},
mutations: {
increment(state: State) {
state.count++;
},
decrement(state: State) {
state.count--;
},
},
actions: {
incrementAsync({ commit }) {
setTimeout(() => {
commit('increment');
}, 1000);
},
},
getters: {
getCount: (state: State) => state.count,
}
});
export default store;
// Component using the action (e.g., increment)
// CounterComponent.vue
<template>
<div>
<p>Count: {{ count }}</p>
<button @click="increment">Increment</button>
</div>
</template>
<script>
import { mapGetters, mapActions } from 'vuex';
export default {
computed: {
...mapGetters(['getCount']),
count() {
return this.getCount;
}
},
methods: {
...mapActions(['increment']),
}
};
</script>
// Testing Vuex actions and mutations
// store.spec.ts
import store from './store';
describe('Vuex Store', () => {
it('should increment the count', () => {
store.commit('increment');
expect(store.state.count).toBe(1);
});
it('should decrement the count', () => {
store.commit('decrement');
expect(store.state.count).toBe(-1);
});
it('should increment the count asynchronously', (done) => {
store.dispatch('incrementAsync');
// Wait for the timeout defined in the action and then verify.
setTimeout(() => {
expect(store.state.count).toBe(0); // Assumes you're starting from 0
done(); // Signal that the asynchronous test is complete
}, 1100);
});
});
"""
### 1.5. Separation of Concerns
**Do This:** Keep state management logic separate from component logic. Use hooks, selectors, or connected components to access state and dispatch actions.
**Don't Do This:** Embed state management logic directly within components. This mixes concerns and makes testing difficult.
**Why:** Separation of concerns makes components more reusable and easier to test in isolation. It leads to a cleaner codebase with better organization and maintainability. State logic can be tested independently from the UI which increases confidence.
**Code Example (React Hooks with custom hook):**
"""typescript
// useCounter.ts (Custom Hook)
import { useState, useCallback } from 'react';
const useCounter = (initialValue: number = 0) => {
const [count, setCount] = useState(initialValue);
const increment = useCallback(() => {
setCount((prevCount) => prevCount + 1);
}, []);
const decrement = useCallback(() => {
setCount((prevCount) => prevCount - 1);
}, []);
return { count, increment, decrement };
};
export default useCounter;
// CounterComponent.ts (Component using the hook)
import React from 'react';
import useCounter from './useCounter';
const CounterComponent: React.FC = () => {
const { count, increment, decrement } = useCounter();
return (
<div>
<p>Count: {count}</p>
<button onClick={increment}>Increment</button>
<button onClick={decrement}>Decrement</button>
</div>
);
};
export default CounterComponent;
// Test Examples (testing the hook in isolation)
import { renderHook, act } from '@testing-library/react-hooks';
import useCounter from './useCounter';
describe('useCounter', () => {
it('should initialize the count to 0 by default', () => {
const { result } = renderHook(() => useCounter());
expect(result.current.count).toBe(0);
});
it('should initialize the count to the provided value', () => {
const { result } = renderHook(() => useCounter(10));
expect(result.current.count).toBe(10);
});
it('should increment the count', () => {
const { result } = renderHook(() => useCounter());
act(() => {
result.current.increment();
});
expect(result.current.count).toBe(1);
});
it('should decrement the count', () => {
const { result } = renderHook(() => useCounter());
act(() => {
result.current.decrement();
});
expect(result.current.count).toBe(-1);
});
});
"""
## 2. Technology-Specific Considerations
### 2.1. React
* **Context API:** Use the Context API for simple, application-wide state management scenarios. It's built into React and requires no external libraries. Prefer more robust solutions like Redux or Zustand for more complex applications.
* **Redux:** Redux requires boilerplate, but it provides a predictable state container, useful for debugging complex applications. Tools like Redux Toolkit minimize the boilerplate.
* **Zustand:** A small, fast, and scalable bearbones state-management solution using simplified flux principles.
* **Recoil:** Innovative state management library by Facebook focusing on granular state definition and efficient updates, especially for asynchronous data.
### 2.2. Angular
* **NgRx:** The Angular equivalent of Redux. Provides a reactive state management solution based on RxJS observables. Offers similar benefits of unidirectional data flow and immutability.
* **RxJS Observables with Services:** For simpler state management, leverage RxJS observables within Angular services. Components can subscribe to these observables to react to state changes. Avoid direct mutation, and use ".next()" on a Subject or BehaviorSubject to emit new immutable states.
### 2.3. Vue.js
* **Vuex:** Vue's official state management library. Similar to Redux but designed specifically for Vue.js. Enforces a strict unidirectional data flow pattern.
* **Provide/Inject:** Similar to React's Context API, "provide/inject" offers a way to share state across components without relying on props drilling, suitable for smaller to medium applications
* **Pinia:** Relatively new library which supersedes Vuex. Very similar with simpler syntax, and full TypeScript support.
## 3. Testing Strategies for State Management
### 3.1. Unit Testing Reducers/Mutations
**Do This:** Write unit tests for reducers (Redux) or mutations (Vuex) to verify that they correctly transform the state based on different actions.
**Don't Do This:** Neglect unit testing reducers/mutations. They are the core of your state management logic.
"""typescript
// Reducer test example
import { appReducer, AppActions } from './reducer';
import { increment } from './actions';
describe('appReducer', () => {
it('should increment the count', () => {
const initialState = { count: 0 };
const action: AppActions = increment();
const newState = appReducer(initialState, action);
expect(newState.count).toBe(1);
expect(newState).not.toBe(initialState); //Ensure immutability
});
});
"""
### 3.2. Testing Actions/Effects
**Do This:** Test actions (Redux) or effects (NgRx) to ensure they dispatch the correct sequence of actions, especially when dealing with asynchronous operations. Use mocking techniques to isolate the action/effect being tested.
"""typescript
// Redux thunk test example using redux-mock-store
import configureMockStore from 'redux-mock-store';
import thunk from 'redux-thunk';
import { fetchData } from './actions';
import * as api from './api'; // Mock API calls
const middlewares = [thunk];
const mockStore = configureMockStore(middlewares);
describe('async actions', () => {
it('dispatches FETCH_DATA_SUCCESS after successful API call', () => {
const mockData = [{ id: 1, name: 'Test' }];
jest.spyOn(api, 'fetchData').mockResolvedValue(mockData); // Mock the API call
const expectedActions = [
{ type: 'FETCH_DATA_REQUEST' },
{ type: 'FETCH_DATA_SUCCESS', payload: mockData }
];
const store = mockStore({ data: [] });
return store.dispatch(fetchData() as any).then(() => {
// return of async actions
expect(store.getActions()).toEqual(expectedActions);
});
});
});
"""
### 3.3. Integration Testing Components with State
**Do This:** Write integration tests to ensure that components correctly interact with the state management system. Mock the store or state provider to control the state and verify component behavior. Use UI testing libraries (e.g., React Testing Library, Cypress) to simulate user interactions.
"""typescript
// React Testing Library integration example
import { render, screen, fireEvent } from '@testing-library/react';
import { Provider } from 'react-redux';
import { createStore } from 'redux';
import CounterComponent from './CounterComponent';
import { appReducer } from './reducer';
import { increment } from './actions';
const mockStore = createStore(appReducer);
describe('CounterComponent integration', () => {
it('should increment the count when the button is clicked', () => {
const { getByText, dispatch } = render(
<Provider store={mockStore}>
<CounterComponent />
</Provider>
);
const incrementButton = getByText('Increment');
fireEvent.click(incrementButton);
expect(getByText('Count: 1')).toBeInTheDocument();
});
});
"""
### 3.4. End-to-End (E2E) Testing
**Do This:** Use E2E testing frameworks like Cypress or Playwright to test the entire data flow from the UI through the state management system to the backend (if applicable).
**Don't Do This:** Rely solely on E2E tests. They are slow and expensive to maintain. Use them to test critical user flows and integration points.
## 4. Common Anti-Patterns
* **Prop Drilling:** Passing props down through many layers of components. Use Context API, Redux, or similar to avoid this.
* **Mutating State Directly:** Causes unpredictable side effects. Always create new state objects immutably.
* **Over-Reliance on Global State:** Global state can become a bottleneck. Use local component state where appropriate.
* **Ignoring Asynchronous Operations:** Failing to handle asynchronous operations correctly in actions/effects can lead to race conditions and incorrect state updates.
* **Complex Selectors without Memoization:** Selectors that perform expensive computations should be memoized to prevent unnecessary re-renders and performance bottlenecks. Memoization libraries such as "reselect" should be considered for complex applications.
## 5. Performance Optimization
* **Memoization:** Use memoization techniques (e.g., "React.memo", "useMemo", "reselect") to avoid unnecessary re-renders of components that depend on state.
* **Code Splitting:** Split your application into smaller chunks to reduce the initial load time. State management libraries often support code splitting.
* **Selective State Updates:** Optimize state updates to only trigger updates when necessary. For example, avoid dispatching actions that result in no state change.
* **Immutable Data Structures:** Using libraries like Immutable.js can improve performance by optimizing change detection and reducing memory usage. However, be mindful of the potential overhead of these libraries.
## 6. Security Considerations
* **Avoid Storing Sensitive Data in Global State:** Sensitive data (e.g., passwords, API keys) should not be stored in the client-side state. Use secure storage mechanisms like cookies or browser storage with appropriate encryption.
* **Sanitize User Input:** When updating state based on user input, always sanitize the input to prevent XSS vulnerabilities.
* **Rate Limiting:** Implement rate limiting on actions that modify state to prevent abuse or denial-of-service attacks.
By adhering to these state management standards, development teams can build robust, maintainable, and testable TDD applications that are both performant and secure. Continuous review and refinement of these standards based on project needs and evolving technologies are highly recommended.
danielsogl
Created Mar 6, 2025
# Testing Methodologies Standards for TDD
This document outlines the coding standards for Testing Methodologies for TDD, focusing on unit, integration, and end-to-end testing strategies within the TDD workflow. It serves as a guide for developers and AI coding assistants.
## 1. Unit Testing in TDD
Unit testing is the foundation of TDD. It involves testing individual components or units of code in isolation.
### 1.1. Standards
* **Do This:** Write unit tests *before* writing any production code. This is the core principle of TDD.
* **Why:** This forces you to think about the desired behavior of the unit before implementation, leading to clearer design and more focused code.
* **Do This:** Test a single unit of code at a time, keeping tests small and focused. Each test should have a clear purpose and test a specific scenario.
* **Why:** Isolating units simplifies debugging and understanding. Smaller tests are easier to understand and maintain.
* **Do This:** Follow the AAA (Arrange, Act, Assert) pattern in your tests.
* **Why:** Enhances readability and clarity. The structure makes it easy to understand what is being tested, how it's being tested, and what the expected outcome is.
* **Do This:** Mock or stub external dependencies to isolate the unit under test.
* **Why:** Prevents external factors from influencing test results. This ensures deterministic and reliable tests. Allows for testing specific edge cases and error scenarios that might be difficult to trigger in a real environment.
* **Do This:** Aim for high code coverage, but don't treat it as the ultimate goal. Focus on testing critical functionalities and edge cases.
* **Why:** High coverage reduces the risk of regressions. However, meaningful tests that cover the core logic are more important than just achieving a high percentage.
* **Don't Do This:** Write tests that are tightly coupled to the implementation details of the unit under test.
* **Why:** Leads to brittle tests that break easily when the implementation changes, even if the functionality remains the same. Tests should focus on the *what*, not the *how*.
* **Don't Do This:** Neglect boundary conditions and edge cases.
* **Why:** These are often the source of bugs. Thoroughly testing these scenarios is crucial for robust code.
### 1.2. Code Examples (Python with "pytest" and "unittest.mock")
"""python
# Feature: Calculate discount based on the customer's spending tier.
# filename: discount_calculator.py
class DiscountCalculator:
def __init__(self, api_client):
self.api_client = api_client
def calculate_discount(self, customer_id, order_total):
customer_tier = self.api_client.get_customer_tier(customer_id)
if customer_tier == "Gold":
discount = 0.1 # 10% discount
elif customer_tier == "Silver":
discount = 0.05 # 5% discount
else:
discount = 0.0 # No discount
return order_total * discount
# filename: test_discount_calculator.py
import unittest
from unittest.mock import Mock
from discount_calculator import DiscountCalculator
class TestDiscountCalculator(unittest.TestCase):
def test_calculate_discount_gold_tier(self):
mock_api_client = Mock()
mock_api_client.get_customer_tier.return_value = "Gold" # Arrange
calculator = DiscountCalculator(mock_api_client)
discount = calculator.calculate_discount(123, 100) # Act
self.assertEqual(discount, 10.0) # Assert
def test_calculate_discount_silver_tier(self):
mock_api_client = Mock()
mock_api_client.get_customer_tier.return_value = "Silver" # Arrange
calculator = DiscountCalculator(mock_api_client)
discount = calculator.calculate_discount(456, 200) # Act
self.assertEqual(discount, 10.0) # Assert
def test_calculate_discount_default_tier(self):
mock_api_client = Mock()
mock_api_client.get_customer_tier.return_value = "Bronze" # Arrange, simulating a default tier.
calculator = DiscountCalculator(mock_api_client)
discount = calculator.calculate_discount(789, 50) # Act
self.assertEqual(discount, 0.0) # Assert
"""
"""python
#pytest example (more modern) - demonstrates the concept of parameterization in tests.
# filename: test_discount_calculator.py
import pytest
from unittest.mock import Mock
from discount_calculator import DiscountCalculator
@pytest.mark.parametrize(
"customer_tier, order_total, expected_discount",
[
("Gold", 100, 10.0),
("Silver", 200, 10.0),
("Bronze", 50, 0.0),
("Platinum", 300, 30.0), # Added Platinum tier for extensibility demonstration.
],
)
def test_calculate_discount(customer_tier, order_total, expected_discount):
mock_api_client = Mock()
mock_api_client.get_customer_tier.return_value = customer_tier # Arrange
calculator = DiscountCalculator(mock_api_client)
discount = calculator.calculate_discount(123, order_total) # Act
assert discount == expected_discount # Assert
"""
### 1.3. Anti-Patterns
* **Testing Implementation Details:** Writing tests that directly verify the internal workings of a class or function, instead of its public API or expected behavior.
* **Example of a bad test (Anti-pattern):** Testing the *specific name* of a private variable after a calculation inside class A (test breaks when refactoring variable name).
* **Ignoring Edge Cases:** Not testing boundary conditions (e.g., zero, negative values, maximum values) and edge cases that can lead to errors or unexpected behavior. Missing null/None checks.
* **Using Real Dependencies:** Not properly mocking or stubbing external dependencies (databases, APIs, file systems) in unit tests, leading to slow, unreliable, and non-deterministic tests.
### 1.4. Technology-Specific Details
* **Python:** Use "unittest.mock" or "pytest-mock" for mocking dependencies. Utilize "pytest"'s parameterization feature for writing data-driven tests. Prioritize writing pure functions whenever possible to simplify unit testing. Use type hints extensively for better code clarity and testability.
### 1.5. Considerations for Legacy Systems
When introducing TDD into a legacy system, it is often not feasible to immediately start with writing tests before code.
* **Sprout Method** Identify small, isolated parts of the legacy system that can be refactored using TDD. This involves creating new code alongside the existing system, with the new code being developed using TDD principles.
* **Characterization Tests** Write tests that capture the existing behavior of the legacy code. These tests serve as a safety net during refactoring, ensuring that the functionality remains the same. These are *not* unit tests in the strictest sense, but rather acceptance tests for sections of the old code.
## 2. Integration Testing in TDD
Integration testing verifies the interaction between two or more units of code. In TDD, this usually happens after sufficient unit tests are in place.
### 2.1. Standards
* **Do This:** Write integration tests to verify that different parts of the system work together correctly.
* **Why:** Ensures that units that pass their individual tests function as expected when combined.
* **Do This:** Focus on testing the interactions between modules or services, not the internal implementation of each unit.
* **Why:** Prevents tight coupling between tests and implementation details. Maintains test resilience to changes within individual units.
* **Do This:** Use realistic test data and scenarios that simulate real-world usage.
* **Why:** Provides higher confidence in the system's behavior under realistic conditions.
* **Don't Do This:** Mock or stub *everything*. Allow some real interactions to occur to verify integration.
* **Why:** Over-mocking defeats the purpose of integration testing, which is to verify the interactions between real components.
* **Don't Do This:** Write integration tests that are too broad or cover too many interactions at once.
* **Why:** Makes it difficult to pinpoint the source of failures. Tests should be focused on specific integration points.
### 2.2. Code Examples (Python with "pytest" and Docker Compose)
Assume there are two services: a "UserService" and a "ProfileService".
"""python
# filename: user_service.py
import requests
class UserService:
def __init__(self, profile_service_url):
self.profile_service_url = profile_service_url
def get_user_profile(self, user_id):
response = requests.get(f"{self.profile_service_url}/profiles/{user_id}")
response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
return response.json()
# filename: test_user_service_integration.py
import pytest
import requests
from user_service import UserService
import docker
import time
PROFILE_SERVICE_PORT = 8001 # Port the profile service will use, can be hardcoded for integration tests
@pytest.fixture(scope="session")
def docker_compose_file(pytestconfig):
return "docker-compose.yml" # Path to docker-compose.yml file in the project root
@pytest.fixture(scope="session", autouse=True)
def start_services(docker_compose_file, docker_services):
"""Starts all the services defined in docker-compose.yml."""
docker_services.start("profile-service") # service name as defined in docker-compose.yml
time.sleep(5) # Give the service time to start. A more sophisticated method could be used.
yield # This allows test collection to happen before services are stopped.
# Cleanup (optional): Remove unused services. However, it's usually desirable to investigate the state after failing tests.
#docker_services.down(remove_images=True) # stops and removes
def is_responsive(url):
"""Check if something responds at the given url."""
try:
response = requests.get(url)
return response.status_code == 200
except requests.ConnectionError:
return False
@pytest.fixture(scope="session")
def profile_service_url(docker_ip, docker_services):
"""Ensure that profile service is up and responsive."""
url = f"http://{docker_ip}:{docker_services.port_for('profile-service', PROFILE_SERVICE_PORT)}"
docker_services.wait_until_responsive(
timeout=30.0, pause=0.1, check=lambda: is_responsive(url)
)
return url
def test_get_user_profile_integration(profile_service_url):
user_service = UserService(profile_service_url)
user_id = 1
try:
profile = user_service.get_user_profile(user_id)
assert profile["user_id"] == user_id
except requests.exceptions.RequestException as e:
pytest.fail(f"Integration test failed: Could not connect to profile service {e}")
"""
"""yaml
# docker-compose.yml (Example)
version: "3.8"
services:
profile-service:
image: profile-service-image:latest # Replace with your profile service image
ports:
- "8001:8000"
environment:
- PORT=8000
#build: #Optional: if you want to build the image every time.
# context: ./profile_service
# dockerfile: Dockerfile
"""
### 2.3. Anti-Patterns
* **Over-Reliance on Mocks:** Mocking too many components makes the test resemble a unit test more than an integration test.
* **Broad Integration Tests:** Creating integration tests that cover too many components or scenarios, making it difficult to diagnose failures
* **Ignoring Network Latency/Failures:** Not accounting for or simulating network issues that might happen in a distributed system.
### 2.4. Technology-Specific Details
* **Docker Compose for Test Environments:** Using Docker Compose to define and manage the dependencies of the application (databases, message queues, other services) during integration tests. This promotes consistent and reproducible test environments.
* **Requests Library in Python** Use try-expect blocks to handle errors and timeouts for external requests.
## 3. End-to-End (E2E) Testing in TDD
E2E testing validates the entire application flow, from the user interface down to the database, simulating real user interactions. In TDD, E2E tests are created to ensure that all the components of an application work together as expected.
### 3.1. Standards
* **Do This:** Write E2E to verify that the application functions correctly from the user's perspective.
* **Why:** Ensures that all layers of the application work seamlessly to deliver the expected user experience.
* **Do This:** Automate E2E tests to ensure they can be run frequently and consistently.
* **Why:** Frequent E2E testing helps catch regressions early and minimizes the risk of releasing broken functionality.
* **Do This:** Use a testing framework that allows you to interact with the application's UI and assert on the expected results.
* **Why:** Automates the process of simulating user interactions and verifying the application's behavior.
* **Don't Do This:** Rely solely on E2E tests. They are slow and expensive to maintain. Use unit and integration tests to cover the majority of the logic.
* **Why:** A balanced testing strategy is essential. E2E tests should focus on verifying the overall flow, while unit and integration tests cover the details.
* **Don't Do This:** Make E2E tests overly brittle by tightly coupling them to specific UI elements or implementation details.
* **Why:** Minor UI changes can break brittle tests, leading to maintenance headaches.
### 3.2. Code Examples (Python with "Playwright")
"""python
# filename: test_e2e.py
import pytest
from playwright.sync_api import sync_playwright
@pytest.fixture(scope="session")
def browser():
with sync_playwright() as p:
browser = p.chromium.launch() # Or firefox, webkit
yield browser
browser.close()
@pytest.fixture
def page(browser):
page = browser.new_page()
yield page
page.close()
def test_login_flow(page):
# Arrange
page.goto("http://localhost:3000/login") # Replace with your app URL
# Act
page.fill("input[name='username']", "testuser") # Use CSS selectors
page.fill("input[name='password']", "password123")
page.click("button[type='submit']")
# Assert
page.wait_for_selector(".dashboard") # wait for the presence of dashboard element.
assert page.url == "http://localhost:3000/dashboard"
assert page.inner_text(".dashboard h1") == "Welcome to your Dashboard"
"""
### 3.3. Anti-Patterns
* **Unreliable Test Environments:** Running E2E tests in unstable environments that lead to flaky results.
* **Lack of Test Data Management:** Not having a strategy for managing test data, which results in inconsistent test results.
* **Neglecting Accessibility:** Forgetting to include accessibility checks in E2E tests to ensure that the application is usable by people with disabilities.
### 3.4. Technology-Specific Details
* **Playwright for Cross-Browser Testing:** Use Playwright or similar tools to test the application in multiple browsers. Allows you to easily assert on the state of the DOM, network requests, and other browser features.
* **CI/CD Integration:** Integrate E2E tests into the CI/CD pipeline to automatically run them on every code change.
## 4. General Testing Principles for TDD
### 4.1. Testability
* **Do This:** Design code with testability in mind from the outset.
* **Why:** Significantly simplifies the testing process and increases code quality. Encourages loose coupling, dependency injection, and clear separation of concerns.
* **Do This:** Strive for pure functions, which are easier to test because they have no side effects and always return the same output for a given input.
* **Why:** Makes unit testing significantly easier.
* **Don't Do This:** Use global state or singletons excessively.
* **Why:** They make it difficult to isolate units of code and lead to unpredictable test results.
### 4.2. Test Naming Conventions
* **Do This:** Adopt a consistent and descriptive naming convention for tests. A common pattern is "test_methodName_scenario_expectedResult".
* **Why:** Enhances the readability and maintainability of the test suite and makes it easier to understand the purpose of each test.
### 4.3. Test Data Management
* **Do This:** Use test data that is relevant to the scenarios being tested.
* **Why:** Ensures that tests are realistic and provide meaningful results. Create test data using factories or fixtures.
### 4.4. Test Organization
* **Do This:** Organize tests in a way that mirrors the structure of the production code.
* **Why:** Makes it easier to locate and maintain tests.
* **Do This:** Keep tests close to respective source code. This might mean having your tests in the same directory, or a parallel test directory. Keeps the tests maintainable, and local.
* **Why:** Enforces locality and discourages the creation of long-range dependencies.
### 4.5. Continuous Improvement of Tests
* **Do This:** Regularly review and refactor tests to keep them up-to-date and maintainable.
* **Why:** Essential for maintaining a healthy test suite that provides valuable feedback and prevents regressions. Apply the same coding standards to tests as to production code.
## 5. Performance Testing in TDD
While not always explicitly part of the red-green-refactor cycle, performance considerations *should* influence design decisions during TDD.
### 5.1. Standards
* **Do This:** Identify performance-critical sections of code early in the TDD process.
* **Why:** Allows for performance considerations to influence design choices from the beginning.
* **Do This:** Write performance tests to measure the execution time and resource consumption of critical code paths.
* **Why:** Helps identify performance bottlenecks and ensures that the application meets performance requirements.
* **Do This:** Use profiling tools to identify areas of code that can be optimized.
* **Why:** Provides insights into the performance characteristics of the code and helps pinpoint areas where optimization efforts should be focused.
* **Don't Do This:** Neglect performance testing until late in the development cycle.
* **Why:** Can lead to costly and time-consuming rework if performance issues are discovered late.
### 5.2. Code Examples (Python with "pytest-benchmark")
"""python
# filename: prime_number.py
def is_prime(n):
"""Determine if a number is prime."""
if n <= 1:
return False
for i in range(2, int(n**0.5) + 1):
if n % i == 0:
return False
return True
# filename: test_prime_number.py
import pytest
from prime_number import is_prime
def test_is_prime_basic():
assert is_prime(2) == True
assert is_prime(4) == False
assert is_prime(11) == True
def test_is_prime_performance(benchmark):
number_to_test = 997 # A known prime number close to 1000
result = benchmark(is_prime, number_to_test) #benchmark(function, *args, **kwargs)
assert result == True
"""
### 5.3. Technology Specific Aspects
* Using "pytest-benchmark" shows how to add simple timing tests, which is often good enough during the development cycle. This allows measuring the speed of crucial code regions.
## 6. Security Considerations in Testing Methodologies
### 6.1. Input Validation Testing
* **Do This:** Always validate inputs and test for a wide range of potentially malicious inputs.
* **Why:** Prevents various injection attacks (e.g., SQL injection, command injection, XSS).
* Test specifically for null values, empty strings, incorrect datatypes and excessively long strings.
* **Do This:** Fuzz inputs using tools designed for security testing.
### 6.2. Authentication and Authorization Testing
* **Do This:** Test authentication mechanisms thoroughly by attempting to bypass authentication using common attack vectors.
* **Why:** Ensures that only authorized users can access sensitive data and functionality.
* **Do This:** Verify authorization logic by testing different roles and permissions and attempting to perform actions that should be unauthorized.
### 6.3. Data Protection Testing
* **Do This:** Test the security of sensitive data by attempting to access or modify data without proper authorization.
* **Why:** Ensures that sensitive data is protected from unauthorized access.
### 6.4. Dependency Vulnerability Scanning
* **Do This:** Use automated tools to scan dependencies for known vulnerabilities and address them promptly.
* **Why:** Prevents the introduction of known security flaws into the application.
### 6.5. Technology Specific Aspects
* There are many security testing frameworks and libraries that help you automate security tests. Examples include OWASP ZAP, and more.
## Conclusion
Following these coding standards for Testing Methodologies in TDD will lead to more robust, maintainable, and secure code. Remember to adapt these guidelines to specific project requirements and technology stacks. Regularly review and update these standards to reflect the latest best practices and advancements in TDD.
danielsogl
Created Mar 6, 2025
# API Integration Standards for TDD
This document outlines the coding standards and best practices for API integration within a Test-Driven Development (TDD) workflow. It provides specific guidance on how to design, implement, and test API interactions to ensure maintainability, performance, and security.
## 1. Introduction
Integrating with external APIs and backend services is a common requirement in modern software development. Applying TDD principles to API integration requires a strategic approach different from traditional unit testing. By focusing on contract testing, isolating external dependencies, and using mocks/stubs effectively, you can build robust and reliable integrations. This document details how to apply TDD effectively in this context.
## 2. Architectural Considerations
### 2.1. Decoupling API Interactions
**Standard:** Decouple your application code from the actual API implementation. Use abstraction layers (e.g., repositories, services) to interact with APIs.
**Why:**
* **Maintainability:** Allows for easier changes to API implementations without affecting core application logic.
* **Testability:** Enables mocking and stubbing API interactions during testing, isolating the code under test.
**Do This:** Define interfaces or abstract classes for API clients.
**Don't Do This:** Directly use API client libraries within application logic.
**Example:**
"""python
# Good: Using an interface
from abc import ABC, abstractmethod
class UserRepository(ABC):
@abstractmethod
def get_user(self, user_id: int):
pass
class UserApiClient:
def get_user(self, user_id: int):
# Actual API call (e.g., using requests or aiohttp)
pass
class UserService:
def __init__(self, user_repository: UserRepository):
self.user_repository = user_repository
def get_user(self, user_id: int):
return self.user_repository.get_user(user_id)
# In tests, we can mock the UserRepository
"""
### 2.2. Contract-Based Testing
**Standard:** Emphasize contract testing to verify that the API integration meets the expected behavior.
**Why:**
* **Reliability:** Ensures that the integration behaves as expected across different environments.
* **Early Detection:** Catches integration issues early in the development cycle.
**Do This:** Define clear contracts (schemas, data structures) for API requests and responses. Use consumer-driven contract testing.
**Don't Do This:** Rely solely on end-to-end tests, which can be slow and brittle.
**Example:**
Using Pact for consumer-driven contract testing:
*Consumer side (defines what it expects from the provider):*
"""ruby
#consumer/service_consumers/user_service_consumer.rb
require 'pact/consumer_contract'
Pact.service_consumer 'MyConsumer' do
has_pact_with 'MyProvider' do
mock_service :my_provider do
given('a user with ID 1 exists')
.upon_receiving('a request to get user 1')
.with(method: :get, path: '/users/1')
.will_respond_with(
status: 200,
headers: {'Content-Type' => 'application/json'},
body: {id: 1, name: 'John Doe'}
)
end
end
end
"""
*Provider side (verifies it meets the consumer's expectations):*
"""ruby
#provider/pact_helper.rb
require 'pact/provider/rspec'
Pact.service_provider 'MyProvider' do
honours_pact_with 'MyConsumer' do
pact_uri './pacts/my_consumer-my_provider.json' #Generated by the consumer test
end
end
describe 'MyProvider', pact: true do
include Rack::Test::Methods #For simple provider implementations
def app
#Your actual provider application
end
it 'returns user data for ID 1'do
get '/users/1'
expect(last_response.status).to eq 200
expect(JSON.parse(last_response.body)['id']).to eq(1)
expect(JSON.parse(last_response.body)['name']).to eq('John Doe')
end
end
"""
### 2.3. Idempotency Considerations
**Standard:** Design API interaction code to be idempotent where applicable, especially for write operations.
**Why:**
* **Resilience:** Handles network errors and retries gracefully, preventing unintended side effects from duplicate requests.
* **Reliability:** Ensures that the desired outcome is achieved even if requests are retried.
**Do This:** Use unique identifiers or transaction IDs in requests to ensure idempotency. Implement logic to check if an operation has already been performed before taking action.
**Don't Do This:** Assume that API requests will always succeed on the first try, or that retries won't cause unintended side effects.
**Example (Python):**
"""python
import uuid
import requests
def create_resource(api_url, resource_data, idempotency_key=None):
if idempotency_key is None:
idempotency_key = str(uuid.uuid4())
headers = {'Idempotency-Key': idempotency_key}
response = requests.post(api_url, json=resource_data, headers=headers)
if response.status_code == 201:
return response.json()
elif response.status_code == 409: # Conflict - Resource already exists
# Handle the case where the resource was already created with the same idempotency key
print("Resource already created with this idempotency key")
return None
else:
response.raise_for_status() # Raise HTTPError for bad responses
# Example Usage:
resource_data = {'name': 'Example Resource'}
new_resource = create_resource('https://example.com/api/resources', resource_data)
if new_resource:
print(f"Resource created: {new_resource}")
else:
print("Resource creation failed.")
"""
## 3. Implementation Details
### 3.1. Mocking API Responses
**Standard:** Use mocking frameworks to simulate API responses during testing.
**Why:**
* **Speed:** Avoids slow API calls during testing, accelerating the test suite.
* **Isolation:** Isolates the code under test from external dependencies, ensuring focused and reliable tests.
* **Control:** Allows you to simulate various API scenarios, including error conditions.
**Do This:** Use libraries like "unittest.mock" (Python), Mockito (Java), or Jest mocks (JavaScript) to create mock API responses.
**Don't Do This:** Use real API endpoints for unit tests, especially in CI/CD environments.
**Example (Python with "unittest.mock"):**
"""python
import unittest
from unittest.mock import patch
import requests
import app # Assuming your application code is in app.py
class TestUserService(unittest.TestCase):
@patch('app.UserApiClient.get_user') # Mock the API client method
def test_get_user_success(self, mock_get_user):
# Configure the mock to return a specific value
mock_get_user.return_value = {'id': 1, 'name': 'Test User'}
user_service = app.UserService(app.UserApiClient()) # Assuming UserService takes an API client instance
user = user_service.get_user(1)
# Assert that the mock was called with correct arguments
mock_get_user.assert_called_once_with(1)
# Assert that the service returns the expected data
self.assertEqual(user, {'id': 1, 'name': 'Test User'})
@patch('app.UserApiClient.get_user')
def test_get_user_failure(self, mock_get_user):
mock_get_user.side_effect = requests.exceptions.RequestException("API Error")
user_service = app.UserService(app.UserApiClient())
with self.assertRaises(requests.exceptions.RequestException):
user_service.get_user(1)
"""
### 3.2. Stubbing API Responses
**Standard:** Utilize stubbing to provide predefined API responses based on specific input parameters.
**Why:**
* **Reproducibility:** Ensures consistent test results by providing controlled and predictable API responses.
* **Scenario Testing:** Allows you to simulate various API scenarios, including edge cases and error conditions.
**Do This:** Use tools like WireMock, Mockoon or service virtualization platforms for stubbing.
**Don't Do This:** Hardcode stubbed data directly in your tests.
**Example (WireMock):**
1. **Define a Stub:**
Create a JSON file (e.g., "mapping_user_1.json") in your WireMock's "mappings" directory:
"""json
{
"request": {
"method": "GET",
"url": "/users/1"
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": "{ \"id\": 1, \"name\": \"John Doe\" }"
}
}
"""
2. **Run WireMock Server:**
Start the WireMock server (e.g., using Docker, standalone JAR, etc.). Ensure your application points to WireMock's address (e.g., "http://localhost:8080") during test execution.
3. **Test Code:**
"""python
import unittest
import requests
class TestUserService(unittest.TestCase):
def test_get_user_success(self):
# Assuming your application is configured to point to WireMock
response = requests.get("http://localhost:8080/users/1")
self.assertEqual(response.status_code, 200)
user_data = response.json()
self.assertEqual(user_data['id'], 1)
self.assertEqual(user_data['name'], 'John Doe')
"""
### 3.3. Handling API Errors
**Standard:** Implement comprehensive error handling for API interactions.
**Why:**
* **Resilience:** Ensures that your application can gracefully handle API errors, such as network issues, server errors, and invalid responses.
* **User Experience:** Provides informative error messages and avoids unexpected crashes.
**Do This:** Use "try...except" blocks (Python), "try...catch" blocks (Java/JavaScript) to handle exceptions raised during API calls.
**Don't Do This:** Ignore API errors or handle them generically without providing meaningful error messages.
**Example (Python):**
"""python
import requests
def get_data_from_api(url):
try:
response = requests.get(url)
danielsogl
Created Mar 6, 2025