Skip to main content
Version: 4.x

The Test Function

The test function represents a single case in your validation suite. It accepts the following arguments:

NameTypeOptionalDescription
nameStringNoThe name of the value or field that is validated.
messageStringYesAn error message to display to the user in case of a failure.
callbackFunctionNoThe actual validation logic for the given test.
keyStringYesA unique key used to retain test value when reordering dynamic tests.

A test can either be synchronous or asynchronous, and it can either have a severity of error or of warn.

tip

The test function is very similar to a unit test's it or test function, with some additions.

How to fail a test?​

Throwing inside your test body (using enforce)​

Just like in most unit testing frameworks, a validation fails whenever the test body throws an exception. Enforce throws an error on failed validations. When thrown with a string

// const username = 'Gina.Vandervort';
// const password = 'Q3O';

test('username', 'Should be at least 3 characters long', () => {
enforce(username).longerThanOrEquals(3);
}); // this test passes

test('password', 'Should be at least 6 characters long', () => {
enforce(password).longerThanOrEquals(6); // an error is thrown here
}); // this test fails
enforce.extend({
isChecked: value => {
return {
pass: !!value.checked,
message: () => 'value must be checked',
};
},
});

/*...*/

/*
tost = { checked: false }
*/

test('tos', () => {
enforce(tos).isChecked(); // will fail with the message: "value must be checked"
});

Explicitly returning false​

To make it easy to migrate your existing validation logic into Vest, it also supports validations explicitly returning false (and not any other falsy value) to represent failures.

// const username = 'Gina.Vandervort';
// const password = 'Q3O';

test('username', 'Should be at least 3 characters long', () => {
return username.length >= 3; // = true
}); // this test passes

test('password', 'Should be at least 6 characters long', () => {
return password.length >= 6; // = false
}); // this test fails

Rejecting a Promise​

Read more in the next section on async tests.