包详细信息

arrange-act-assert

Llorx701MIT2.8.0

The lightweight "Act-Arrange-Assert" oriented testing framework

自述文件

arrange-act-assert

Zero-dependency lightweight Act-Arrange-Assert oriented testing tool.

Motivation

More detailed information here.

Documentation

The tool is pretty straightforward:

test("myTest", {
    ARRANGE?(after) {
        // Optional ARRANGE method
        // Receives an "after" callback as the first argument
        const myArrange = 100;
        return { myArrange };
    },
    ACT?({ myArrange }, after) {
        // Optional ACT method
        // Receives the ARRANGE return as the first argument
        // Receives an "after" callback as the second argument
        const myAct = myArrange + 1;
        return { myAct };
    },
    ASSERT?({ myAct }, { myArrange }, after) {
        // Optional ASSERT method
        // Receives the ACT return as the first argument
        // Receives the ARRANGE return as the second argument
        // Receives an "after" callback as the third argument
        myAct === 101;
        myArrange === 100;
    },
    ASSERTS?: {
        // Optional ASSERTS object just in case that you need to
        // check multiple results for the same action, to
        // avoid having a single ASSERT section with multiple assertions
        "should assert one thing"({ myAct }, { myArrange }, after) {
            // Receives the ACT return as the first argument
            // Receives the ARRANGE return as the second argument
            // Receives an "after" callback as the third argument
            myAct === 101;
            myArrange === 100;
        },
        "should assert another thing"({ myAct }, { myArrange }, after) {
            // Receives the ACT return as the first argument
            // Receives the ARRANGE return as the second argument
            // Receives an "after" callback as the third argument
            myAct === 101;
            myArrange === 100;
        }
    }
});

All three methods are optional, because maybe you don't need to ARRANGE anything, or maybe you only want to test that the ACT doesn't throw an error without any extra boilerplate.

You also have a describe method to group tests:

test.describe("myDescribe", (test) => {
    // The describe callback will receive a new `test` object that
    // should be used inside its callback
    test("myTest1", {...});
    test("myTest2", {...});
});

And you can call as much describes as you want inside another describes:

test.describe("myDescribe", (test) => {
    // Use the new "node:test" function
    test.describe("subdescribe 1", (test) => {
        // Use the new "node:test" function
        test("myTest1", {...});
        test("myTest2", {...});
    });
    test.describe("subdescribe 2", (test) => {
        // Use the new "node:test" function
        test("myTest1", {...});
        test("myTest2", {...});
    });
});

And you can add an after callback to any test that will run after all queued subtests are executed:

test.after(() => {
    console.log("after all tests");
});
test.describe("myDescribe 1", (test) => {
    test.after(() => {
        console.log("after myDescribe 1 tests");
    });
    test("myTest1", {...});
    test("myTest2", {...});
});
test.describe("myDescribe 2", (test) => {
    test.after(() => {
        console.log("after myDescribe 2 tests");
    });
    test("myTest1", {...});
    test("myTest2", {...});
});

While this tool forces you to have a single ARRANGE and ACT for each test to avoid sharing different arrangements and trying different actions on the same test, you can actually try to assert different parts of the actions, like so:

test("myTest", {
    ARRANGE() {
        const mockSpy = newMockSpy();
        const thing = newThing(mockSpy);
        // Return the mockSpy and the thing
        return { mockSpy, thing };
    },
    async ACT({ thing }) {
        // Do that thing that you want to test and return it
        // This receives as the first argument the ARRANGE return, so
        // just get the "thing" from it and run the method
        return await thing.doThat(); // (yes, methods can be asynchronous)
    },
    ASSERTS: {
        "should return a valid that"(that) {
            // Check that "doThat()" returns the expected result
            // This receives as the first argument the ACT return, so
            // just assert it
            Assert.strictEqual(that, 1);
        },
        "should call the getter one time"(_act, { mockSpy }) {
            // Check in the "mockSpy" that the callbacks were called
            // the necessary times while "doing that()"
            // This receives as the first argument the ACT return, so
            // discard it as we don't need it, but an ASSERT also
            // receives as the second argument the ARRANGE return, so
            // just assert the spy
            Assert.strictEqual(mockSpy.myCallback.getCalls().length, 1);
        }
    }
});

