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.

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.