Javascript Testing Expert

JavaScript testing expert

⚠️ Scope: Testing functions and components, not black-box e2e.

🏅 Main objectives: use tests as a way to...

1. uncover hard to detect bugs
2. document how to use the code
3. avoid regressions
4. challenge the code

🔧 Recommended tooling for Optique: node:test, node:assert/strict, and fast-check. ✅ Do try to install only missing and relevant tooling. ✅ Do recommend Node's built-in test libraries for Optique tests. ✅ Do adapt yourself to missing tools.

File and code layout

✅ Do mimic the existing test structure of the project when adding new tests

✅ Do use one test file per code file

👍 Prefer using .test.ts extension (e.g., fileName.ts → fileName.test.ts) and colocating tests with the source file, matching the project's existing examples

✅ Do put it within describe, when using it

👍 Prefer it over test

✅ Do name the describe with the name of the function being tested

✅ Do use a dedicated describe for each function being tested

✅ Do start it names with "should"; keep them clear, concise, and readable as a sentence implicitly prefixed by "it"

✅ Do start with simple and documenting tests

✅ Do continue with advanced tests looking for edge-cases

❌ Don't explicitly separate simple from advanced tests; just put them in the right order

✅ Do put helper functions specific to the file after all the describes just below a comment // Helpers stating the beginning of the helpers tailored for this file

Core guidelines

✅ Do follow the AAA pattern and make it visible in the test

it('should...', () => {
  // Arrange
  code;

  // Act
  code;

  // Assert
  code;
});

✅ Do keep tests focused, try to assert on one precise aspect

✅ Do keep tests simple

👎 Avoid complex logic in tests or its helpers

❌ Don't test internal details

👍 Prefer stubs over mocks, the first one provides an alternate implementation, the second one helps to assert on calls being done or not Why? Often, asserting the number of calls is not something critical for the user of the function but purely an internal detail

❌ Don't rely on network call, stub it with msw

✅ Do reset globals and mocks in beforeEach if any it plays with mocks or spies or alter globals Prefer explicit cleanup that works across Node.js, Deno, and Bun.

👍 Prefer realistic data for documentation-like tests Eg.: use real names if you have to build instances of users

❌ Don't overuse snapshot tests; only snapshot things when the "what is expected to be seen in the snapshot" is clear Why? Snapshots tests tend to capture too many details in the snapshot, making them hard to update given future reader is lost on what was the real thing being tested

👍 Prefer snapshots when shape and structure are important (component hierarchy, attributes, non-regression on output structure)

👍 Prefer screenshots when final render is important (visual styling, layout)

✅ Do warn developer when the code under tests requires too many parameters and/or too many mocks/stubs to be forged (more than 10) Why? Code being hardly testable is often a code smell pinpointing an API having to be changed. Code is harder to evolve, harder to reason about and often handling too many responsibilities. Recommend the single-responsibility principle (SRP)

✅ Do extract helper functions only when repetition is substantial or expresses a distinct behavioral intent

✅ Do keep small repeated assertion patterns inline in Optique tests unless a helper would clarify behavior

✅ Do group substantial shared logic under a function having a clear and explicit name, follow SRP for these helpers Eg.: avoid functions with many optional parameters or several responsibilities

❌ Don't write a big prepare function re-used by all tests in their act part, but make the name clearer and eventually split it into multiple functions

✅ Do make sure your test breaks if you drop the thing supposed to make it pass Eg.: When your test says "should do X when Y" make sure that if you don't have Y it fails before keeping it.

👎 Avoid writing tests with entities specifying hardcoded values on unused fields

Example of test content

const user: User = {
  name: 'Paul', // unused
  birthday: '2010-02-03',
};
const age = computeAge(user);
//...

👍 Prefer leveraging fast-check with node:test

import assert from "node:assert/strict";
import * as fc from "fast-check";
import { describe, it } from "node:test";

describe('computeAge', () => {
  it('should compute a positive age', () => {
    fc.assert(
      fc.property(fc.string(), (name) => {
        const user: User = {
          name, // unused
          birthday: '2010-02-03',
        };

        const age = computeAge(user, new Date('2020-02-03'));

        assert.ok(age > 0);
      }),
    );
  });
});

👍 Prefer leveraging fast-check for property-based tests

👎 Avoid writing tests depending on unstable values Eg.: in the example above computeAge depends on the current date Remark: same for locales and plenty other platform dependent values

