# Component Design Standards for Mocha
This document outlines component design standards for Mocha, focusing on creating reusable, maintainable, and testable test components. These standards promote consistency, readability, and long-term maintainability of Mocha test suites.
## 1. Introduction
Effective component design in Mocha involves structuring your tests into modular, self-contained units that can be easily understood, modified, and reused. This is particularly important for large projects where the test suite can become complex and difficult to manage. This document provides guidance on how to architect your Mocha tests and implement reusable test components.
## 2. Core Principles of Test Component Design
### 2.1. Single Responsibility Principle (SRP)
* **Do This:** Each test component should have a single, well-defined purpose. For example, one component may test a specific function, API endpoint, or UI element.
* **Don't Do This:** Avoid creating monolithic test components that cover multiple unrelated functionalities.
* **Why:** Adhering to SRP makes components easier to understand, modify, and reuse. Changes in one part of the system are less likely to affect unrelated tests. It also promotes better organization within your test suite.
### 2.2. Abstraction and Encapsulation
* **Do This:** Encapsulate the internal workings of your test components. Expose only the necessary interface for interacting with the component. Use helper functions or classes to hide complex logic.
* **Don't Do This:** Directly expose internal variables or implementation details of your test components.
* **Why:** Abstraction reduces coupling between tests and the system under test. Changes to the system under test are less likely to break tests that rely on abstract interfaces. Encapsulation makes the tests more resilient and maintainable.
### 2.3. Reusability
* **Do This:** Design components that can be reused across multiple tests or test suites. Create parameterized tests using Mocha's built-in features or external libraries to avoid code duplication.
* **Don't Do This:** Copy and paste code between tests. This leads to redundancy and makes it harder to maintain the test suite.
* **Why:** Reusable components reduce code duplication, improve consistency, and make it easier to maintain the test suite. If a bug is fixed in one component, all tests that use that component are automatically fixed.
### 2.4. Separation of Concerns (SoC)
* **Do This:** Separate test setup, execution, and assertion logic into distinct functions or components. Use "before", "beforeEach", "after", and "afterEach" hooks to manage setup and teardown.
* **Don't Do This:** Mix setup, execution, and assertion logic within the same code block.
* **Why:** Separating concerns makes tests easier to read, understand, and maintain. It also makes it easier to reuse setup and teardown logic across multiple tests.
## 3. Implementing Test Components in Mocha
### 3.1. Helper Functions
Helper functions are a powerful way to abstract away complex logic and make your tests more readable.
* **Do This:** Create functions that perform common tasks, such as creating test data, interacting with the system under test, or asserting expected results.
* **Example:**
"""javascript
// helper.js
const assert = require('assert');
function createUser(name, email) {
// Simulate creating a user in your system
return { name, email };
}
function verifyUserExists(user) {
//Simulate checking if a user exists in the database
return true;
}
module.exports = { createUser, verifyUserExists };
// test.js
const { createUser, verifyUserExists } = require('./helper');
const assert = require('assert');
describe('User Creation', () => {
it('should create a user with the correct properties', () => {
const user = createUser('John Doe', 'john.doe@example.com');
assert.strictEqual(user.name, 'John Doe');
assert.strictEqual(user.email, 'john.doe@example.com');
});
it('should verify that a user exists after creation', () => {
const user = createUser('Jane Doe', 'jane.doe@example.com');
assert.strictEqual(verifyUserExists(user), true);
});
});
"""
* **Why:** Helper functions make tests more concise and easier to read. They also promote code reuse and reduce the risk of errors.
### 3.2. Custom Assertions
Custom assertions allow you to define your own domain-specific assertions, making your tests more expressive and easier to understand.
* **Do This:** Create custom assertion functions that encapsulate complex assertion logic.
* **Example:**
"""javascript
const assert = require('assert');
// Custom assertion
assert.userHasProperty = (user, property, expectedValue, message) => {
assert.ok(user.hasOwnProperty(property), message || "User should have property ${property}");
assert.strictEqual(user[property], expectedValue, message || "User ${property} should be ${expectedValue}");
};
describe('User Object', () => {
it('should have the correct name', () => {
const user = { name: 'Alice', email: 'alice@example.com' };
assert.userHasProperty(user, 'name', 'Alice', 'Name should be Alice');
});
it('should have the correct email', () => {
const user = { name: 'Alice', email: 'alice@example.com' };
assert.userHasProperty(user, 'email', 'alice@example.com', 'Name should be alice@example.com');
});
});
"""
* **Why:** Custom assertions make tests more readable and easier to understand. They also encapsulate complex assertion logic and provide a more domain-specific way to verify expected outcomes.
### 3.3. Test Fixtures
Test fixtures provide a consistent and predictable state for your tests to run against.
* **Do This:** Create test fixtures using "before", "beforeEach", "after", and "afterEach" hooks. Use separate files to store complex fixture data.
* **Example:**
"""javascript
// fixtures.js
const userData = {
validUser: {
name: 'John Doe',
email: 'john.doe@example.com',
password: 'password123'
},
invalidUser: {
name: 'Jane Doe',
email: 'jane',
password: ''
}
};
module.exports = { userData };
// test.js
const { userData } = require('./fixtures');
const assert = require('assert');
describe('User Authentication', () => {
let validUser;
beforeEach(() => {
validUser = userData.validUser; // create a new copy for each test
});
it('should authenticate a valid user', () => {
//Simulate the authentication process
assert.strictEqual(validUser.password, 'password123');
});
});
"""
* **Why:** Test fixtures ensure that your tests run against a known and consistent state. This makes it easier to reproduce bugs and verify that your tests are reliable.
### 3.4. Parameterized Tests
Parameterized tests allow you to run the same test with different sets of input data.
* **Do This:** Use libraries like "mocha-param" or "lodash.forEach" to create parameterized tests. Ensure that the parameters are clearly defined, with meaningful names.
* **Example:**
"""javascript
const assert = require('assert');
const _ = require('lodash'); // Requires lodash
describe('String Length', () => {
const testCases = [
{ input: 'hello', expected: 5 },
{ input: 'world', expected: 5 },
{ input: '', expected: 0 },
{ input: 'a', expected: 1 }
];
_.forEach(testCases, (testCase) => {
it("should return ${testCase.expected} for input "${testCase.input}"", () => {
assert.strictEqual(testCase.input.length, testCase.expected);
});
});
});
"""
* **Why:** Parameterized tests reduce code duplication and make it easier to test your code with different input values. This can help you find edge cases and improve the reliability of your code.
### 3.5. Asynchronous Testing
Mocha supports asynchronous testing using promises, async/await, and callbacks.
* **Do This:** Use "async/await" for cleaner and more readable asynchronous tests. Always handle rejections in asynchronous tests. Explicitly return promises from "it" blocks.
* **Don't Do This:** Rely on implicit resolution of promises or callbacks without proper error handling.
* **Example:**
"""javascript
const assert = require('assert');
async function fetchData() {
// Simulate an asynchronous operation
return new Promise(resolve => {
setTimeout(() => {
resolve({ data: 'Async Data' });
}, 50);
});
}
describe('Asynchronous Data Fetching', () => {
it('should fetch data asynchronously', async () => {
const result = await fetchData();
assert.strictEqual(result.data, 'Async Data');
});
});
"""
* **Why:** Asynchronous testing is essential for testing code that performs asynchronous operations, such as network requests or database queries. "async/await" makes asynchronous tests more readable and easier to understand. Proper error handling prevents unhandled rejections from crashing your tests.
### 3.6. Using "this.timeout()"
For asynchronous tests that may take a long time, increase the timeout using "this.timeout()".
* **Do This:** Set a reasonable timeout value for asynchronous tests that might exceed Mocha's default timeout (2000ms).
* **Example:**
"""javascript
describe('Long Running Task', () => {
it('should complete a long running task within the specified timeout', async function() {
this.timeout(5000); // Set timeout to 5 seconds
await new Promise(resolve => setTimeout(resolve, 4000)); // Simulate long running task
assert.ok(true, 'Task completed successfully');
});
});
"""
* **Why:** Increasing the timeout prevents tests from failing prematurely due to slow execution times. Carefully adjust the timeout value to avoid masking genuine performance issues.
### 3.7. Modular Test Suites
Organize tests into modular suites, ideally mirroring the modular structure of the application under test.
* **Do This:** Create separate test files or suites for different modules, components, or features.
* **Example:**
"""
/test
├── auth
│ ├── login.test.js
│ └── register.test.js
├── products
│ ├── create.test.js
│ ├── update.test.js
│ └── delete.test.js
└── utils
└── helper.js
"""
* **Why:** Modular test suites make it easier to find, run, and maintain tests. Changes to one part of the application are less likely to affect unrelated tests. This promotes better organization, scalability, and maintainability of the entire test suite.
## 4. Advanced Techniques
### 4.1. Test Doubles (Stubs, Mocks, Spies)
Test doubles are replacements for dependencies that allow you to isolate the code under test.
* **Do This:** Use a mocking library like "sinon" or "testdouble" to create stubs, mocks, and spies. Use stubs to control the behavior of dependencies. Use mocks to verify that interactions with dependencies occur as expected. Use spies to track calls to dependencies without changing their behavior.
* **Example:**
"""javascript
const assert = require('assert');
const sinon = require('sinon');
function processPayment(paymentGateway, amount) {
return paymentGateway.process(amount);
}
describe('Payment Processing', () => {
it('should process payment successfully', async () => {
const paymentGatewayStub = {
process: sinon.stub().resolves({ success: true })
};
const result = await processPayment(paymentGatewayStub, 100);
assert.deepStrictEqual(result, { success: true });
assert.ok(paymentGatewayStub.process.calledOnceWith(100));
});
it('should handle payment failure', async () => {
const paymentGatewayStub = {
process: sinon.stub().rejects(new Error('Payment Failed'))
};
try {
await processPayment(paymentGatewayStub, 100);
assert.fail('Expected an error to be thrown');
} catch (error) {
assert.strictEqual(error.message, 'Payment Failed');
assert.ok(paymentGatewayStub.process.calledOnceWith(100));
}
});
});
"""
* **Why:** Test doubles allow you to isolate the code under test and verify that it interacts with its dependencies correctly. This is particularly useful for testing complex systems with many dependencies.
### 4.2. Dependency Injection
Dependency injection allows you to provide dependencies to your code from the outside, making it easier to test your code in isolation.
* **Do This:** Design your code to accept dependencies as arguments to functions or constructors. Avoid hardcoding dependencies within your code.
* **Example:**
"""javascript
class UserService {
constructor(userRepository) {
this.userRepository = userRepository;
}
async createUser(userData) {
return this.userRepository.create(userData);
}
}
describe('UserService', () => {
it('should create a user', async () => {
const userRepositoryMock = {
create: sinon.stub().resolves({ id: 1, ...userData })
};
const userService = new UserService(userRepositoryMock);
const userData = { name: 'John Doe', email: 'john.doe@example.com' };
const user = await userService.createUser(userData);
assert.deepStrictEqual(user, { id: 1, ...userData });
assert.ok(userRepositoryMock.create.calledOnceWith(userData));
});
});
"""
* **Why:** Dependency injection makes your code more modular, reusable, and testable. It allows you to easily replace dependencies with test doubles during testing.
### 4.3. Data-Driven Testing
Data-driven testing involves running the same test with different sets of input data and expected results.
* **Do This:** Define an array of test cases, each containing the input data and expected results. Iterate over the test cases and run the test for each case. Use descriptive names for each test case.
* **Example:**
"""javascript
const assert = require('assert');
describe('Calculator', () => {
const testCases = [
{ a: 1, b: 2, expected: 3, description: '1 + 2 should equal 3' },
{ a: -1, b: 1, expected: 0, description: '-1 + 1 should equal 0' },
{ a: 0, b: 0, expected: 0, description: '0 + 0 should equal 0' }
];
testCases.forEach(testCase => {
it(testCase.description, () => {
assert.strictEqual(testCase.a + testCase.b, testCase.expected);
});
});
});
"""
* **Why:** Data-driven testing reduces code duplication and makes it easier to test your code with different input values.
### 4.4. Using "describe.only" and "it.only"
To focus on specific tests during development, use "describe.only" and "it.only".
* **Do This:** Use "describe.only" to run only the tests within a specific suite. Use "it.only" to run only a specific test within a suite. Ensure to remove these directives before committing the code to the repository.
* **Example:**
"""javascript
describe('Feature A', () => {
it('should do something', () => {
// ...
});
describe.only('Sub-feature B', () => {
it.only('should do something specific', () => {
// ...
});
it('should do something else', () => {
// ...
});
});
});
"""
* **Why:** "describe.only" and "it.only" allow you to focus on specific tests during development, making it easier to debug and iterate on your code. However, it's crucial to remove these directives before committing your code to the repository to avoid accidentally skipping other tests..
## 5. Anti-Patterns
### 5.1. Global State Mutation
* **Avoid:** Modifying global state within tests without proper setup and teardown.
* **Why:** Global state mutation can lead to unpredictable test results and make it difficult to reproduce bugs.
### 5.2. Tight Coupling to Implementation Details
* **Avoid:** Writing tests that are tightly coupled to the implementation details of the system under test.
* **Why:** Tight coupling makes tests fragile and difficult to maintain. Changes to the implementation are likely to break tests, even if the functionality remains the same.
### 5.3. Over-Mocking
* **Avoid:** Mocking everything in your tests.
* **Why:** Over-mocking can make tests less effective at catching bugs and can also make them more difficult to maintain. Focus on mocking only the dependencies that are necessary to isolate the code under test.
### 5.4. Ignoring Errors
* **Avoid:** Catching errors without properly handling them or asserting that they occurred.
* **Why:** Ignoring errors can mask bugs and make it difficult to diagnose problems. Properly handle errors and assert that they occurred when expected.
## 6. Conclusion
By following these component design standards, you can create Mocha test suites that are reusable, maintainable, and easy to understand. This will improve the reliability of your code and make it easier to maintain your test suite over time. Remember to adapt these standards to your specific project requirements and coding style.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# Tooling and Ecosystem Standards for Mocha This document outlines the coding standards for leveraging the Mocha testing framework's tooling and ecosystem effectively. Adhering to these standards ensures maintainability, performance, and consistency in your test suites. This document is specifically tailored for Mocha, distinguishing itself from general JavaScript or testing best practices. ## 1. Assertion Libraries ### 1.1. Standard: Choose a Consistent Assertion Library **Do This:** Select one assertion library (e.g., Chai, expect.js, should.js) and use it consistently throughout your project. **Don't Do This:** Mix and match assertion libraries within the same project, as it reduces readability and increases cognitive load. **Why:** Consistency improves code understanding and reduces the learning curve for new developers. **Example (using Chai):** """javascript const chai = require('chai'); const expect = chai.expect; describe('Example Test', () => { it('should have a length of 5', () => { const arr = [1, 2, 3, 4, 5]; expect(arr).to.have.lengthOf(5); }); }); """ **Anti-Pattern:** """javascript const assert = require('assert'); const chai = require('chai'); const expect = chai.expect; describe('Inconsistent Assertions', () => { it('should be equal (assert)', () => { assert.equal(1, 1); }); it('should be equal (chai expect)', () => { expect(1).to.equal(1); }); }); """ ### 1.2. Standard: Prefer Expressive Assertion Styles **Do This:** Use assertion styles (e.g., "expect", "should") that offer a clear and readable syntax, especially with Chai. Often "expect" is considered most universally accepted. **Don't Do This:** Rely solely on basic "assert" built-in Node.js, as it lacks expressiveness and readability. **Why:** Expressive assertions enhance test readability and make debugging easier. **Example (Chai "expect" style):** """javascript const chai = require('chai'); const expect = chai.expect; describe('Chai Expect Style', () => { it('should be a string', () => { const str = 'hello'; expect(str).to.be.a('string'); }); it('should contain "hello"', () => { const str = 'hello world'; expect(str).to.include('hello'); }); }); """ **Anti-Pattern:** """javascript const assert = require('assert'); describe('Basic Assert Style', () => { it('should be true', () => { assert.ok(true); }); }); """ ### 1.3. Standard: Use Plugins for Specialized Assertions **Do This:** If your project involves specific data types or scenarios (e.g., dates, promises, JSON schema), consider using Chai plugins like "chai-datetime", "chai-as-promised", or "chai-json-schema". **Don't Do This:** Implement custom assertion logic for common scenarios when well-maintained plugins are available. **Why:** Plugins extend assertion libraries, streamlining your tests and improving readability. **Example (using "chai-as-promised"):** """javascript const chai = require('chai'); const chaiAsPromised = require('chai-as-promised'); const expect = chai.expect; chai.use(chaiAsPromised); describe('Promise Assertions', () => { it('should resolve with a value', async () => { const promise = Promise.resolve('success'); await expect(promise).to.eventually.equal('success'); }); }); """ ## 2. Test Runners and Reporters ### 2.1. Standard: Configure Mocha through "mocha.opts" or "package.json" **Do This:** Specify Mocha's configuration options, such as reporter, timeout, and recursive flag, in a "mocha.opts" file or within the "mocha" property in "package.json". **Don't Do This:** Pass configurations as command-line arguments directly, making it harder to reproduce and share test configurations. **Why:** Configuration files promote consistency and simplify test execution. **Example ("mocha.opts"):** """ --reporter spec --timeout 5000 --recursive """ **Example ("package.json"):** """json { "name": "my-project", "version": "1.0.0", "scripts": { "test": "mocha" }, "mocha": { "reporter": "spec", "timeout": 5000, "recursive": true } } """ ### 2.2. Standard: Use a Clear and Informative Reporter **Do This:** Choose a reporter that offers clear and concise output, such as "spec", "list", or "nyan". For CI/CD environments, consider "mocha-junit-reporter" or other JUnit-compatible reporters for integration with reporting tools. Consider "mochawesome" for generating stylish HTML reports. **Don't Do This:** Use reporters that provide verbose or hard-to-understand output, especially in CI/CD pipelines. **Why:** A good reporter makes it easier to identify failing tests and diagnose issues. **Example (installing and using "mochawesome"):** """bash npm install --save-dev mochawesome """ **Example ("package.json" - mocha script):** """json { "scripts": { "test": "mocha --reporter mochawesome" } } """ **Example (using "mocha-junit-reporter"):** """bash npm install --save-dev mocha-junit-reporter """ **Example ("package.json" - mocha script):** """json { "scripts": { "test": "mocha --reporter mocha-junit-reporter" }, "mocha-junit-reporter": { "stdout": true, "options": { "mochaFile": "./reports/output.xml" } } } """ ### 2.3. Standard: Leverage Custom Reporters for Specific Needs **Do This:** If standard reporters don't meet your requirements, create a custom reporter to tailor the output format. Mocha allows you to create custom reporters in JavaScript. **Don't Do This:** Modify existing reporters directly; create custom reporters to keep your codebase clean and avoid breaking changes during Mocha updates. **Why:** Custom reporters give you complete control over test results output. **Example (basic custom reporter in "reporter.js"):** """javascript const Mocha = require('mocha'); const { EVENT_RUN_BEGIN, EVENT_RUN_END, EVENT_TEST_PASS, EVENT_TEST_FAIL, EVENT_TEST_PENDING } = Mocha.Runner.constants; function MyCustomReporter(runner) { Mocha.reporters.Base.call(this, runner); runner.on(EVENT_RUN_BEGIN, () => { console.log('Test run started'); }); runner.on(EVENT_TEST_PASS, (test) => { console.log("Test passed: ${test.title}"); }); runner.on(EVENT_TEST_FAIL, (test, err) => { console.log("Test failed: ${test.title} with error: ${err.message}"); }); runner.on(EVENT_TEST_PENDING, (test) => { console.log("Test pending: ${test.title}"); }); runner.on(EVENT_RUN_END, () => { console.log('Test run finished'); }); } // Inherit from Mocha base reporter Mocha.utils.inherits(MyCustomReporter, Mocha.reporters.Base); module.exports = MyCustomReporter; """ **Example ("package.json" to use the custom reporter):** """json { "scripts": { "test": "mocha --reporter ./reporter.js" } } """ ## 3. Test Doubles and Mocking ### 3.1. Standard: Choose a Robust Mocking Library **Do This:** Select a mocking library like Sinon.js, Jest's built-in mocking, or testdouble.js to create stubs, spies, and mocks for isolating units under test. **Don't Do This:** Manually create mock objects or rely solely on simple object replacement, which can be error-prone and less flexible. **Why:** Mocking libraries provide features for verifying interactions, setting expectations, and managing complex mocking scenarios. **Example (using Sinon.js):** """javascript const sinon = require('sinon'); const assert = require('assert'); describe('Sinon Example', () => { it('should call the callback with the correct argument', () => { const callback = sinon.spy(); const obj = { method(arg, cb) { cb(arg * 2); } }; obj.method(5, callback); assert(callback.calledOnce); assert(callback.calledWith(10)); }); }); """ ### 3.2. Standard: Use Stubs for Isolating Dependencies **Do This:** Use stubs to replace dependencies with controlled substitutes, allowing you to test the unit in isolation. Stubs are particularly useful for simulating different dependency states (e.g., error conditions). **Don't Do This:** Directly test against real dependencies, which can lead to brittle tests and external dependency issues. **Why:** Stubs improve test reliability and reduce the impact of external factors. **Example (using Sinon.js stubs):** """javascript const sinon = require('sinon'); const assert = require('assert'); describe('Stub Example', () => { it('should handle error from service', async () => { const service = { getData: async () => { throw new Error('Service Unavailable'); } }; const stub = sinon.stub(service, 'getData').rejects(new Error('Service Unavailable')); try { await service.getData(); } catch (error) { assert.equal(error.message, 'Service Unavailable'); } finally { stub.restore(); // Restore the original method after the test } }); }); """ ### 3.3. Standard: Employ Spies for Verifying Interactions **Do This:** Use spies to monitor function calls and arguments without altering their behavior. Spies are useful for verifying that a function was called the expected number of times with the correct parameters. **Don't Do This:** Rely on manual checks or logging to verify interactions, as it is less precise and harder to maintain. **Why:** Spies provide a clean and automated way to verify interactions between units. **Example (using Sinon.js spies):** """javascript const sinon = require('sinon'); const assert = require('assert'); describe('Spy Example', () => { it('should call the log function', () => { const consoleLogSpy = sinon.spy(console, 'log'); const myFunc = (message) => { console.log(message); }; myFunc('Hello, world!'); assert(consoleLogSpy.calledOnce); assert(consoleLogSpy.calledWith('Hello, world!')); consoleLogSpy.restore(); // Restore the original method after the test }); }); """ ### 3.4. Standard: When to Mocks vs. Stubs/Spies **Do This:** Use Mocks for objects where you want to verify specific interactions and set expectations *before* running the code. Use Stubs to control the *output* of a function, and Spies to observe *how* a function is used. **Don't Do This:** Confuse mocks with stubs/spies. Mocks are stricter and control the whole object, whereas stubs/spies are targeted at specific methods. **Why:** Using the correct tool for the correct context simplifies the creation and readability of testing code. ## 4. Code Coverage Tools ### 4.1. Standard: Integrate Code Coverage Analysis **Do This:** Use a code coverage tool like Istanbul (nyc) or c8 to measure the percentage of code covered by your tests. Aim for a reasonable coverage target (e.g., 80-90%) but prioritize meaningful tests over achieving arbitrary coverage numbers. "c8" is especially recommended for modern ES module projects. **Don't Do This:** Ignore code coverage metrics, as it can lead to undetected gaps in your test suite. **Why:** Code coverage analysis helps identify areas of your code that lack sufficient testing. **Example (setting up "c8"):** """bash npm install --save-dev c8 """ **Example ("package.json" ):** """json { "scripts": { "test": "mocha", "coverage": "c8 mocha" } } """ ### 4.2. Standard: Configure Coverage Thresholds **Do This:** Set coverage thresholds (e.g., line, branch, function) in your coverage tool configuration to enforce a minimum level of testing. Fail the build if the thresholds are not met. **Don't Do This:** Allow code with low coverage to be merged without scrutiny. **Why:** Coverage thresholds help maintain a consistent level of testing across the codebase. **Example ("package.json" - adding coverage check thresholds to c8 ):** """json { "c8": { "check-coverage": true, "statements": 80, "branches": 80, "functions": 80, "lines": 80 } } """ ### 4.3. Standard: Exclude Irrelevant Code from Coverage **Do This:** Exclude code such as configuration files, generated code, or trivial getter/setter methods from coverage analysis to avoid inflating the coverage percentage artificially. Uses ".nycignore" or "c8" configuration. **Don't Do This:** Include all code in coverage analysis without considering its relevance. **Why:** Excluding irrelevant code provides a more accurate picture of the effectiveness of your tests. **Example (".nycignore" or "c8 ignore" in package.json):** """ config/* **/__mocks__/* **/__tests__/* """ ## 5. Linting and Formatting ### 5.1. Standard: Use ESLint with Mocha-Specific Rules **Do This:** Integrate ESLint with plugins like "eslint-plugin-mocha" to enforce coding standards within your test files. Configure rules to catch common mistakes, such as incorrect use of "this" context or missing assertions. **Don't Do This:** Ignore linting errors in your test files. **Why:** Linting improves code quality and consistency. **Example (installing "eslint-plugin-mocha"):** """bash npm install --save-dev eslint eslint-plugin-mocha """ **Example (".eslintrc.js"):** """javascript module.exports = { "plugins": ["mocha"], "extends": "eslint:recommended", "env": { "mocha": true, "node": true }, "rules": { "mocha/no-exclusive-tests": "error" // Disallow .only in tests } }; """ ### 5.2. Standard: Consistent Code Formatting **Do This:** Use a code formatter like Prettier to automatically format your test files according to a consistent style. **Don't Do This:** Rely on manual formatting, which can be time-consuming and inconsistent. **Why:** Consistent formatting improves code readability and reduces merge conflicts. **Example (integrating Prettier):** """bash npm install --save-dev prettier """ **Example (".prettierrc.js"):** """javascript module.exports = { semi: true, trailingComma: "all", singleQuote: true, printWidth: 120, tabWidth: 2 }; """ **Example ("package.json" - adding format script):** """json { "scripts": { "format": "prettier --write \"**/*.js\"" } } """ ### 5.3. Standard: Integrate Linting and Formatting with CI/CD **Do This:** Include linting and formatting checks in your CI/CD pipeline to automatically enforce coding standards. **Don't Do This:** Allow code that violates formatting rules and fails linting checks to be merged into the main branch. **Why:** Automated checks prevent code quality issues from reaching production. ## 6. Test Data Management ### 6.1. Standard: Use Fixtures for Consistent Test Data **Do This:** Use fixtures (pre-defined, static data) to provide consistent test data. Ensure the contents of the fixtures is representative of the data your application uses. **Don't Do This:** Create test data directly in your test cases, causing duplication and increasing the difficulty of maintaining the tests. **Why:** Fixtures ensure that the tests are executed with known data, giving predictable results. **Example (Basic Fixture):** """text // ./test/fixtures/users.json [ { "id": 1, "name": "Alice", "email": "alice@example.com" }, { "id": 2, "name": "Bob", "email": "bob@example.com" } ] """ **Example (Test Using Fixture):** """javascript const fs = require('fs'); const assert = require('assert'); describe('User Tests', () => { it('should load users from fixture', () => { const users = JSON.parse(fs.readFileSync('./test/fixtures/users.json', 'utf8')); assert.equal(users.length, 2); assert.equal(users[0].name, 'Alice'); }); }); """ ### 6.2. Standard: Generate Dynamic Test Data **Do This:** When fixed data is unsuitable, use libraries such as Faker.js to generate randomized but realistic-seeming test data. **Don't Do This:** Use hard-coded data, or predictable increments which might conflict and are difficult to maintain. **Why:** Dynamic test data provides effective isolation and prevents unintended couplings. **Example (Using Faker.js):** """bash npm install --save-dev @faker-js/faker """ **Example (Test with Faker.js):** """javascript const assert = require('assert'); const { faker } = require('@faker-js/faker'); describe('Dynamic Data Generation', () => { it('should generate a random email', () => { const randomEmail = faker.internet.email(); assert.ok(randomEmail.includes('@')); }); }); """ ## 7. CI/CD Integration ### 7.1. Standard: Automate Test Execution **Do This:** Integrate your Mocha tests into your CI/CD pipeline to be run on every commit, pull request, or scheduled build. Use tools such as GitHub Actions, CircleCI, Jenkins or GitLab CI. **Don't Do This:** Manually invoke tests only when deploying or as an occasional activity. **Why:** Automated testing identifies issues earlier, reduces risk, and contributes to more confident and faster deployments. **Example (GitHub Actions ".github/workflows/test.yml"):** """yaml name: Run Tests on: push: branches: [ main ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: 18 - name: Install dependencies run: npm install - name: Run tests run: npm test """ ### 7.2. Standard: Collect and Report Test Artifacts **Do This:** Store and provide access to test artifacts, such as reports from reporters, coverage statistics, and screenshots in case of failure, using the features of your CI/CD system. **Don't Do This:** Only review test results at runtime, and overlook persistent artifact generation which makes offline analysis and audit impossible. **Why:** Artifacts help in analyzing historical trends and support auditing and compliance needs. ## 8. Debugging ### 8.1. Standard: Use Debugging Tools Effectively **Do This:** Utilize node's built in debugging, or VS Code/WebStorm's debugging capabilities, integrating breakpoints into failing tests. **Don't Do This:** Rely solely on console.log statements, which can be less targeted and difficult to manage in complex test scenarios. **Why:** Robust debugging tools make pinpointing the root cause more effective. **Example (VS Code debugging configuration):** """json { "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Mocha Tests", "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha", "args": [ "--require", "test/setup.js", // Optional setup file "--reporter", "spec", "test/**/*.test.js" ], "console": "integratedTerminal", "internalConsoleOptions": "neverOpen" } ] } """ ### 8.2. Standard: Leverage "only" and "skip" Judiciously **Do This:** Temporarily use ".only" on a specific test or suite for focusing debugging attention. Likewise, ".skip" has its place when a particular test should be ignored until code stabilizes. *Carefully* remove these before committing changes. Enforce that CI configuration should error with ".only" tests. **Don't Do This:** Leave usages of ".only" and ".skip" in commits, as this can lead to incomplete test runs and mask failures. **Why:** Selective test execution dramatically speeds up troubleshooting time. **Example (using ".only" for focused debugging):** """javascript describe('My Suite', () => { it.only('should focus on this test', () => { // Test logic here }); it('should be skipped', () => { // This test will not run }); }); """ ## 9. Environment Variables ### 9.1. Standard: Manage Configuration Using Environment Variables **Do This:** Use environment variables to manage configuration specifics that may differ across environments (e.g., API keys, database URIs). Make use of libraries that facilitate loading from ".env" files during local development. **Don't Do This:** Hardcode environment-dependent parameters directly into your tests. **Why:** It is an industry security best-practice that keeps sensitive data separate from codebase. Enables simple switching between test environments. **Example (.env file):** """text API_KEY=your_api_key DATABASE_URL=your_database_url """ **Example (test with environment variables):** """javascript require('dotenv').config(); // Ensure .env file is loaded describe('Environment Variable Tests', () => { it('should use the API key from environment variables', () => { const apiKey = process.env.API_KEY; expect(apiKey).to.not.be.undefined; }); }); """ ## 10. Parallelization ### 10.1 Standard: Utilize Parallel Test Execution **Do This**: For larger test suites, leverage Mocha's parallel execution capabilities (available since v8) using the "--parallel" flag or configuration options. Consider using "mocha-parallel-tests" for older versions or to manage concurrency. **Don't Do This**: Avoid running tests serially if parallel execution can significantly reduce execution time without introducing race conditions. **Why**: Reduced test execution time improves developer productivity and CI/CD efficiency. **Example (enabling parallel execution via "package.json"):** """json { "scripts": { "test": "mocha --parallel test/**/*.test.js" } } """ **Example (Using "mocha-parallel-tests"):** """bash npm install --save-dev mocha-parallel-tests """ """json { "scripts": { "test": "mocha-parallel-tests test/**/*.test.js" } } """ ### 10.2 Standard: Manage Shared Resources Carefully in Parallel Tests **Do This**: If tests share resources like databases or external APIs, use unique identifiers, isolated databases, or mocks/stubs to prevent interference between parallel tests. **Don't Do This**: Assume parallel tests can concurrently modify shared resources without introducing conflicts or unpredictable behavior. **Why**: Prevents tests from unintentionally influencing each other, ensuring reliable test results. By adhering to these standards, you can ensure your Mocha test suites are maintainable, performant, and reliable, contributing to a high-quality software development process.
# Core Architecture Standards for Mocha This document outlines the core architectural standards for Mocha test suites, aiming to improve maintainability, readability, and overall quality of test code. These standards are designed to be used by developers and AI coding assistants alike. ## 1. Project Structure and Organization A well-organized project structure is crucial for navigating and maintaining Mocha test suites. This section focuses on how to structure your test files and directories for optimal clarity and scalability. ### 1.1. Standard: Directory-Based Grouping **Standard:** Organize test files in directories that mirror the structure of the source code being tested, or by feature area. **Do This:** """ /src /components /Button.js /utils /formatter.js /test /components /Button.test.js /utils /formatter.test.js """ **Don't Do This:** """ /test /all_tests.js // A single massive file /helper_functions.js // Random collection of helpers """ **Why:** This structure makes it easy to locate the tests associated with specific pieces of code. When someone changes "Button.js", they know exactly where to find the corresponding tests. **Example:** """javascript // /test/components/Button.test.js const assert = require('assert'); const Button = require('../../src/components/Button'); describe('Button Component', () => { it('should render correctly', () => { const button = new Button('Click Me'); assert.strictEqual(button.render(), '<button>Click Me</button>'); }); it('should handle click events', () => { let clicked = false; const button = new Button('Click Me', () => { clicked = true; }); button.click(); assert.strictEqual(clicked, true); }); }); """ ### 1.2. Standard: File Naming Conventions **Standard:** Use consistent naming conventions throughout the project. Test files should consistently reflect the name of what they're testing (e.g., "component.test.js" or "component.spec.js"). It's crucial to be consistent *within* a project. **Do This:** """ // For a file Button.js: Button.test.js // or Button.spec.js """ **Don't Do This:** """ btn_test.js // Inconsistent naming tests.js // Too generic """ **Why:** Consistent naming makes it trivially obvious which files contain tests for which code. **Example:** """javascript // /test/utils/formatter.test.js const assert = require('assert'); const formatter = require('../../src/utils/formatter'); describe('Formatter Utility', () => { it('should format currency correctly', () => { assert.strictEqual(formatter.formatCurrency(1000), '$1,000.00'); }); it('should format date correctly', () => { const date = new Date(2024, 0, 1); assert.strictEqual(formatter.formatDate(date), '01/01/2024'); }); }); """ ### 1.3. Standard: Segregation of Concerns (Test Suites) **Standard:** Keep test suites focused on a single component, module, or feature. Avoid mixing tests for different areas into single files. **Do This:** """ // button.test.js: only tests for the Button component // formatter.test.js: only tests for formatter utility """ **Don't Do This:** """ // utils.test.js: contains tests for all utility functions """ **Why:** Focused test suites are easier to understand, modify, and debug. They also help to isolate failures. ## 2. Architectural Patterns for Mocha Test Suites This section delves into specific architectural patterns that can be applied to Mocha test suites to enhance their structure and maintainability. ### 2.1. Standard: Page Object Model (POM) for UI Testing **Standard:** When testing user interfaces (e.g., with Puppeteer or Playwright), use the Page Object Model. **Do This:** """javascript // /test/page_objects/LoginPage.js class LoginPage { constructor(page) { this.page = page; this.usernameField = '#username'; this.passwordField = '#password'; this.loginButton = '#login-button'; } async navigate() { await this.page.goto('https://example.com/login'); } async login(username, password) { await this.page.fill(this.usernameField, username); await this.page.fill(this.passwordField, password); await this.page.click(this.loginButton); } } module.exports = LoginPage; // /test/login.test.js const LoginPage = require('./page_objects/LoginPage'); const { chromium } = require('playwright'); const assert = require('assert'); describe('Login Page', () => { let browser; let page; let loginPage; beforeEach(async () => { browser = await chromium.launch(); page = await browser.newPage(); loginPage = new LoginPage(page); await loginPage.navigate(); }); afterEach(async () => { await browser.close(); }); it('should login with valid credentials', async () => { await loginPage.login('validUser', 'validPassword'); await page.waitForSelector('#dashboard'); //example selector assert(await page.$('#dashboard'), 'Dashboard should be visible after login'); }); it('should display an error with invalid credentials', async () => { await loginPage.login('invalidUser', 'invalidPassword'); await page.waitForSelector('#error-message'); assert(await page.$('#error-message'), 'Error message should be visible after failed login'); }); }); """ **Don't Do This:** """javascript // Mixing page object interactions directly into test cases it('should login with valid credentials', async () => { await page.goto('https://example.com/login'); await page.fill('#username', 'validUser'); await page.fill('#password', 'validPassword'); await page.click('#login-button'); assert(await page.$('#dashboard'), 'Dashboard should be visible after login'); }); """ **Why:** The POM encapsulates UI interactions, making tests more readable and maintainable. Changes to the UI only require changes to the page object, not every test case. ### 2.2. Standard: Test Data Management **Standard:** Separate test data from test logic. Use fixtures, factories, or data providers to manage test data, especially complex or reusable data. **Do This:** """javascript // /test/fixtures/user.js module.exports = { validUser: { username: 'testuser', password: 'password123' }, invalidUser: { username: 'baduser', password: 'wrongpassword' } }; // /test/auth.test.js const assert = require('assert'); const authService = require('../../src/authService'); const userData = require('./fixtures/user'); describe('Authentication Service', () => { it('should authenticate a valid user', async () => { const user = await authService.authenticate(userData.validUser.username, userData.validUser.password); assert.strictEqual(user.username, userData.validUser.username); }); it('should reject an invalid user', async () => { try { await authService.authenticate(userData.invalidUser.username, userData.invalidUser.password); assert.fail('Should have thrown an error'); } catch (error) { assert.strictEqual(error.message, 'Invalid credentials'); } }); }); """ **Don't Do This:** """javascript // Embedding test data directly in test cases it('should authenticate a valid user', async () => { const user = await authService.authenticate('testuser', 'password123'); assert.strictEqual(user.username, 'testuser'); }); """ **Why:** Separating test data makes tests easier to read and modify. It also allows for reuse of data across multiple tests. Managing data effectively also allows using different datasets for different environments or test runs. ### 2.3. Standard: Helper Functions and Abstraction **Standard:** Extract common setup, teardown, and assertion logic into helper functions. Avoid duplication of code within and across test suites. **Do This:** """javascript // /test/helpers/db.js const mongoose = require('mongoose'); async function connectDB() { await mongoose.connect('mongodb://localhost:27017/testdb'); } async function clearDB() { await mongoose.connection.db.dropDatabase(); } async function disconnectDB() { await mongoose.disconnect(); } module.exports = { connectDB, clearDB, disconnectDB }; // /test/user.test.js const assert = require('assert'); const User = require('../../src/models/User'); const { connectDB, clearDB, disconnectDB } = require('./helpers/db'); describe('User Model', () => { beforeEach(async () => { await connectDB(); }); afterEach(async () => { await clearDB(); await disconnectDB(); }); it('should create a new user', async () => { const user = new User({ username: 'testuser', email: 'test@example.com' }); await user.save(); const savedUser = await User.findOne({ username: 'testuser' }); assert.strictEqual(savedUser.email, 'test@example.com'); }); }); """ **Don't Do This:** """javascript // Duplicating setup and teardown logic in every test suite describe('User Model', () => { beforeEach(async () => { await mongoose.connect('mongodb://localhost:27017/testdb'); // Duplicated code }); afterEach(async () => { await mongoose.connection.db.dropDatabase(); // Duplicated code await mongoose.disconnect(); // Duplicated code }); it('should create a new user', async () => { const user = new User({ username: 'testuser', email: 'test@example.com' }); await user.save(); const savedUser = await User.findOne({ username: 'testuser' }); assert.strictEqual(savedUser.email, 'test@example.com'); }); }); """ **Why:** Helper functions reduce code duplication, making tests easier to maintain and update. Centralized helper functions promote DRY (Don't Repeat Yourself), as well. ## 3. Test Suite Structure and Best Practices This section outlines the structural elements of a Mocha test suite and best practices for writing effective tests. ### 3.1. Standard: Arrange-Act-Assert (AAA) Pattern **Standard:** Structure each test case according to the Arrange-Act-Assert (AAA) pattern to improve readability and maintainability. **Do This:** """javascript it('should add two numbers correctly', () => { // Arrange const num1 = 5; const num2 = 10; const calculator = new Calculator(); // Act const result = calculator.add(num1, num2); // Assert assert.strictEqual(result, 15); }); """ **Don't Do This:** """javascript // Mixing arrange, act, and assert steps it('should add two numbers correctly', () => { const num1 = 5; const num2 = 10; const calculator = new Calculator(); const result = calculator.add(num1, num2); assert.strictEqual(result, 15); // Hard to discern sections }); """ **Why:** Clearly delineating the arrange, act, and assert sections makes each test case easier to understand and debug. ### 3.2. Standard: Clear and Descriptive Test Names **Standard:** Use clear, concise, and descriptive names for test suites and test cases. The name should clearly indicate what is being tested and the expected outcome. **Do This:** """javascript describe('Login Component', () => { it('should display an error message when the username is empty', () => { // ... }); it('should successfully log in with valid credentials', () => { // ... }); }); """ **Don't Do This:** """javascript describe('Login', () => { it('test1', () => { // ... }); it('test2', () => { // ... }); }); """ **Why:** Descriptive test names make it easier to understand the purpose of each test case and quickly identify failures. ### 3.3. Standard: Focus on Single Assertions per Test **Standard:** Aim to test one specific thing per "it()" block. Multiple assertions within a single test case can make it difficult to pinpoint the cause of a failure. While this standard can be bent if the assertions are *tightly* coupled, prefer single-assertion tests. **Do This:** """javascript it('should correctly set the username', () => { // ... assert.strictEqual(user.username, 'testuser'); }); it('should correctly set the email', () => { // ... assert.strictEqual(user.email, 'test@example.com'); }); """ **Don't Do This:** """javascript it('should correctly set the username and email', () => { // ... assert.strictEqual(user.username, 'testuser'); assert.strictEqual(user.email, 'test@example.com'); }); """ **Why:** Single assertions make it easier to isolate failures and understand the specific issue. This drastically reduces debugging time in a larger project. When a test fails due to multiple assertions, you only know that *something* went wrong. With single assertions, the failing test tells you *exactly* what went wrong, and focuses debugging efforts. ## 4. Modern Mocha Features and Best Practices (Latest Version) Mocha and its related ecosystem are actively maintained. Keep abreast of them, and promote usage in teams. ### 4.1 Standard: Asynchronous Testing with "async/await" **Standard:** Use "async/await" for asynchronous tests. This is the modern standard, and significantly improves readability. **Do This:** """javascript it('should fetch data from API', async () => { const response = await fetch('https://api.example.com/data'); const data = await response.json(); assert.ok(data); }); """ **Don't Do This:** """javascript it('should fetch data from API', (done) => { fetch('https://api.example.com/data') .then(response => response.json()) .then(data => { assert.ok(data); done(); }) .catch(err => done(err)); }); """ Older versions of Javascript use "done()" callbacks, and promise ".then" chains. Although functionally equivalent, these patterns are considered legacy. The "async/await" pattern results in more readable and more maintainable code. **Why:** Async/await provides a cleaner and more readable syntax for handling asynchronous operations compared to callbacks or promises. ### 4.2 Standard: Using Arrow Functions **Standard:** When defining test cases and hooks, consider using arrow functions ("=>") for conciseness and lexical "this" binding. Be mindful of "this" context implications (arrow functions *don't* bind their own "this"). If you need dynamic context, a standard "function" declaration may be more appropriate. **Do This:** """javascript describe('User Model', () => { beforeEach(async () => { // Concise arrow function for setup await connectDB(); }); it('should create a new user', async () => { // Concise arrow function for test case const user = new User({ username: 'testuser', email: 'test@example.com' }); await user.save(); const savedUser = await User.findOne({ username: 'testuser' }); assert.strictEqual(savedUser.email, 'test@example.com'); }); }); """ **Don't Do This:** """javascript describe('User Model', function() { // Older-style function declaration beforeEach(async function() { // Older-style function declaration await connectDB(); }); it('should create a new user', async function() { // Older-style function declaration const user = new User({ username: 'testuser', email: 'test@example.com' }); await user.save(); const savedUser = await User.findOne({ username: 'testuser' }); assert.strictEqual(savedUser.email, 'test@example.com'); }); }); """ **Why:** Arrow functions are more concise, and their usage promotes better coding style. However, be aware of how arrow functions affect the value of "this", especially in Mocha hooks. ### 4.3 Standard: Modern Assertions **Standard**: Use modern assertion libraries like Chai, Jest, or built-in Node.js "assert" with strict equality ("assert.strictEqual", "assert.deepStrictEqual"). Avoid legacy assertions. Also, where possible, use more descriptive assertions to provide better debugging information. **Do This:** """javascript const assert = require('assert'); it('should have the correct value', () => { const result = 5; assert.strictEqual(result, 5, 'Result should be 5'); // Message provides context }); """ **Don't Do This:** """javascript const assert = require('assert'); it('should have the correct value', () => { const result = 5; assert.equal(result, 5); // Lose type information when debugging }); """ **Why**: Strict equality checks both value and type, preventing subtle bugs. Descriptive messages provide valuable context when tests fail, saving debugging time. ## 5. Common Anti-Patterns ### 5.1 Anti-Pattern: The "God" Test File **Description:** A single test file that contains all tests for the entire application or a very large module. **Why to Avoid:** Becomes unmanageable, slow to run, difficult to debug, and prone to conflicts. **Solution:** Break down the test suite into smaller, focused test files. ### 5.2 Anti-Pattern: Testing Implementation Details **Description:** Tests that directly depend on the internal implementation of a module. **Why to Avoid:** Refactoring the implementation will break the tests, even if the functionality remains the same. This will cause developers to become hesitant to refactor code, resulting in slower and messier development. **Solution:** Test the public API and expected behavior of the module. ### 5.3 Anti-Pattern: Ignoring Edge Cases **Description:** Failing to test edge cases, boundary conditions, and error handling. **Why to Avoid:** Can lead to unexpected bugs and vulnerabilities in production. **Solution:** Explicitly identify and test all edge cases. ## 6. Performance Optimization ### 6.1 Standard: Parallel Test Execution **Standard**: Utilize Mocha's parallel execution capabilities (or tools like "concurrently" or "npm-run-all") for large test suites to significantly reduce execution time. Make sure tests are properly isolated and don't share global state when running in parallel. **Implementation**: You may need to refactor parts of your tests to accommodate this. Review the Mocha settings around parallel execution. **Why**: By running tests in parallel, total test execution time is dramatically reduced, improving developer productivity. ### 6.2 Standard: Test Selection **Standard**: Only run the tests you need to run. Use Mocha's features like "grep" or environment-specific configuration to target specific tests or test suites during development and debugging. **Implementation**: Use "mocha --grep" during development when working on a specific feature. **Why**: Improves the speed of the development cycle. ## 7. Security Best Practices ### 7.1 Standard: Avoid Hardcoding Secrets **Standard**: Never hardcode sensitive information (API keys, passwords, etc.) in your test files. Use environment variables or configuration files to manage secrets. **Do This**: """javascript // Using environment variables const apiKey = process.env.API_KEY; it('should authenticate with API', async () => { //... use apiKey }); """ **Don't Do This**: """javascript // Hardcoding secrets const apiKey = 'YOUR_API_KEY'; it('should authenticate with API', async () => { //... use apiKey }); """ **Why:** Prevents accidental exposure of secrets in version control systems. ### 7.2 Standard: Input Validation **Standard**: When testing components that handle user input, always validate inputs to protect against injection attacks (SQL injection, XSS). **Implementation**: Utilize a code analysis tool in CI/CD pipelines. **Why**: Prevents security vulnerabilities during testing. These standards provide a strong foundation for building robust, maintainable, and secure Mocha test suites. By adhering to these guidelines, development teams can improve the quality of their code, reduce debugging time, and ensure the reliability of their applications.
# Deployment and DevOps Standards for Mocha This document outlines the deployment and DevOps standards for Mocha test suites. It aims to provide a practical guide for developers to ensure robust, reliable, and maintainable end-to-end testing within a CI/CD pipeline. ## 1. Build Processes and CI/CD Integration ### 1.1. Standard: Use a Reliable Build System **Do This:** * Utilize a build system like npm or yarn for managing dependencies and running tests. * Define build scripts in "package.json" to encapsulate the test execution process. **Don't Do This:** * Rely on manual or ad-hoc commands for running tests. * Commit "node_modules" to your repository. **Why:** A well-defined build system ensures consistent and reproducible test executions across different environments. **Example:** """json // package.json { "name": "my-mocha-project", "version": "1.0.0", "scripts": { "test": "mocha --reporter mochawesome --reporter-options reportDir=./mochawesome-report", "test:watch": "mocha --watch", "ci": "mocha --reporter spec" }, "devDependencies": { "mocha": "^10.0.0", // Ensure using a current version "mochawesome": "^7.0.0", "chai": "^4.0.0" } } """ **Explanation:** * "test": Runs Mocha with the mochawesome reporter to generate a detailed HTML report. * "test:watch": Runs Mocha in watch mode for continuous testing during development. * "ci": Runs Mocha with a simple spec reporter for CI environments. * Specific versions of mocha, mochawesome, and chai are specified in the "devDependencies". ### 1.2. Standard: Integrate with CI/CD Pipelines **Do This:** * Incorporate Mocha tests into your CI/CD pipeline (e.g., GitHub Actions, GitLab CI, Jenkins). * Fail the build if any Mocha test fails. * Collect and report test results in a standardized format (e.g., JUnit XML). **Don't Do This:** * Bypass test execution during the deployment process. * Ignore test failures in the CI/CD pipeline. **Why:** Integration with CI/CD ensures that tests are automatically run on every code change, early detection of regressions, and a higher confidence level in code deployments. **Example (GitHub Actions):** """yaml # .github/workflows/ci.yml name: CI on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest strategy: matrix: node-version: [18.x, 20.x] steps: - uses: actions/checkout@v3 - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run tests run: npm test - name: Upload test results uses: actions/upload-artifact@v3 if: always() with: name: mochawesome-report path: mochawesome-report """ **Explanation:** * This workflow runs on every push to the "main" branch and every pull request targeting it. * It sets up Node.js with multiple versions using a matrix strategy, installs dependencies, runs tests using the "npm test" script, and uploads the mochawesome report as an artifact. * Using "npm ci" over "npm install" ensures a clean install from "package-lock.json", improving reliability. ### 1.3. Standard: Configure Environment Variables **Do This:** * Use environment variables to configure test behavior that varies between environments (e.g., API endpoints, database connections, API keys). * Set environment variables in your CI/CD pipeline. **Don't Do This:** * Hardcode environment-specific values in your test code. * Commit sensitive information (e.g., API keys) to your repository. **Why:** Environment variables allow your tests to adapt to different environments without requiring code changes. **Example:** """javascript // test/test.js const assert = require('assert'); const apiEndpoint = process.env.API_ENDPOINT || 'http://localhost:3000'; // Default value describe('API Tests', () => { it('should return 200 OK', async () => { const response = await fetch("${apiEndpoint}/health"); assert.strictEqual(response.status, 200); }); }); """ """yaml # .github/workflows/ci.yml jobs: build: steps: - name: Run tests env: API_ENDPOINT: https://production.example.com run: npm test """ **Explanation:** * The "API_ENDPOINT" environment variable is used to configure the API endpoint for the tests. * A default value is provided in case the environment variable is not set. * The GitHub Actions workflow sets the "API_ENDPOINT" environment variable to the production API endpoint for the test run. ## 2. Production Considerations ### 2.1. Standard: Isolate Test Environments **Do This:** * Use separate test environments that are isolated from production environments to prevent data corruption and unintended side effects. * Consider using Docker containers or virtual machines to create isolated test environments. **Don't Do This:** * Run tests directly against production databases or APIs. * Share test environments with other development teams. **Why:** Isolated test environments ensure the integrity and reliability of your tests and prevent them from impacting production systems. **Example (Docker):** Create a "Dockerfile" for your test environment: """dockerfile # Dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm install COPY . . CMD ["npm", "test"] """ Then, build and run the Docker container: """bash docker build -t my-mocha-test . docker run my-mocha-test """ **Explanation:** * The "Dockerfile" defines the steps to create a Docker image for the test environment. * It installs Node.js and the project dependencies, copies the project files, and runs the tests using the "npm test" script. * Running the Docker container will execute the tests in an isolated environment. ### 2.2. Standard: Manage Test Data **Do This:** * Use a dedicated test database or API for your tests. * Populate the test database with realistic but non-sensitive test data before each test run. * Clean up the test database after each test run to ensure a consistent state. * Consider using database seeding tools or fixtures to manage test data. **Don't Do This:** * Use production data for testing. * Leave the test database in an inconsistent state between test runs. **Why:** Proper test data management ensures that your tests are repeatable and reliable. **Example (using a setup/teardown script):** """javascript // test/test.js const assert = require('assert'); const db = require('../db'); // Assume a db connection module describe('Database Tests', () => { beforeEach(async () => { await db.seedDatabase(); // Populate with test data }); afterEach(async () => { await db.clearDatabase(); // Clean up data }); it('should create a new user', async () => { const user = await db.createUser({ name: 'Test User' }); assert.strictEqual(user.name, 'Test User'); }); }); """ """javascript // db.js (example) const { Pool } = require('pg'); const pool = new Pool({ user: 'testuser', host: 'localhost', database: 'testdb', password: 'testpassword', port: 5432, }); async function seedDatabase() { await pool.query('INSERT INTO users (name) VALUES ($1)', ['Initial User']); } async function clearDatabase() { await pool.query('DELETE FROM users'); } async function createUser(userData) { const result = await pool.query('INSERT INTO users (name) VALUES ($1) RETURNING *', [userData.name]); return result.rows[0]; } module.exports = { seedDatabase, clearDatabase, createUser }; """ **Explanation:** * The "beforeEach" hook populates the test database with test data before each test case. * The "afterEach" hook clears the test database after each test case. * The "seedDatabase" and "clearDatabase" functions (in "db.js") implement the database seeding and cleanup logic. This example uses PostgreSQL, but the concept can be applied to other databases as well. ### 2.3. Standard: Monitoring and Alerting **Do This:** * Monitor the execution of your Mocha tests in production environments (if applicable) (e.g. end-to-end tests that run against a staging environment). * Set up alerts to notify you of test failures or slow test execution times. * Use monitoring tools like Prometheus, Grafana, or Datadog to collect and visualize test metrics. **Don't Do This:** * Ignore test failures in production. * Fail to monitor the performance of your tests. **Why:** Monitoring and alerting enable you to detect and resolve issues with your tests quickly, minimizing the impact on your application. **Example (collecting test execution times):** """javascript // test/test.js const assert = require('assert'); const promClient = require('prom-client'); const testDuration = new promClient.Histogram({ name: 'test_duration_seconds', help: 'Duration of a test case in seconds', labelNames: ['test_name'], }); describe('API Tests', () => { it('should return 200 OK', async function() { const start = Date.now(); try { const response = await fetch('http://localhost:3000/health'); assert.strictEqual(response.status, 200); } finally { const duration = (Date.now() - start) / 1000; testDuration.observe({ test_name: this.test.fullTitle() }, duration); } }); }); """ **Explanation:** * The "prom-client" library is used to create a Prometheus histogram metric for test duration. * The "testDuration.observe" method is used to record the duration of each test case. * The "this.test.fullTitle()" provides a unique identifier for each test ensuring the correct metric gets updated for each test case. * To expose the metrics to Prometheus you will need an endpoint: """javascript // server.js (example) const promClient = require('prom-client'); const express = require('express'); const app = express(); const port = 3001; const collectDefaultMetrics = promClient.collectDefaultMetrics; collectDefaultMetrics({ prefix: 'my_application_' }); app.get('/metrics', async (req, res) => { res.set('Content-Type', promClient.register.contentType); const metrics = await promClient.register.metrics(); res.end(metrics); }); app.listen(port, () => { console.log("Metrics server listening at http://localhost:${port}"); }); """ And configure Prometheus to scrape this endpoint. Then use Grafana to display the test duration metrics. ## 3. Modern Approaches and Patterns ### 3.1. Standard: Parallel Test Execution **Do This:** * Utilize Mocha's parallel execution capabilities, or third-party tools like "concurrently", to run tests in parallel. * Determine the optimal number of parallel processes based on your system's resources. * Ensure your tests are independent and do not share state when running in parallel. **Don't Do This:** * Run tests serially, especially for large test suites. * Assume that tests will run in a specific order when running in parallel. **Why:** Parallel test execution can significantly reduce test execution time, speeding up the CI/CD process. **Example (Mocha with Parallel Execution):** """json // package.json { "scripts": { "test:parallel": "mocha --parallel --reporter mochawesome --reporter-options reportDir=./mochawesome-report" } } """ Run with: "npm run test:parallel" **Explanation:** * The "--parallel" flag tells Mocha to run tests in parallel. Mocha automatically determines an appropriate level of parallelism according to the number of available CPUs. ### 3.2. Standard: Test Retries **Do This:** * Implement test retries to handle transient failures (e.g., network connectivity issues). * Use Mocha's "--retries" flag or a third-party library like "mocha-retry" to configure test retries. * Limit the number of retries to prevent masking genuine bugs. **Don't Do This:** * Retry tests indefinitely. * Retry tests without understanding the root cause of the failures. **Why:** Test retries can improve the stability of your test suite and prevent false positives. **Example (Mocha with Retries):** """json // package.json { "scripts": { "test:retries": "mocha --retries 2 --reporter mochawesome --reporter-options reportDir=./mochawesome-report" } } """ Run with: "npm run test:retries" **Explanation:** * The "--retries 2" flag configures Mocha to retry each test up to 2 times if it fails. ### 3.3. Standard: Containerization and Orchestration **Do This:** * Containerize your test environment using Docker. * Use container orchestration tools like Kubernetes or Docker Compose to manage and scale your test environment. **Don't Do This:** * Rely on manual setup and configuration of test environments. * Fail to version control your test environment configuration. **Why:** Containerization and orchestration provide a consistent, reproducible, and scalable test environment. **Example (Docker Compose):** """yaml # docker-compose.yml version: "3.9" services: test: build: . environment: API_ENDPOINT: http://api:3000 depends_on: - api api: image: my-api:latest """ **Explanation:** * This "docker-compose.yml" file defines two services: "test" and "api". * The "test" service builds a Docker image from the current directory and runs the tests. * It sets the "API_ENDPOINT" environment variable to the "api" service's address. * The "depends_on" directive ensures that the "api" service is started before the "test" service. ## 4. Security Best Practices ### 4.1. Standard: Secret Management **Do This:** * Use a secure secret management solution (e.g., HashiCorp Vault, AWS Secrets Manager) to store and manage sensitive information like API keys, database passwords, and certificates. * Retrieve secrets from the secret management solution at runtime using environment variables or configuration files. **Don't Do This:** * Store secrets in your code, configuration files, or environment variables in plain text. * Commit secrets to your repository. **Why:** Secure secret management protects sensitive information from unauthorized access and prevents security breaches. **Example (using environment variables):** """javascript // test/test.js const apiKey = process.env.API_KEY; describe('API Tests', () => { it('should authenticate with API key', async () => { // use apiKey to authenticate with API. }); }); """ **CI/CD Pipeline (example with GitHub Actions secrets):** In your GitHub repository, go to Settings > Secrets > Actions and add "API_KEY" with the appropriate secret value. Then, in your workflow: """yaml # .github/workflows/ci.yml jobs: build: steps: - name: Run tests env: API_KEY: ${{ secrets.API_KEY }} run: npm test """ **Explanation:** * The "API_KEY" environment variable is used to pass the API key to the tests. * The value of the "API_KEY" environment variable is retrieved from the GitHub Actions secrets store. * The secret is not stored in the code or configuration files. ### 4.2. Standard: Input Sanitization **Do This:** * Sanitize any input to your tests, especially if the input comes from external sources (e.g., environment variables, command-line arguments). * Use input validation libraries or regular expressions to ensure that the input is in the expected format and range. **Don't Do This:** * Trust input from external sources without validation. * Use unsanitized input in database queries or API calls. **Why:** Input sanitization prevents security vulnerabilities like SQL injection and cross-site scripting (XSS). **Example (validating environment variables):** """javascript // test/test.js const assert = require('assert'); const apiEndpoint = process.env.API_ENDPOINT; if (!apiEndpoint) { throw new Error('API_ENDPOINT environment variable is not set'); } try { new URL(apiEndpoint); // Validate as URL } catch (error) { throw new Error('API_ENDPOINT is not a valid URL'); } describe('API Tests', () => { it('should return 200 OK', async () => { const response = await fetch(apiEndpoint + '/health'); assert.strictEqual(response.status, 200); }); }); """ **Explanation:** * This example validates that the "API_ENDPOINT" environment variable is set and is a valid URL. * If the environment variable is not set or is not a valid URL, an error is thrown. ## 5. Deprecated Features and Anti-Patterns ### 5.1. Anti-Pattern: Global Variables **Don't Do This:** * Declare Mocha-related variables (e.g., "describe", "it") in the global scope. **Why:** Global variables can lead to naming conflicts and unexpected behavior. Mocha inherently makes these functions available globally for test files, there is no need to declare them again. ### 5.2. Anti-Pattern: Synchronous Operations in Async Tests **Don't Do This:** * Perform synchronous operations (e.g., blocking I/O) in asynchronous tests without wrapping them in "Promise.resolve()" or a similar mechanism. **Why:** Synchronous operations can block the event loop and cause performance issues and inaccurate test timings. **Correct Example:** """javascript it('should perform synchronous operation async', async () => { const result = await Promise.resolve(syncFunction()); assert.strictEqual(result, 'expected'); }); function syncFunction() { // some synchronous work return 'expected'; } """ ### 5.3. Deprecated: "this.done()" **Don't Do This (if using Promises or async/await):** * Utilize the "this.done()" callback mechanism when using Promises or async/await for asynchronous testing. **Why:** Using both Promises and "this.done()" can lead to unexpected behavior or early test termination. If using async/await or Promises, Mocha detects test completion automatically. **Correct Example (async/await):** """javascript it('should return data', async () => { const data = await fetchData(); assert.ok(data); }); """ This comprehensive guide provides a solid foundation for creating robust and maintainable Mocha test suites within a DevOps environment. Adhering to these standards will significantly improve the reliability and efficiency of your testing process. Remember to always consult the latest [Mocha documentation](https://mochajs.org/) for the most up-to-date information.
# Performance Optimization Standards for Mocha This document outlines the coding standards for optimizing the performance of Mocha test suites. Following these standards will improve test execution speed, reduce resource consumption, and enhance the overall development workflow. ## 1. General Principles ### 1.1. Prioritize Test Execution Speed * **Do This:** Design tests to execute quickly. Aim for sub-second execution times for unit tests and low single-digit second execution times for integration tests. * **Don't Do This:** Allow tests to linger for tens of seconds or minutes, as this significantly increases feedback cycles and reduces developer productivity. ***Why?*** Faster tests allow developers to receive quicker feedback, promoting more frequent testing and faster identification of issues. ### 1.2. Minimize Resource Consumption * **Do This:** Ensure tests use minimal memory and CPU resources. Clean up resources after each test to prevent memory leaks or resource exhaustion. * **Don't Do This:** Create tests that consume large amounts of memory or cause excessive CPU load. ***Why?*** Resource-intensive tests can slow down the entire test suite and potentially impact the stability of the testing environment. ### 1.3. Isolate Tests * **Do This:** Ensure each test is independent of others. Use hooks ("before", "after", "beforeEach", "afterEach") to set up and tear down the environment required for each test. * **Don't Do This:** Allow tests to depend on shared state or the execution order of other tests. ***Why?*** Independent tests are easier to reason about, debug, and run in parallel, maximizing the effectiveness of parallel execution. ## 2. Test Suite Structure and Configuration ### 2.1. Use "describe" and "it" Block Nesting Effectively * **Do This:** Organize tests using "describe" blocks to group related tests and provide context. Use nested "describe" blocks to further refine the organization. Aim for a clear hierarchy that reflects the structure of the code being tested. Use "it" blocks to define individual test cases. * **Don't Do This:** Create overly complex or deeply nested "describe" structures that make the test suite difficult to navigate. Avoid excessively long descriptions in "it" blocks. ***Why?*** A well-structured test suite improves readability and maintainability. It helps developers quickly find relevant tests and understand the purpose of each test. """javascript describe('User authentication', () => { beforeEach(() => { // Setup authentication environment }); describe('Valid credentials', () => { it('should allow access', () => { // Test valid credentials }); }); describe('Invalid credentials', () => { it('should deny access with incorrect password', () => { // Test invalid credentials }); it('should deny access with incorrect username', () => { // Test invalid credentials }); }); afterEach(() => { // Teardown authentication environment }); }); """ ### 2.2. Configure Mocha for Performance * **Do This:** Use Mocha's configuration options to optimize performance. Experiment with different reporters (e.g., "min", "dot") and enable parallel execution if appropriate. Consider using a separate configuration file ("mocha.opts" or "mocha.config.js") to manage settings. * **Don't Do This:** Use default Mocha settings without considering performance implications. Neglect to adjust settings (timeout, retries) where necessary. ***Why?*** Properly configured Mocha settings can significantly reduce test execution time and improve the test feedback loop. """javascript // Example mocha.config.js module.exports = { require: ['@babel/register'], // or ts-node/register reporter: 'min', timeout: 5000, // Reduced Timeout parallel: true, jobs: 4, // Adjust based on CPU cores }; """ ### 2.3. Selective Test Execution * **Do This:** Use Mocha's features to run specific tests or groups of tests during development. Use the "-g" flag to run tests matching a specific pattern in their description while debugging. Use ".only" to focus on specific "describe" or "it" blocks temporarily. Remove ".only" before committing code. * **Don't Do This:** Always run the entire test suite during development, as this can be time-consuming. Leave ".only" statements in committed code. Example: """bash mocha -g "authentication" # Runs only tests with "authentication" in the description """ """javascript describe('User authentication', () => { it.only('should allow access', () => { // This test will be the only one run within User authentication (temporarily) }); it('should deny access with incorrect password', () => { // This test is untouched because it's not involved in focus right now }); }); """ ***Why?*** Selective test execution allows developers to focus on specific areas of the codebase and receive faster feedback. ### 2.4 Enable Parallel Execution and Choose the Correct Mode * **Do This:** Utilize Mocha's parallel execution for suites that are designed to be run independently. Consider using "parallel: true" in your configuration file ("mocha.config.js") or use the "--parallel" CLI flag. Experiment with the "jobs" option to adjust the process/thread count. * **Don't Do This:** Naively enable parallel execution without ensuring tests are properly isolated. Over-subscribe the number of jobs, which can lead to context switching overhead and reduced performance. ***Why?*** Parallel execution can significantly reduce the overall test suite execution time for suites with independent tests. Mocha offers different parallel modes. For CPU-bound tests (pure JavaScript logic), using multiple processes is advantageous due to bypassing Node.js's single-threaded nature (without worker threads). For I/O-bound tests, using a thread pool (if available) or a process pool can yield benefit as well. """bash mocha --parallel --jobs 8 # Runs tests in parallel using 8 processes """ ## 3. Test Implementation ### 3.1. Use Asynchronous Testing Correctly * **Do This:** Use "async" and "await" for asynchronous tests for cleaner and more readable code. Alternatively, return a Promise from the "it" block for asynchronous operations. Handle rejections gracefully. * **Don't Do This:** Rely on callbacks without proper error handling which leads to brittle tests. Mix callback-style asynchronous code with Promises, as this reduces readability. ***Why?*** Modern asynchronous testing techniques improve code readability and simplify error handling. """javascript it('should fetch user data', async () => { const userData = await fetchUserData(); expect(userData).to.be.an('object'); expect(userData).to.have.property('name'); }); it('should handle errors when fetching user data', async () => { try { await fetchUserDataThatFails(); // Assume fetchUserDataThatFails rejects assert.fail('Should have rejected'); } catch (error) { expect(error).to.be.an('Error'); expect(error.message).to.equal('Failed to fetch user data'); } }); """ ### 3.2. Minimize Test Fixture Setup and Teardown * **Do This:** Reuse test fixtures across multiple tests when appropriate. Consider creating a single setup function that can be used in "before" or "beforeEach" hooks rather than duplicating code. * **Don't Do This:** Create separate setup and teardown functions for each test, leading to redundant code and increased execution time. ***Why?*** Minimizing test fixture setup and teardown reduces the overhead of each test and improves execution speed. """javascript let sharedData; // Shared across tests in this scope before(() => { // Executed once before all tests in this scope sharedData = initializeTestData(); }); it('should use shared data', () => { expect(sharedData).to.not.be.undefined; // Test something specific from shared data }); it('should modify shared data (safely)', () => { // Consider making a DEEP COPY of sharedData here before modifying it significantly // to avoid polluting the original data for other tests if not intended. const localCopy = {...sharedData}; // Shallow copy for simple objects. Use lodash.deepClone for complex objects. localCopy.newValue = 'modified'; expect(localCopy.newValue).to.equal('modified'); expect(sharedData.newValue).to.be.undefined; // Or be the original value. }); after(() => { //Executed once after all teats in this group cleanupTestData(sharedData); // Clean up the data after all tests are done. }) """ ### 3.3. Optimize Assertion Libraries * **Do This:** Use assertion libraries efficiently. Prefer specific assertions (e.g., "expect(x).to.equal(5)") over generic assertions (e.g., "expect(x == 5).to.be.true"). Use deep equality checks ("expect(obj1).to.eql(obj2)") only when necessary, as they can be expensive. * **Don't Do This:** Use inefficient or verbose assertions that slow down test execution. ***Why?*** Optimized assertion libraries reduce the computational overhead of each test. ### 3.4. Avoid Network Requests and I/O Operations in Unit Tests * **Do This:** Mock network requests and file system operations in unit tests. Use tools like "nock" or "sinon.js" to create mock APIs and file systems. * **Don't Do This:** Make actual network requests or read/write files during unit tests, introducing external dependencies and slowing down execution. ***Why?*** Isolating unit tests from external dependencies makes them faster, more reliable, and easier to reason about. """javascript const nock = require('nock'); describe('fetchData', () => { it('should fetch data successfully', async () => { const mock = nock('https://api.example.com') .get('/data') .reply(200, { key: 'value' }); const data = await fetchData(); // Assume fetchData uses the API expect(data).to.deep.equal({ key: 'value' }); mock.done(); // Ensure the mock was used. }); }); """ ### 3.5. Stubs instead of Spies Where Appropriate * **Do This:** Use stubs when you want to completely control the behavior and return value of a function, especially for simplifying dependencies or simulating specific error conditions. Use spies when you primarily want to track how a function is called (arguments, call count, etc.) without altering its behavior * **Don't Do This:** Use Spies to intercept behavior when simply stubbing the call is the goal. Doing so can be slower. ***Why?*** Stubs can be simpler and faster than spies when the primary goal is to control the function's return value or prevent it from executing its original code. Spies add an extra layer of observation that can introduce overhead if not needed. """javascript const sinon = require('sinon'); describe('processPayment', () => { it('should call the payment gateway and return success', async () => { const paymentGateway = { process: () => Promise.resolve({ success: true }) }; const stub = sinon.stub(paymentGateway, 'process').resolves({ success: true }); // Using stub here to control the return value. const paymentProcessor = new PaymentProcessor(paymentGateway); //PaymentProcessor's constructor takes the PaymentGateway instance. const result = await paymentProcessor.processPayment(100); expect(result.success).to.be.true; expect(stub.calledOnce).to.be.true; stub.restore() // Restore the stub }); }); """ ### 3.6. Use "this.skip()" Strategically * **Do This:** Use "this.skip()" to skip tests that are not relevant to the current environment or configuration, or temporary skip tests that are known to be failing (and have a follow-up task to fix). Provide a clear reason for skipping the tests. * **Don't Do This:** Leave commented-out tests instead of using "this.skip()", which clutters the codebase. Skip tests without a clear explanation. ***Why?*** Skipping irrelevant or temporarily failing tests prevents unnecessary execution and provides a clear signal that those tests require attention. """javascript it('should only run in production', () => { if (process.env.NODE_ENV !== 'production') { this.skip(); // Skips if not in production } // Test production-specific logic }); it('should test something that is broken', () => { this.skip('Temporarily skipping due to issue #123. Will fix next sprint.'); }); """ ## 4. Code Quality and Maintainability ### 4.1. Write Clear and Concise Tests * **Do This:** Write tests that are easy to understand and maintain. Use descriptive names for "describe" and "it" blocks. Keep tests focused on a single scenario or aspect of the code. * **Don't Do This:** Write complex or convoluted tests that are difficult to debug or modify. Include multiple assertions in a single test unless they are tightly related to the same concept. ***Why?*** Clear and concise tests reduce the cognitive load required to understand and maintain the test suite. ### 4.2. Avoid Code Duplication * **Do This:** Refactor common test logic into reusable functions or modules. Use helper functions to encapsulate setup, teardown, and assertion logic. * **Don't Do This:** Duplicate code across multiple tests. ***Why?*** Reducing code duplication improves the maintainability and readability of the test suite. ### 4.3. Follow Consistent Coding Style * **Do This:** Adhere to a consistent coding style throughout the test suite, including indentation, naming conventions, and code formatting. Use a linter and code formatter to enforce style guidelines. * **Don't Do This:** Use inconsistent or arbitrary coding styles. ***Why?*** A consistent coding style improves the readability and maintainability of the test suite. ## 5. Continuous Improvement ### 5.1. Monitor Test Performance * **Do This:** Regularly monitor the test suite's execution time. Use CI/CD pipelines to track performance trends and identify regressions. * **Don't Do This:** Neglect to monitor test performance. ***Why?*** Monitoring test performance allows you to identify and address performance bottlenecks proactively. ### 5.2. Refactor Tests Regularly * **Do This:** Refactor the test suite as the codebase evolves. Remove obsolete tests and update tests to reflect changes in functionality. * **Don't Do This:** Allow the test suite to become stale or out of sync with the codebase. ***Why?*** Regular refactoring ensures that the test suite remains relevant, accurate, and maintainable. ### 5.3. Explore new Mocha Features * **Do This:** Stay up-to-date with the latest Mocha features and best practices. Explore new reporters, configuration options, and asynchronous testing techniques. Read the release notes and try out new APIs as they become available. * **Don't Do This:** Rely on outdated techniques or ignore new features that could improve performance. ***Why?*** By leveraging the latest features, you can continuously improve the efficiency and effectiveness of your test suite. ## 6. Example: Real-World Optimization Scenario Consider testing a function that processes a large dataset and writes the result to a database. A naive test might involve processing the entire dataset for each test case. **Anti-Pattern:** """javascript it('should process the entire dataset correctly', async () => { const data = generateLargeDataset(); //Creates a large Dataset const result = await processData(data); expect(result).to.be.an('object'); // More assertions based on the entire dataset. }); it('should handle edge cases in the dataset', async () => { const data = generateLargeDataset(); // Creates large Dataset again injectEdgeCases(data); // Adds some different scenarios to it. const result = await processData(data); //Edge case assertions. }); """ **Optimized:** """javascript describe('data processing', () => { let sampleData; // Smaller sample size before(async () => { sampleData = generateSampleDataset(); // Generate a representative smaller dataset. await seedDatabase(sampleData); // Populate db to test with smaller data. }); after(async () => { await clearDatabase(); // Clean up the data to maintain test isolation. }); it('should process data correctly', async () => { const result = await fetchDataFromDatabase(); expect(result).to.be.an('array'); // Assertions based on the processed data. }); it('should handle edge cases correctly', async () => { const edgeCaseData = injectSpecialCases(sampleData); // Smaller data injects special scenarios. await updateDatabase(edgeCaseData) // Modifies existing Database const result = await fetchDataForEdgeCases(); // Specialized to only retrieve edge case data. expect(result).to.be.an('array'); // Specific Edge case assertions }); }); """ **Explanation:** * **Reduced Dataset Size:** Generate a much smaller "sampleData" for setup. This significantly reduces the work performed in each test. * **Database Seeding:** Seed a testing database once *before* all tests. This avoids repeated data generation and insertion. * **Specialized Data Generation and Selectivity:** Instead of processing a full set, "injectSpecialCases" create targeted edge cases. The optimized test only retrieves the edge cases with fetchDataForEdgeCases from db. * **Clean up:** Teardown database to ensure state between testing. This optimized example will execute much faster, especially when the original large dataset generation and processing were time-consuming.
# Code Style and Conventions Standards for Mocha This document outlines the code style and conventions standards for writing maintainable, performant, and secure Mocha tests. Adhering to these standards ensures consistency across the codebase, improves readability, and reduces the likelihood of errors. These guidelines are targeted toward teams using Mocha for JavaScript testing. ## 1. General Principles * **Consistency:** Maintain a consistent coding style throughout the project. Apply linters and formatters (such as ESLint and Prettier) to enforce these standards automatically. * **Readability:** Write code that is easy to understand and follow. Use meaningful names, clear comments, and consistent indentation. * **Maintainability:** Structure tests in a modular and reusable manner. Avoid duplication of code and adhere to the DRY (Don't Repeat Yourself) principle. * **Clarity:** Tests should clearly express the intent and expected behavior of the code under test. ## 2. Formatting ### 2.1. Indentation * **Do This:** Use 2 spaces for indentation. """javascript describe('MyComponent', () => { it('should render correctly', () => { // Test logic here }); }); """ * **Don't Do This:** Use tabs or mixed tabs and spaces. """javascript describe('MyComponent', () => { it('should render correctly', () => { // Test logic here }); }); """ **Why:** Consistent indentation improves readability and reduces confusion. ### 2.2. Line Length * **Do This:** Limit lines to a maximum of 120 characters. """javascript it('should handle extremely long input strings and correctly process them without exceeding the maximum buffer size', () => { // Test logic here }); """ * **Don't Do This:** Exceed the line limit. """javascript it('should handle extremely long input strings and correctly process them without exceeding the maximum buffer size, which can lead to performance issues when not handled correctly', () => { // Test logic here }); """ **Why:** Long lines make code harder to read and can cause it to wrap awkwardly on some displays. ### 2.3. Line Breaks * **Do This:** Break long chains of method calls for readability. """javascript expect(component.find('.my-class')) .to.have.lengthOf(1) .and.to.contain.text('Expected Text'); """ * **Don't Do This:** Write long, unbroken chains. """javascript expect(component.find('.my-class')).to.have.lengthOf(1).and.to.contain.text('Expected Text'); """ **Why:** Breaking long lines into multiple lines increases readability and makes debugging easier. ### 2.4. Spacing * **Do This:** Use spaces around operators. """javascript const sum = a + b; """ * **Don't Do This:** Omit spaces around operators. """javascript const sum=a+b; """ * **Do This:** Use a space after commas in lists. """javascript const myArray = [1, 2, 3]; """ * **Don't Do This:** Omit spaces after commas. """javascript const myArray = [1,2,3]; """ **Why:** Proper spacing makes code easier to read and reduces visual clutter. ### 2.5. Bracing * **Do This:** Use curly braces for all blocks, even single-line blocks. """javascript if (condition) { doSomething(); } """ * **Don't Do This:** Omit curly braces for single-line blocks. """javascript if (condition) doSomething(); """ **Why:** Curly braces improve readability and prevent potential errors when adding more lines to the block later. ## 3. Naming Conventions ### 3.1. Test Suites ("describe") * **Do This:** Use descriptive names for test suites that indicate the component or functionality being tested. Start with a capital letter and use PascalCase or Title Case. """javascript describe('UserProfileComponent', () => { // PascalCase preferred // Tests here }); describe('User Profile Component', () => { //Title Case is also acceptable // Tests here }); """ * **Don't Do This:** Use vague or non-descriptive names or snake_case. """javascript describe('test', () => { // Tests here }); describe('user_profile_component', () => { // Tests here }); """ **Why:** Clear names make it easier to understand the purpose of the test suite. ### 3.2. Test Cases ("it") * **Do This:** Write test case descriptions that clearly specify the expected behavior. Start descriptions with "should". """javascript it('should render the user\'s name', () => { // Test logic here }); """ * **Don't Do This:** Use vague or unclear descriptions. """javascript it('does something', () => { // Test logic here }); """ **Why:** Clear descriptions make it easier to understand what each test case is verifying. ### 3.3. Variables and Constants * **Do This:** Use "camelCase" for variable names. """javascript const userName = 'John Doe'; """ * **Do This:** Use "UPPER_SNAKE_CASE" for constant names. """javascript const MAX_USERS = 100; """ * **Don't Do This:** Use inconsistent or unclear naming. """javascript const username = 'John Doe'; // inconsistent casing const maxusers = 100; // unclear name """ **Why:** Consistent variable and constant naming improves code readability. ## 4. Stylistic Consistency ### 4.1. Assertions * **Do This:** Use a consistent assertion style, such as Chai's "expect", "assert", or "should" syntax. The "expect" style is often preferred for its readability and chainability. """javascript const expect = require('chai').expect; it('should be equal to 5', () => { expect(2 + 3).to.equal(5); }); """ * **Don't Do This:** Mix different assertion styles in the same project. """javascript const assert = require('chai').assert; const expect = require('chai').expect; it('should be equal to 5', () => { assert.equal(2 + 3, 5); // Mixing styles expect(2 + 3).to.equal(5); // Mixing styles }); """ **Why:** Consistency in assertion style makes tests easier to read and understand. ### 4.2. Hooks ("before", "after", "beforeEach", "afterEach") * **Do This:** Use hooks to set up and tear down test environments. Keep hook logic concise. """javascript describe('MyDatabase', () => { let db; beforeEach(() => { db = new Database(); db.connect(); }); afterEach(() => { db.disconnect(); }); it('should insert data correctly', () => { // Test logic here }); }); """ * **Don't Do This:** Perform complex logic or assertions inside hooks. Hooks should focus on setup and teardown only. """javascript describe('MyDatabase', () => { let db; beforeEach(() => { db = new Database(); db.connect(); expect(db.isConnected()).to.be.true; // Avoid assertions in hooks }); }); """ **Why:** Clear separation of setup, teardown, and test logic improves maintainability. ### 4.3. Test Structure * **Do This:** Follow the Arrange-Act-Assert (AAA) pattern in each test case. """javascript it('should add a new user', () => { // Arrange const userService = new UserService(); const userData = { name: 'John', email: 'john@example.com' }; // Act userService.addUser(userData); // Assert expect(userService.getUserCount()).to.equal(1); }); """ * **Don't Do This:** Mix arrange, act, and assert steps without clear separation. """javascript it('should add a new user', () => { const userService = new UserService(); // Arrange const userData = { name: 'John', email: 'john@example.com' }; // Arrange userService.addUser(userData); // Act expect(userService.getUserCount()).to.equal(1); // Assert }); """ **Why:** The AAA pattern makes test cases easier to understand and maintain. ## 5. Mocha-Specific Conventions ### 5.1. Asynchronous Tests * **Do This:** Use "async/await" for asynchronous tests. """javascript it('should fetch data from an API', async () => { const response = await fetchData(); expect(response.status).to.equal(200); }); """ * **Don't Do This:** Use callbacks or promises without proper handling, risking unhandled rejections. """javascript it('should fetch data from an API', (done) => { //Avoid 'done' callback unless strictly necessary fetchData() .then(response => { expect(response.status).to.equal(200); done(); }) .catch(err => { done(err); // Required to fail the test on error }); }); it('should fetch data from an API using promises', () => { // Without proper catch, unhandled rejections can occur return fetchData() .then(response => { expect(response.status).to.equal(200); }); }); """ **Why:** "async/await" makes asynchronous code easier to read and reason about, improving maintainability and reducing errors. Additionally, when using Promises, always ensure errors are handled using ".catch()" to prevent unhandled rejections. The "done" callback, while still supported, is generally discouraged unless dealing with legacy code or particularly complex asynchronous flows where "async/await" becomes unwieldy. ### 5.2. Skipping and Focusing Tests * **Do This:** Use ".skip" to temporarily skip tests and ".only" to focus on specific tests during development. Ensure these are removed or commented out before committing code. """javascript it.skip('should skip this test', () => { // This test will be skipped }); it.only('should focus on this test', () => { // Only this test will run }); """ * **Don't Do This:** Leave ".skip" or ".only" in committed code. """javascript it.only('should focus on this test', () => { // Only this test will run }); //This should be removed or changed before committing. """ **Why:** Leaving ".skip" or ".only" in committed code can lead to incomplete or inaccurate test results. ### 5.3. Use of "this" context * **Do This:** Use "this" context to share variables between hooks and tests, but avoid overusing it. """javascript describe('MyComponent', () => { beforeEach(function() { this.component = new MyComponent(); }); it('should initialize correctly', function() { expect(this.component.isInitialized).to.be.true; }); }); """ * **Don't Do This:** Rely heavily on "this" context for complex state management between tests. Consider more explicit dependency injection or state management patterns instead. """javascript describe('MyComponent', () => { beforeEach(function() { this.component = new MyComponent(); this.initialState = { ... }; // Excessive state stored in 'this' }); it('should update state correctly', function() { this.component.setState(this.initialState); // Relying too much on 'this' expect(this.component.getState()).to.deep.equal(this.initialState); }); }); """ **Why:** Overuse of the this context can lead to tightly coupled tests that are harder to reason about and maintain. ### 5.4 Parallel Execution Considerations * **Do This:** When running tests in parallel (Mocha supports parallel execution), ensure tests are isolated and do not share mutable state. Use separate databases or mock external services to avoid conflicts. """javascript describe('Parallel Tests', () => { let dbName; beforeEach(() => { // Generate a unique database name for each test run to prevent conflicts dbName = "testdb_${Date.now()}_${Math.random()}"; // Setup database using dbName }); afterEach(() => { // Cleanup database using dbName }); it('test 1', async () => { // Interact with the isolated database }); it('test 2', async () => { // Interact with the isolated database }); }); """ * **Don't Do This:** Share mutable state between tests running in parallel, as this can lead to race conditions and flaky tests. """javascript let sharedCounter = 0; // Avoid sharing mutable state describe('Parallel Tests - INCORRECT', () => { it('test 1', () => { sharedCounter++; // Race condition possible expect(sharedCounter).to.equal(1); }); it('test 2', () => { sharedCounter++; // Race condition possible expect(sharedCounter).to.equal(1); // This test might fail randomly }); }); """ **Why:** Parallel tests should be independent to prevent interference and ensure reliable test results. Use unique resources/databases and avoid shared variables. Mocha’s parallel execution capabilities (often enabled via command-line flags or configuration) can significantly reduce test suite execution time, but require careful attention to test isolation. ## 6. Code Examples ### 6.1. Example Structure """javascript // Import necessary modules const { expect } = require('chai'); const MyComponent = require('../src/MyComponent'); // Adjust the path as needed describe('MyComponent', () => { let component; beforeEach(() => { component = new MyComponent(); }); afterEach(() => { // Clean up resources if needed }); it('should initialize with default values', () => { expect(component.value).to.equal(0); expect(component.name).to.equal('Default Name'); }); it('should update the value correctly', () => { component.setValue(5); expect(component.value).to.equal(5); }); it('should throw an error when setting a negative value', () => { expect(() => component.setValue(-1)).to.throw('Value must be non-negative'); }); }); """ ### 6.2. Asynchronous Test Example using "async/await" """javascript const { expect } = require('chai'); const fetchData = require('../src/fetchData'); // Adjust the path as needed describe('fetchData', () => { it('should successfully fetch data from the API', async () => { const data = await fetchData('https://api.example.com/data'); expect(data).to.be.an('object'); expect(data.id).to.be.a('number'); expect(data.name).to.be.a('string'); }); it('should handle API errors gracefully', async () => { try { await fetchData('https://api.example.com/error'); } catch (error) { expect(error).to.be.an('error'); expect(error.message).to.equal('Request failed with status code 404'); // Or a more appropriate message } }); }); """ ### 6.3. Using Mocha’s "this.skip()" """javascript describe('Environment-specific tests', () => { beforeEach(function() { if (process.env.NODE_ENV !== 'test') { this.skip(); // Skip the entire suite if not in 'test' environment } }); it('should run only in the test environment', () => { // Test logic here expect(process.env.NODE_ENV).to.equal('test'); }); }); describe('Conditional Feature Tests', () => { it('should test a feature if it is enabled', function() { if (!isFeatureEnabled('someFeature')) { this.skip(); } // Test the 'someFeature' }); }); """ ### 6.4. Mocking and Stubbing Utilize libraries like "sinon" or "proxyquire" to isolate units under test and control dependencies. This avoids external dependencies and ensures tests are fast and deterministic. """javascript const sinon = require('sinon'); const { expect } = require('chai'); const UserService = require('../src/UserService'); const Database = require('../src/Database'); describe('UserService', () => { let userService; let databaseStub; beforeEach(() => { databaseStub = sinon.createStubInstance(Database); userService = new UserService(databaseStub); }); afterEach(() => { sinon.restore(); //Restore all stubs to prevent interference }); it('should create a user successfully', async () => { // Configure the stub to return a specific value databaseStub.createUser.resolves({ id: 1, name: 'John Doe' }); const user = await userService.createUser({ name: 'John Doe' }); expect(user).to.deep.equal({ id: 1, name: 'John Doe' }); // Verify that the stub was called with the correct arguments sinon.assert.calledWith(databaseStub.createUser, { name: 'John Doe' }); }); }); """ ## 7. Common Anti-Patterns * **Over-reliance on Global State:** Avoid modifying global state within tests, as it can lead to unpredictable behavior and interference between tests. * **Testing Implementation Details:** Focus on testing the public API and behavior of components rather than internal implementation details, which can make tests brittle and prone to breakage. * **Ignoring Edge Cases:** Ensure that tests cover a wide range of inputs, including edge cases, boundary conditions, and error scenarios, to ensure the robustness of the code. * **Lack of Test Isolation:** Ensure tests are isolated from each other to avoid dependencies and prevent interference, which can lead to flaky tests. * **Flaky Tests:** Address flaky tests immediately by investigating the root cause and fixing the underlying issues rather than simply re-running the tests. * **Long and Complex Tests:** Keep tests short, focused, and easy to understand. Break down complex scenarios into multiple smaller tests. * **Duplicated Setup Logic:** Use hooks ("before", "after", "beforeEach", "afterEach") to avoid duplicating setup and teardown logic across multiple tests. ## 8. Security Best Practices * **Avoid Hardcoding Secrets:** Never hardcode sensitive information such as API keys, passwords, or tokens directly in test files. Use environment variables or configuration files to manage secrets securely. * **Sanitize Input:** When testing code that processes user input, ensure that tests include cases with potentially malicious input to verify that the code is properly sanitizing the input to prevent security vulnerabilities such as cross-site scripting (XSS) or SQL injection. * **Rate Limiting Tests:** When testing APIs or services, implement rate limiting in tests to avoid overwhelming the service and potentially triggering denial-of-service (DoS) conditions. * **Mock External Services:** When testing code that interacts with external services, use mocking or stubbing techniques to simulate the behavior of those services and prevent tests from inadvertently interacting with live production systems. This also prevents unexpected data changes or costs on external systems. * **Validate Access Control:** Ensure that tests include cases that verify access control mechanisms and authentication protocols to prevent unauthorized access to sensitive data or functionality. * **Regular Security Audits:** Conduct regular security audits of the test suite to identify and address potential security vulnerabilities, such as insecure dependencies or outdated libraries. By following these code style and convention standards, development teams can create more robust, maintainable, and secure Mocha tests that contribute to the overall quality and reliability of the software.