Codi Test Framework

Common errors

• ReferenceError: test is not defined

  cause Attempting to use `test` (or `describe`, `expect`) without importing it, or in a CommonJS module that doesn't support ESM imports.
  fix Ensure your test file is an ES Module (`.mjs` or `type: "module"` in `package.json`) and you've added `import { test } from 'codi-test-framework';`.

• AssertionError: Expected 5 but got 3

  cause A test assertion failed because the actual value did not match the expected value.
  fix Review the logic of your test case and the expected outcome. Ensure the code under test behaves as intended and that your assertion `expect(actual).toBe(expected)` has the correct `expected` value.

• TypeError: expect(...).toEquals is not a function

  cause Attempting to use a deprecated or incorrect assertion method. The `toEquals` method was removed in version 1.0.0.
  fix Update assertion method to `expect(...).toEqual(...)` for deep object comparison or `expect(...).toBe(...)` for primitive value comparison.

Warnings

• breaking The `expect` API underwent a significant breaking change in version 1.0.0. Methods like `equals` were replaced with more descriptive `toBe` and `toEqual` to align with common testing patterns.
  Fix: Update assertion calls from `expect(a).equals(b)` to `expect(a).toBe(b)` for primitive comparisons, or `expect(a).toEqual(b)` for deep object comparisons.
• breaking Asynchronous tests in versions prior to 0.8.0 relied on a `done` callback. This callback mechanism was removed in favor of native `async/await` support for clearer asynchronous test handling.
  Fix: Refactor asynchronous tests to return a Promise or use the `async` keyword with `await` expressions. Remove any `done()` calls.
• gotcha When running tests in non-isolated environments (e.g., directly in a global script without a proper test runner), the `test`, `expect`, and `describe` functions might inadvertently pollute the global scope, leading to unexpected conflicts.
  Fix: Always run Codi Test Framework tests within a designated test runner environment or ensure that your test files are executed in modules where imports are scoped locally. Avoid global execution contexts for tests.
• deprecated The `beforeEach` and `afterEach` hooks for setting up and tearing down test environments were deprecated in version 1.0.20 due to inconsistent behavior with asynchronous operations.
  Fix: Migrate setup/teardown logic directly into individual test cases or use module-level `beforeAll`/`afterAll` hooks if synchronous and suitable. Consider helper functions for repetitive setup.

Install

• npm install codi-test-framework npm
• yarn add codi-test-framework yarn
• pnpm add codi-test-framework pnpm

Imports

• test
  wrong:

  const { test } = require('codi-test-framework');

  correct:

  import { test } from 'codi-test-framework';

  The framework primarily uses ES Modules. CommonJS require() is not supported since v1.0.
• expect
  wrong:

  import expect from 'codi-test-framework';

  correct:

  import { expect } from 'codi-test-framework';

  The 'expect' assertion utility is a named export, not a default export.
• describe
  wrong:

  import * as Codi from 'codi-test-framework'; Codi.describe(() => {});

  correct:

  import { describe } from 'codi-test-framework';

  For clarity and tree-shaking, it's recommended to import individual functions rather than the entire module namespace.

Quickstart

This quickstart demonstrates defining a test suite, asynchronous tests, and using basic assertions.

import { test, expect, describe } from 'codi-test-framework';

describe('Math Operations', () => {
  test('should add two numbers correctly', () => {
    const result = 1 + 2;
    expect(result).toBe(3);
  });

  test('should handle asynchronous operations', async () => {
    const fetchData = () => Promise.resolve({ data: 'hello' });
    const response = await fetchData();
    expect(response.data).toBe('hello');
  });

  test('should multiply numbers', () => {
    expect(2 * 3).toBe(6);
    expect(5 * 0).toBe(0);
  });
});

// Simulate a test runner executing these tests
console.log('Running tests with Codi Test Framework...');
// In a real scenario, these tests would be discovered and executed by a runner.
// For this quickstart, assume the 'describe' and 'test' calls register tests internally.
console.log('Tests completed. (Output depends on actual runner implementation)');