👍 Prefer passing today as an explicit dependency when the API allows it

👍 Prefer controlling today with a generated date in a fast-check property Why? You check the code against one new today at each run, but if it happens to fail one day you will be reported with the exact date causing the problem

fc.assert(
  fc.property(
    fc.date({ min: new Date('2010-02-04'), noInvalidDate: true }),
    (today) => {
      const user: User = {
        name: "Paul", // unused
        birthday: '2010-02-03',
      };

      const age = computeAge(user, today);

      assert.ok(age >= 0);
    },
  ),
);

👎 Avoid writing tests depending on random values or entities

👍 Prefer controlling randomly generated values by relying on fast-check

✅ Do use property based tests for any test with a notion of always or never Eg.: name being "should always do x when y" or "should never do x when y" Remark: consider these tests as advanced and put them after the documentation tests and not with them

👍 Prefer using property based testing for edge case detection instead of writing all cases one by one

❌ Don't try to test 100% of the algorithm cases using property-based testing Why? Property-based testing and example-based testing are complementary. Property-based tests are excellent for uncovering edge cases and validating general properties, while example-based tests provide clear documentation and cover specific important scenarios. Use both approaches together for comprehensive test coverage.

// for all a, b, c strings
// b is a substring of a + b + c
it('should detect the substring', () => {
  fc.assert(
    fc.property(fc.string(), fc.string(), fc.string(), (a, b, c) => {
      // Arrange
      const text = a + b + c;
      const pattern = b;

      // Act
      const result = isSubstring(text, pattern);

      // Assert
      assert.ok(result);
    }),
  );
});

✅ Do extract complex logic from components into dedicated and testable functions

❌ Don't test trivial component logic that has zero complexity

👍 Prefer testing the DOM structure and user interactions when using testing-library

👍 Prefer testing the visual display and user interactions when using browser testing

👍 Prefer querying by accessible attributes and user-visible text by relying on getByRole, getByLabelText, getByText over getByTestId whenever possible for testing-library and browser testing

✅ Do ensure non visual regression of Design System components and more generally visual components by leveraging screenshot tests in browser when available ✅ Do fallback to snapshot tests capturing the DOM structure if screenshot tests cannot be ran

Guidelines for properties

This section assumes the context is property-based tests.

⚠️ Important: In Optique tests, use fc.assert with fc.property or fc.asyncProperty directly.

❌ Don't generate inputs directly The risk being that you may end up rewriting the code being tested in the test

✅ Do construct values to build some inputs where you know the expected outcome

❌ Don't expect the returned value in details, in many cases you won't have enough details to be able to assert the full value

✅ Do expect some aspects and characteristics of the returned value

❌ NEVER specify any maxLength on an arbitrary if it is not a requirement of the algorithm 👍 Prefer specifying a size: '-1' if you feel that the algorithm will take very long on large inputs (by default fast-check generates up to 10 items, so only use size when clearly required) Eg.: No fc.string({maxLength: 5}) or fc.array(arb, {maxLength: 8}) except when it is a strict requirement

❌ NEVER specify any constraint on an arbitrary if it is not a requirement of the arbitrary, use defaults as much as possible Eg.: if the algorithm should accept any integer just ask an integer without specifying any min and max

👎 Avoid overusing .filter and fc.pre Why? They slow down the generation of values by dropping some generated ones

👍 Prefer using options provided by arbitraries to directly generate valid values Eg.: use fc.string({ minLength: 2 }) instead of fc.string().filter(s => s.length >= 2) Eg.: use fc.integer({ min: 1 }) instead of fc.integer().filter(n => n >= 1), or use fc.nat() instead of fc.integer().filter(n => n >= 0)

👍 Prefer using map over filter when a map trick can avoid filtering Eg.: use fc.nat().map(n => n * 2) for even numbers Eg.: use fc.tuple(fc.string(), fc.string()).map(([start, end]) => start + 'A' + end) for strings always having an 'A' character

👍 Prefer bigint type over number type for integer computations used within predicates when there is a risk of overflow (eg.: when running pow, multiply.. on generated values)

Some classical properties:

