bingo-stratum-testers

Test utilities for Stratum Blocks and Presets. 🧑‍🔧

npm

npm i -D bingo-stratum-testers

pnpm

pnpm add -D bingo-stratum-testers

yarn

yarn add -D bingo-stratum-testers

The separate bingo-stratum-testers package includes testing utilities that run Blocks and Presets in fully virtualized environments. This is intended for use in unit tests that should mock out all Stratum Contexts.

Tip

bingo-stratum-testers is test-framework-agnostic. You can use it with any typical testing framework, including Jest and Vitest.

Stratum generally reuses existing Bingo tester APIs when possible:

• Base options can be prepared using the same API as Templates: bingo-testers > testOptions.
• Templates are standard Bingo templates, and so can be provided to bingo-testers > testTemplate.

Other Stratum constructs behave differently:

• Blocks: may be tested directly with testBlock and testIntake
• Presets: do not have a corresponding API, as they can be tested by passing the preset option to a Template that includes them

testBlock

For Blocks, a testBlocks function is exported that is analogous to produceBlock. It takes in similar arguments:

1. block (required): a Block
2. settings (optional): any properties from a Block Context

For example, this test asserts that an nvmrc Block creates an .nvmrc file with content "20.12.2":

import { testBlock } from "create-testers";
import { describe, expect, it } from "vitest";

import { blockNvmrc } from "./blockNvmrc";

describe("blockNvmrc", () => {
  it("returns an .nvmrc", () => {
    const actual = testBlock(blockNvmrc);

    expect(actual).toEqual({
      files: { ".nvmrc": "20.12.2" },
    });
  });
});

As with produceBlock, testBlock returns the Block’s Creation. Both Direct Creations and Indirect Creations will be present.

settings and all its properties are optional. However, some properties will cause testBlock to throw an error if they’re not provided and the Block attempts to use them:

• options: each property throws an error if accessed at all

addons

Block Addons may be provided under addons.

For example, this test asserts that a Prettier block adds a useTabs arg to its output ".prettierrc.json":

import { testBlock } from "create-testers";
import { describe, expect, expect, it } from "vitest";
import { z } from "zod";

import { base } from "./base";

const blockPrettier = base.createBlock({
  addons: {
    useTabs: z.boolean(),
  },
  produce({ addons }) {
    return {
      files: {
        ".prettierrc.json": JSON.stringify({
          $schema: "http://json.schemastore.org/prettierrc",
          useTabs: addons.useTabs,
        }),
      },
    };
  },
});

describe("blockPrettier", () => {
  it("creates a .prettierrc.json when provided options", () => {
    const actual = testBlock(blockPrettier, {
      addons: {
        config: {
          useTabs: true,
        },
      },
    });

    expect(actual).toEqual({
      files: {
        ".prettierrc.json": JSON.stringify({
          $schema: "http://json.schemastore.org/prettierrc",
          useTabs: true,
        }),
      },
    });
  });
});

options

Base Options may be provided under options, as well as preset: string.

For example, this test asserts that a README.md uses the title defined under options:

import { testBlock } from "create-testers";
import { describe, expect, it } from "vitest";

import { base } from "./base";

const blockReadme = base.createBlock({
  produce({ options }) {
    return {
      files: {
        "README.md": `# ${options.title} (${options.preset})`,
      },
    };
  },
});

describe("blockDocs", () => {
  it("uses options.name for the README.md title", () => {
    const actual = testBlock(blockReadme, {
      options: {
        preset: "test",
        title: "My Project",
      },
    });

    expect(actual).toEqual({
      files: {
        "README.md": `# My Project (test)`,
      },
    });
  });
});

testIntake

For Blocks with intake, a testIntake function is exported that is analogous to testOptions. It takes in two arguments:

1. block (required): a Block
2. settings (optional): an Intake Context

files

A bingo-fs directory may be provided under files. Files in the directory must be stored as [string, CreatedFileMetatdata?] tuples

For example, this test asserts that an nvmrc Block intakes a version Addon from an existing .nvmrc file on disk:

import { testIntake } from "create-testers";
import { describe, expect, it } from "vitest";

import { blockNvmrc } from "./blockNvmrc";

describe("intake", () => {
  it("returns an .nvmrc", () => {
    const version = "20.12.2";

    const actual = testIntake(blockNvmrc, {
      files: {
        ".nvmrc": [`${version}\n`],
      },
    });

    expect(actual).toEqual({ version });
  });
});