setup function instead of beforeEach in unit & service level tests

[stalniy]

Summary

This RFC processes to change the approach of writing and structuring testing code. Instead of using beforeEach with variables that are shared across different tests, it suggests to replace this pattern with setup function

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