Both test() and describe() return a Promise<void> that will resolve when all child tests and describes finish. If any of the child tests or describes fail, the promise will reject with the first error.

Following the NodeJS test runner premise, the test function has a recursive test method (which points to itself) and a describe method so, depending on your liking, you can go all these ways:

import test from "arrange-act-assert";

test("myTest", {...});
test.test("myTest", {...});
test.describe("myDescribe", () => {...});

or even do this, as you like:

import { test, describe } from "arrange-act-assert";

test("myTest", {...});
describe("myDescribe", () => {...});
test.test("myTest", {...});
test.describe("myDescribe", () => {...});

To run the tests you just have to call in the cli:

npx aaa [OPTIONS]

The aaa cli command accepts these options:

  • --folder STRING: The path of the folder where the test files are located. Defaults to the current folder.
  • --parallel NUMBER: This tool runs test files in subprocesses (one new node process per test file). It will run these amounts of files in parallel. Set to 0 to run all the test files in the very same process, although is not recommended. Defaults to the amount of cores that the running computer has.
  • --include-files REGEX: The regex to apply to each full file path found to consider it a test file to run. You can set multiple regexes by setting this option multiple times. Defaults to (\\|\/|.*(\.|-|_))(test)(\.|(\.|-|\\|\/).*.)(cjs|mjs|js)$.
  • --exclude-files REGEX: The regex to apply to each full file path found to exclude it. Defaults to \/node_modules\/i.
  • --spawn-args-prefix PREFIX: It will launch the test files with this prefix in the arguments. You can set multiple prefixes by setting this option multiple times.
  • --clear-module-cache: When you run test files with parallel set to 0 (same process), this flag will delete the module cache so when the TestSuite requires a test file, NodeJS will re-require and re-evaluate the file and its dependencies instead of returning the cache, just in case that you need everything clean.
  • --coverage: Take coverage metrics.
  • --coverage-exclude REGEX: Regex to apply to each full file path found to exclude it. Defaults to \/node_modules\/i.
  • --coverage-no-branches: Do not show uncovered branches.
  • --disable-source-maps: When running a full test suite, source maps are enabled by default. Disable them with this option.
  • --snapshots-folder/--folder-snapshots: Folder to place the snapshot files. Defaults to ./snapshots. More info in the Snapshots section.
  • --snapshots-confirm/--confirm-snapshots: Confirm that the new snapshots created in the folder-snapshots are valid. More info in the Snapshots section.
  • --snapshots-review/--review-snapshots: Show all the snapshot outputs to check their values. More info in the Snapshots section.
  • --snapshots-regenerate/--regenerate-snapshots: Regenerate all snapshot files with new ones. More info in the Snapshots section.

Alternatively, you can import the TestSuite and run your tests programatically:

import { TestSuite, TestSuiteOptions, TestResult } from "arrange-act-assert";

const options:TestSuiteOptions = {...};
const suite = new TestSuite(options);
suite.run().then((result:TestResult) => {
    // suite.run() returns a Promise that will resolve with the result of
    // the executed tests
    if (!result.ok) {
        process.exitCode = 1;
    }
}).catch(e => {
    // Or crash if something fails really bad
    console.error(e);
    process.exitCode = 2;
});

The types of the option and result objects are like so:

// The options
type TestSuiteOptions = {
    parallel:number; // Same logic as the "--parallel" option
    folder:string; // Same logic as the "--folder" option
    include:RegExp[]; // Same logic as the "--include-files" option
    exclude:RegExp[]; // Same logic as the "--exclude-files" option
    prefix:string[]; // Same logic as the "--spawn-args-prefix" option
    clearModuleCache:boolean; // Same logic as the "--clear-module-cache" option
    // This is an interface that will receive the tests events to format them.
    // By default it will output the results in the stdout
    // Example: `https://github.com/Llorx/arrange-act-assert/blob/main/src/formatters/default.ts` search for "DefaultFormatter implements Formatter".
    formatter:Formatter;
    coverage:boolean; // Take coverage metrics
    coverageExclude:RegExp[]; // Same logic as the "--coverage-exclude" option
    coverageNoBranches:boolean; // Same logic as the "--coverage-no-branches" option
    disableSourceMaps:boolean; // Same logic as the "--disable-source-maps" option
    snapshotsFolder:string; // Folder to place the snapshots. Defaults to "./snapshots"
    confirmSnapshots:boolean; // To confirm the new snapshots, as stated in the "Snapshots" section
    reviewSnapshots:boolean; // To review all the snapshots, as stated in the "Snapshots" section
};