1. Characteristics independent of the inputs. Eg.: for any floating point number d, Math.floor(d) is an integer. for any integer n, Math.abs(n) ≥ 0
2. Characteristics derived from the inputs. Eg.: for any a and b integers, the average of a and b is between a and b. for any n, the product of all numbers in the prime factor decomposition of n equals n. for any array of data, sorted(data) and data contains the same elements. for any n1, n2 integers such that n1 != n2, romanString(n1) != romanString(n2). for any floating point number d, Math.floor(d) is an integer such as d-1 ≤ Math.floor(d) ≤ d
3. Restricted set of inputs with useful characteristics. Eg.: for any array data with no duplicates, the result of removing duplicates from data is data itself. for any a, b and c strings, the concatenation of a, b and c always contains b. for any prime number p, its decomposition into prime factors is itself
4. Characteristics on combination of functions. Eg.: zipping then unzipping a file should result in the original file. lcm(a,b) times gcd(a,b) must be equal to a times b
5. Comparison with a simpler implementation. Eg.: c is contained inside sorted array data for binary search is equivalent to c is contained inside data for linear search

Guidelines for race conditions

✅ Do write tests checking for race conditions and exploring resolution order when an algorithm accepts asynchronous functions as input

✅ Do leverage fast-check and its fc.scheduler() arbitrary, together with s.scheduleFunction and s.waitFor, to explore ordering deterministically

Turn:

it('should resolve in call order', async () => {
  // Arrange
  const seenAnswers = [];
  const call = (v) => Promise.resolve(v);

  // Act
  // `queue` is a helper that serializes async calls.
  const queued = queue(call);
  await Promise.all([queued(1).then((v) => seenAnswers.push(v)), queued(2).then((v) => seenAnswers.push(v))]);

  // Assert
  assert.deepEqual(seenAnswers, [1, 2]);
});

Into:

it('should resolve in call order', async () => {
  await fc.assert(
    fc.asyncProperty(fc.scheduler(), async (s) => {
      // Arrange
      const seenAnswers = [];
      const call = (v) => Promise.resolve(v);

      // Act
      // `queue` is a helper that serializes scheduled async calls.
      const queued = queue(s.scheduleFunction(call));
      await s.waitFor(
        Promise.all([queued(1).then((v) => seenAnswers.push(v)), queued(2).then((v) => seenAnswers.push(v))]),
      );

      // Assert
      assert.deepEqual(seenAnswers, [1, 2]);
    }),
  );
});

Recommendation for faker users

If using faker to fake data, we recommend wiring any fake data generation within fast-check by leveraging this code snippet:

// Source: https://fast-check.dev/blog/2024/07/18/integrating-faker-with-fast-check/
import { Faker, Randomizer, base } from '@faker-js/faker';
import fc from 'fast-check';

class FakerBuilder<TValue> extends fc.Arbitrary<TValue> {
  constructor(private readonly generator: (faker: Faker) => TValue) {
    super();
  }
  generate(mrng: fc.Random, biasFactor: number | undefined): fc.Value<TValue> {
    const randomizer: Randomizer = {
      next: (): number => mrng.nextDouble(),
      seed: () => {}, // no-op, no support for updates of the seed, could even throw
    };
    const customFaker = new Faker({ locale: base, randomizer });
    return new fc.Value(this.generator(customFaker), undefined);
  }
  canShrinkWithoutContext(value: unknown): value is TValue {
    return false;
  }
  shrink(value: TValue, context: unknown): fc.Stream<fc.Value<TValue>> {
    return fc.Stream.nil();
  }
}

function fakerToArb<TValue>(generator: (faker: Faker) => TValue): fc.Arbitrary<TValue> {
  return new FakerBuilder(generator);
}

Example of usage

fc.assert(
  fc.property(
    fakerToArb((faker) => faker.person.firstName),
    fakerToArb((faker) => faker.person.lastName),
    (firstName, lastName) => {
      // code
    },
  ),
);

Using fast-check with node:test

Example 1.

import * as fc from "fast-check";
import { it } from "node:test";

it("...", () => {
  fc.assert(
    fc.property(fc.string(), (value) => {
      //...
    }),
  );
});

Example 2.

import * as fc from "fast-check";
import { it } from "node:test";

it("...", () => {
  fc.assert(
    fc.property(...arbitraries, (...values) => {
      //...
    }),
  );
});

Example 3. If the predicate is asynchronous, the property has to be instantiated via asyncProperty and assert has to be awaited.

import * as fc from "fast-check";
import { it } from "node:test";

it("...", async () => {
  await fc.assert(
    fc.asyncProperty(...arbitraries, async (...values) => {
      //...
    }),
  );
});