@premiss/api NPM

Premiss

Premiss is a testing library written in TypeScript to provide an API for testing code. It is not a framework, therefore it does not provide a cli, runner, assertions, test doubles, or other integrations. The library provides an interface to represent the “Arrange-Act-Assert” testing pattern, with the addition of “Annul” for what should be the rare case you need to clean up.

Motivation

There are two main reasons for this project. The first is most of what’s out there for testing are frameworks and I try to avoid frameworks. The other is an intent to keep a single test cohesive through constraining the shape of the test so that it has a single reason to exist. And as a side bonus, I used this as an opportunity to use the TCR workflow to build this.

Example

String Calcluator Kata Example

API Reference

The API has a single entry point, the verify function. The verify function takes a proof interface, evaluates it, and returns a proof examination result. The result contains the outcome of the examination along with timings. The examination outcome indicates if the proof passed or failed and when failed the step the failure occurred at. Only the assert method signature is required.

Implementations

A class implementation of the proof interface

import { Proof } from "@premiss/api";

export class YourAmazingTest implements Proof
{
    public async arrange(): Promise<void>
    {
        // Set up for winning
    }

    public async act(): Promise<void>
    {
        // Execute the winning
    }

    public async assert(): Promise<void>
    {
        // Count your winnings
    }

    public async annul(): Promise<void>
    {
        // Give you winnings away?
        // No really why do you have to clean up?
    }
}

An object literal implementation of the proof interface

import { Proof, ProofStep } from "@premiss/api";

export const YourAmazingTest =
    {
        [ProofStep.arrange]: async (): Promise<void> =>
        {
            // Set up for winning
        },

        [ProofStep.act]: async (): Promise<void> =>
        {
            // Execute the winning
        },

        [ProofStep.assert]: async (): Promise<void> =>
        {
            // Count your winnings
        },

        [ProofStep.annul]: async (): Promise<void> =>
        {
            // Give your winnings away?
            // No really why do you have to clean up?
        }
    }

The minimum proof interface implementation

import { Proof } from "@premiss/api";

export class YourAmazingTest implements Proof
{
    public async assert(): Promise<void>
    {
        // Count your winnings
    }
}

Running a test

import { verify } from "@premiss/api";

const myTestResult = (async (): Promise<TimedResult<ProofExaminationResult>> => {
    // new up your test
    const proof = new YourAmazingTest();
    // run your test
    return await verify(proof);
})();
// do what you want with your test results

Test result variations

A passing test result with no annul defined

{
    elapsedNanoseconds: 1292900n,
    result: 
    {
        examinationOutcome: ExaminationOutcomeObserved.passed,
        examinationResultSet: 
        {
            arrange: 
            {
                elapsedNanoseconds: 132401n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            act: 
            {
                elapsedNanoseconds: 568600n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            assert: 
            {
                elapsedNanoseconds: 65301n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            annul: 
            {
                elapsedNanoseconds: 0n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeUnobserved.skipped
                }
            },
            elapsedNanoseconds: 766302n
        }
    }
}

A failing test result with successful annul step

{
    elapsedNanoseconds: 1422101n,
    result: 
    {
        examinationOutcome: ExaminationOutcomeObserved.failed,
        examinationError: 
        {
            error:
            {
                generatedMessage: false,
                code: "ERR_ASSERTION",
                actual: 1003,
                expected: 2,
                operator: "strictEqual",
                message: "The assertion error message"
            },
            proofStep: ProofStep.assert
        },
        examinationResultSet: 
        {
            arrange: 
            {
                elapsedNanoseconds: 132401n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            act: 
            {
                elapsedNanoseconds: 568600n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            assert: 
            {
                elapsedNanoseconds: 65301n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.failed,
                    examinationError: 
                    {
                        error:
                        {
                            generatedMessage: false,
                            code: "ERR_ASSERTION",
                            actual: 1003,
                            expected: 2,
                            operator: "strictEqual",
                            message: "The assertion error message"
                        },
                        proofStep: ProofStep.assert
                    }
                }
            },
            annul: 
            {
                elapsedNanoseconds: 129201n,
                result: 
                {
                    examinationOutcome: ExaminationOutcomeObserved.passed
                }
            },
            elapsedNanoseconds: 895503n
        }
    }
}