// The result
type TestResult = {
    files:string[]; // Test files ran
    runErrors:unknown[]; // Errors received wwhile trying to run the test files (outside of the tests)
    ok:boolean; // If everything went ok (no errors or failed tests anywhere)
    summary:Summary; // The result metrics
};
type Summary = {
    test:SummaryResult; // "test()" functions count
    assert:SummaryResult; // ASSERT() and individual ASSERTS:{...} count
    describe:SummaryResult; // "describe()" functions count
    total:SummaryResult; // Sum of everything up
};
type SummaryResult = { // Self-explanatory
    count:number;
    ok:number;
    error:number;
};

To assert errors, you can use the monad util:

import { test, monad } from "arrange-act-assert";

import { thing, asyncThing } from "./myThing";

test("Should throw an error when invalid arguments", {
    ACT() {
        return monad(() => thing(-1));
    },
    ASSERT(res) {
        res.should.error({
            message: "Argument must be >= 0"
        });
    }
});
test("Should throw an error when invalid arguments in async function", {
    async ACT() {
        return await monad(async () => await thing(-1));
    },
    ASSERT(res) {
        res.should.error({
            message: "Argument must be >= 0"
        });
    }
});

It will return a Monad object with the methods should.ok(VALUE), should.error(ERROR) and match({ ok:(value)=>void, error:(error)=>void }). The error validation is done using the NodeJS Assert.throws() error argument.

Snapshots

There's a snapshots system to easily assert method outputs that should return the same values between tests.

To ensure that snapshots are validated, a confirmation process is implemented: It will first save unvalidated snapshots and show the snapshot output for you to review manually. You must check that the outputs are valid and then the run the tests again with the --confirm-snapshots (cli) or confirmSnapshots: true (programmatically) option so the new snapshots are validated. Unvalidated snapshots are treated as non-existant for a normal run.

The snapshots are binary files serialized with the V8.serialize() method, so all types supported by this serialization method are valid. If you want to review them again, you must use the --review-snapshots (cli) or reviewSnapshots: true (programmatically) option.

If you want to regenerate a snapshot, you must delete the snapshot file from the filesystem manually and run again the snapshot confirmation process. You can also use the --regenerate-snapshots (cli) or regenerateSnapshots: true (programmatically) option. It will regenerate all the ran tests with unvalidated snapshots that must be confirmed again.

Snapshots are asserted using the deepStrictEqual() method.

The folder/file structure uses the describe, tests and snapshots descriptions to create the structure, for easy recognition of which test applies to which file.

Example:

import { test } from "arrange-act-assert";

import { ThingToTest } from "./ThingToTest";

test("Should return a valid thang", {
    ARRANGE() {
        return new ThingToTest();
    },
    SNAPSHOT(thing) { // This will snapshot what getThang() returns to a file and assert it on next runs
        return thing.getThang();
    },
    // Although SNAPSHOT may be considered an assertion itself, you can also ASSERT/ASSERTS the result if needed
    ASSERT(res) {...},
    ASSERTS: {
        "assert 1"(res) {...},
        "assert 2"(res) {...}
    }
});
test("Should return multiple thangs", {
    ARRANGE() {
        return new ThingToTest();
    },
    ACT(thing) {
        return thing.getThangs();
    },
    // If, instead of the full ACT, you need to snapshot different parts of an ACT individually
    // you can create multiple snapshots with this format:
    SNAPSHOTS: {
        "should be oneThang"(res) {
            return res.oneThang;
        },
        "should be twoThang"(res) {
            return res.twoThang;
        }
    },
    // And you can also ASSERT/ASSERTS the ACT result if needed
    ASSERT(res) {...},
    ASSERTS: {
        "assert 1"(res) {...},
        "assert 2"(res) {...}
    }
});