Skip to main content

Betterer Test

BettererTestOptions#

Whenever you create a BettererTest you can pass an options object. It will be validated by and turned into a BettererTestConfig.

There is a lot of power (and therefore complexity) in this options object. The types should hopefully guide you towards a useful test, but feel free to reach out if you need help!

type BettererTestOptions<DeserialisedType = unknown, SerialisedType = DeserialisedType, DiffType = null> =  | BettererTestOptionsBasic  | BettererTestOptionsComplex<DeserialisedType, SerialisedType, DiffType>;

Generics#

DeserialisedType (default unknown)#

This type describes the basic result type of a test. For simple tests this can just be a number or other primitive. More complex types can be used, but will possibly require implementing differ, serialiser, and printer.

SerialisedType (default DeserialisedType)#

This type describes the serialised type of a test result. Some complex result types (like BettererFileTestResult) cannot be directly serialised to JSON, so it must be converted to a serailisable form.

DiffType (default null)#

This type describes the diff between two results. Some complex result types (like BettererFileTestResult) cannot be compared directly, so a diff can be constructed to better express the comparison.

BettererTestOptionsBasic#

The least complex version of a BettererTest operates on simple numbers and can be defined with just a few properties.

type BettererTestOptionsBasic = {  constraint: BettererTestConstraint<number>;  test: BettererTestFunction<number>;  goal?: BettererTestGoal<number> | number;  deadline?: Date | string;};

Properties#

constraint: BettererTestConstraint#

The constraint function for the test.

test: BettererTestFunction#

The function that runs the actual test.

goal: BettererTestGoal | number#

The goal function or value for the test.

deadline: Date | string#

The deadline for the test.

BettererTestOptionsComplex#

For a more complex version BettererTest that operates on more complex objects, you may need to define more complex behaviour.

type BettererTestOptionsComplex<DeserialisedType, SerialisedType, DiffType> = {  constraint: BettererTestConstraint<DeserialisedType>;  test: BettererTestFunction<DeserialisedType>;  differ: BettererDiffer<DeserialisedType, DiffType>;  printer?: BettererPrinter<SerialisedType>;  progress?: BettererProgress<DeserialisedType>;  serialiser: BettererSerialiser<DeserialisedType, SerialisedType>;  goal: BettererTestGoal<DeserialisedType> | DeserialisedType;  deadline?: Date | string;};

Properties#

constraint: BettererTestConstraint#

The constraint function for the test.

test: BettererTestFunction#

The function that runs the actual test.

differ: BettererDiffer#

The function that compares two test results.

printer: BettererPrinter#

The function that converts a serialised test result to the string that will be saved in the test results file

progress: BettererProgress#

The function that converts a test result to a number value that represents the progress towards the goal.

serialiser: BettererSerialiser#

The functions that serialises and deserialises a test result between the DeserialisedType and SerialisedType.

goal: BettererTestGoal | number#

The goal function or value for the test.

deadline: Date | string#

The deadline for the test.

BettererTest#

The interface to the Betterer test system.

class BettererTest {  get config(): BettererTestConfig;  get isOnly(): boolean;  get isSkipped(): boolean;  constructor(options: BettererTestOptions);  only(): this;  skip(): this;}

Constructor#

Args:

Usage#

import { BettererTest } from '@betterer/betterer';
const test = new BettererTest({ ... });

Properties#

config: BettererTestConfig#

The complete configuration for the test.

isOnly: boolean#

Calling only() will mark this as true. If this is true all other tests will be skipped.

isSkipped: boolean#

Calling skip() will mark this as true. If this is true this test will be skipped.

Methods#

only()#

Run only this test. All other tests will be marked as skipped.

Returns: BettererTest

skip()#

Skip this test.

Returns: BettererTest

BettererTestConfig#

The validated configuration for a BettererTest

type BettererTestConfig<DeserialisedType, SerialisedType, DiffType> = {  constraint: BettererTestConstraint<DeserialisedType>;  deadline: number;  goal: BettererTestGoal<DeserialisedType>;  test: BettererTestFunction<DeserialisedType>;  differ: BettererDiffer<DeserialisedType, DiffType>;  printer: BettererPrinter<SerialisedType>;  progress: BettererProgress<DeserialisedType> | null;  serialiser: BettererSerialiser<DeserialisedType, SerialisedType>;  type: BettererTestType;};

BettererTestConstraint#

A function that checks if a test result is better, worse, or the same.

type BettererTestConstraint<DeserialisedType> = (  result: DeserialisedType,  expected: DeserialisedType) => Promise<BettererConstraintResult> | BettererConstraintResult;

Args:

Returns: Promise<BettererConstraintResult> | BettererConstraintResult

BettererTestFunction#

A function that runs the actual test.

type BettererTestFunction<DeserialisedType> = (run: BettererRun) => Promise<DeserialisedType> | DeserialisedType;

Args:

Returns: Promise<DeserialisedType> | DeserialisedType

BettererTestGoal#

A function that returns whether the test has met its goal.

type BettererTestGoal<DeserialisedType> = (result: DeserialisedType) => Promise<boolean> | boolean;

Args:

Returns: Promise<boolean> | boolean

BettererDiffer#

A function that compares two test results.

type BettererDiffer<DeserialisedType, DiffType> = (  expected: DeserialisedType,  result: DeserialisedType) => BettererDiff<DeserialisedType, DiffType>;

Args:

Returns: BettererDiff<DeserialisedType, DiffType>

BettererDiff#

A object that describes the diff between two results.

type BettererDiff<DeserialisedType = unknown, DiffType = null> = {  expected: DeserialisedType;  result: DeserialisedType;  diff: DiffType;  log: (logger: BettererLogger) => Promise<void>;};

Properties#

expected: DeserialisedType#

The expected result.

result: DeserialisedType#

The current result.

diff: DiffType#

The difference between expected and result.

Methods#

log()#

A logging hook for the diff. This is called by the reporter whenever a test becomes worse.

Args:

Returns: Promise<void>

BettererSerialiser#

The functions that serialises and deserialises a test result between the DeserialisedType and SerialisedType.

type BettererSerialiser<DeserialisedType, SerialisedType = DeserialisedType> = {  serialise: BettererSerialise<DeserialisedType, SerialisedType>;  deserialise: BettererDeserialise<DeserialisedType, SerialisedType>;};

BettererSerialise#

The functions that coverts from a DeserialisedType to a SerialisedType.

type BettererSerialise<DeserialisedType, SerialisedType> = (result: DeserialisedType) => SerialisedType;

Args:

Returns: SerialisedType

BettererDeserialise#

The functions that coverts from a SerialisedType to a DeserialisedType.

type BettererDeserialise<DeserialisedType, SerialisedType> = (serialised: SerialisedType) => DeserialisedType;

Args:

Returns: DeserialisedType

BettererPrinter#

A function that converts a serialised test result to the string that will be saved in the test results file.

type BettererPrinter<SerialisedType> = (serialised: SerialisedType) => MaybeAsync<string>;

Args:

Returns: Promise<string> | string

BettererProgress#

A function that converts a test result to a number value that represents the progress towards the goal.

type BettererProgress<DeserialisedType> = (  baseline: DeserialisedType | null,  result: DeserialisedType | null) => MaybeAsync<BettererDelta | null>;

Args:

Returns: Promise<BettererDelta> | Promise<null> | BettererDelta | null