setup function instead of beforeEach in unit & service level tests

[stalniy]

Summary

This RFC proposes a shift in how testing code is structured.
Instead of relying on beforeEach blocks and shared mutable variables across multiple tests, it suggests adopting a setup function pattern. This approach promotes clearer test boundaries, improves readability, and reduces hidden dependencies between tests

Motivation

beforeEach + variables add a lot stuff at the beginning of tests, usually this is not easy to understand code with type casting and spies which developer need to reset in afterEach. Some tests may require a bit different setup from the one defined in beforeEach which makes this logic more complicated.

setup function aims to encapsulate this logic into a function that can be called manually in every tests with test specific parameters

Examples

Current one

import { X509Certificate } from "crypto";
import { setTimeout } from "timers/promises";

import { CertificateValidator, CertificateValidatorIntrumentation, CertValidationResultError } from "../../src/services/CertificateValidator";
import { ProviderService } from "../../src/services/ProviderService";
import { createX509CertPair } from "../seeders/createX509CertPair";

describe(CertificateValidator.name, () => {
  const ONE_MINUTE = 60 * 1000;
  let validator: CertificateValidator;
  let getCertificate: ProviderService["getCertificate"];
  let getNow = jest.fn(() => Date.now());

  beforeEach(() => {
     getCertificate = jest.fn();
     validator = new CertificateValidator(getNow, { getCertificate }  as ProviderService);
  });

  it('returns "unknownCertificate" error result if provider certificate cannot be found', async () => {
    const { cert } = createX509CertPair({
      validFrom: new Date(),
      validTo: new Date(Date.now() + ONE_MINUTE),
      commonName: "akash1rk090a6mq9gvm0h6ljf8kz8mrxglwwxsk4srxh",
      serialNumber: "177831BE7F249E66"
    });
    getCertificate.mockImplementation(() => Promise.resolve(null));

    const result = await validator.validate(cert, "mainnet", "provider") as CertValidationResultError;

    expect(result.ok).toBe(false);
    expect(result.code).toBe("unknownCertificate");
    expect(getCertificate).toHaveBeenCalledWith("mainnet", "provider", cert.serialNumber);
  });
});

Suggested one

describe(CertificateValidator.name, () => {
  const ONE_MINUTE = 60 * 1000;

  it('returns "unknownCertificate" error result if provider certificate cannot be found', async () => {
    const { cert } = createX509CertPair({
      validFrom: new Date(),
      validTo: new Date(Date.now() + ONE_MINUTE),
      commonName: "akash1rk090a6mq9gvm0h6ljf8kz8mrxglwwxsk4srxh",
      serialNumber: "177831BE7F249E66"
    });
    const getCertificate = jest.fn(() => Promise.resolve(null));
    const validator = setup({ getCertificate });      // <---------------------------------------------

    const result = (await validator.validate(cert, "mainnet", "provider")) as CertValidationResultError;

    expect(result.ok).toBe(false);
    expect(result.code).toBe("unknownCertificate");
    expect(getCertificate).toHaveBeenCalledWith("mainnet", "provider", cert.serialNumber);
  });  

  function setup(params?: TestInput) {
    return new CertificateValidator(
      () => params?.now ?? Date.now(),
      {
        getCertificate: params?.getCertificate || jest.fn()
      } as ProviderService,
      params?.instrumentation
    );
  }

  interface TestInput {
    now?: number;
    getCertificate?: ProviderService["getCertificate"];
    instrumentation?: CertificateValidatorIntrumentation;
  }
});

Main benefits

• gives more control on test level, every test can adapt testing env/object by passing parameters to setup function
• no need to clear spies, as they live and die in scope of a single test
• no shared state across tests which developer may forget to clean what will result in flakiness
• easier to discover for others. When we have setup function with parameters, IDE helps to understand what developer can pass, so he may add a new test without even reading setup function
• setup function at the bottom of test suite doesn't force developers to read implementation details, they can first look at test on high level and only if they need to change or understand setup function, they will scroll at the bottom

Drawbacks

• more verbose, need additional interface with TestInput

Recommendations of writing setup function

1. Use it to configure object under testing. Do as little side effects as possible. It's main purpose is to construct object under testing, by mocking all required dependencies
2. Allow overrides via setup single function input parameter
3. Consider skipping setup function if creation of object under testing is super easy
4. Consider using withSetup to define cleanup logic:

describe('Entity', () => {

  const setup = withSetup((input: {
    certificatePair: { public: string; private: string }
  }) => {
     const server = startServerWithCertificate(input.certificatePair);
     return {
       teardown: () => server.close();
       server,
     };
  });
});

where withSetup looks like this:

type Teardown = (() => void | Promise<void>);
function withSetup<T>(setup: (input: T) => { teardown?: Teardown } | Promise<{ teardown?: Teardown }>) {
  let teardown: Teardown | undefined;

  afterEach(async () => {
    await teardown?.();
    teardown = undefined;
  });

  return (input: T) => {
     const result = setup(input);
     if (isPromise(result)) {
      return result.then(result => teardown = result.teardown);
     }
      
     teardown = result.teardown;
     return result;
  };
}

[stalniy]

Agreed to try to write cursor rule in mdc format to write test like this