Forem: Evyatar Alush

Dead simple React validations with Vest

Evyatar Alush — Sat, 11 Jul 2020 20:13:38 +0000

One of the things that get the most bad rep in web development is form validation. It is something that seems so trivial and a part of almost every app, yet almost always, as your feature gets more complex, your validations seem to grow in mess and complexity as well.

Vest is a fairly new framework that aims to fix that bad parts in form validations by getting inspired by unit testing framework such as Mocha and Jest. It is framework agnostic, which means that you can use it with any UI framework you currently use.

In this tutorial you will learn how to use the basics of Vest to easily validate forms written in React.

What we'll be making today?

We'll start with a basic registration form, already implemented in React.

In this tutorial, although not React heavy, I am assuming you are comfortable with React, and have some familiarity with React's useState hook.

The concepts you'll be learning here though, are NOT react specific, and can be applied to any framework.

At any point during this tutorial when you feel that you want to go off-script, feel free to head to the Vest documentation site to learn about other cool features.

In this form we will add the following validations:
✅ Username required
✅ Username is too short
✅ Password is too short
✅ TOS agreement -> Validation without an error
✅ Passwords do not match -> Cross field validation
✅ Only validating the field that's being changed by the user
✅ Email is invalid
✅ Password is weak -> Warning validation
✅ Disabling the submit button if there are any errors

Take a look at our finished product:

Try it live on CodeSandbox

Let's start

You can start by forking the starter sandbox. It contains a simple React form without any validations at all. All the form does at the moment is update the form state upon input change.

To make things simpler, it also contains an <Input/> component that's already designed to show our errors validation errors when we run them later on.

Begin with the basics

The main concept in Vest is that your validation sits separately from your feature. This allows you to easily refactor your feature without touching your validations.

So head over to the src/validate.js file. That's where we'll be spending most our time.

The first step is to import vest from 'vest';

Next we'll create a new vest suite with our form name and immediately export it.

import vest from 'vest';

export default vest.create(() => {

});

This export returns a function, that when we run it - it runs our validation.

Now, this function needs to somehow get our form data. We pass it over using our callback function, so let's add a data argument to our callback function.

import vest from "vest";

export default vest.create((data = {}) => {

});

This is the initial structure that's true to every Vest suite.

The anatomy of a test

As noted before, Vest is inspired by the syntax of unit-testing frameworks, so we write tests in a similar fashion.

A structure of a jest test is roughly

test('message', () => {
    expect(value).toBe(anotherValue)
});

And the structure of a Vest test is (in this example, eqauls is one of many possible assertions).

test('field_name', 'message', () => {
    enforce(value).equals(anotherValue)
})

test - A function that runs a single validation test
'field_name' - The field being validated
'message' - The error that is presented to the user
enforce - Vest's assertion library (docs link)

Writing your first test

Our first test is "Username is required", we will check that it is not empty using .isNotEmpty().

First, add to your import statement the named imports of enforce and test.

import vest, { test, enforce } from "vest";

and in your suite, add the following test:

  test("username", "Username is required", () => {
    enforce(data.username).isNotEmpty();
  });

validate.js is now supposed to look like this:

import vest, { test, enforce } from "vest";

export default vest.create((data = {}) => {
  test("username", "Username is required", () => {
    enforce(data.username).isNotEmpty();
  });
});

Connecting Vest to our form

Obviously, this should not work yet. We have done nothing to make our form work with Vest.

Head back to src/Form.js.

First, let's import our validation suite into our Form module:

// src/Form.js
import suite from './validate';

And now, we need to make our form "aware" of our returned validation results, with suite.get(). Whenever we we run our validations, suite.get will contain the most up-to-date validation result.

// src/Form.js
// ...
export default function Form() {
  const [formState, setFormState] = useState({});

  const result = suite.get();
  // ...
}

To display the errors on the username field, find it and add it the errors property: errors={result.getErrors('username')}

      <Input
        name="username"
        label="Username"
        value={formState.username}
        onChange={handleChange}
        errors={result.getErrors('username')}
      />

Vest is now connected to your form, and whenever an error is present - your form will show it. But we did not yet make our form run our validations.

Create a new function called runValidate (the name doesn't matter) in the body of your React component:

This function takes the name of the changed field,
and its value. It then runs our validation agains the full state.

  const runValidate = (name, value) => {
    const res = validate({
      ...formState,
      ...{ [name]: value }
    });
  };

Call runValidate from the handleChange handler:

  const handleChange = (name, value) => {
    setFormState({ ...formState, [name]: value });
    runValidate(name, value);
  };

Our component is supposed to begin like this:

export default function Form() {
  const [formState, setFormState] = useState({});

  const result = suite.get();

  const runValidate = (name, value) => {
    const res = validate({
      ...formState,
      ...{ [name]: value }
    });
  };

  const handleChange = (name, value) => {
    const nextFormState = { ...formState, [name]: value };
    setFormState(nextFormState);
    runValidate(name, value);
  };

// ...

Try typing something into the username field and then remove it. You're supposed to see our error message:

That was easy.

One cool thing about Vest's validation being test-driven, is that you can have multiple tests for the same field, meaning that you can easily display different errors depending on different criteria. For example, if you only want to allow usernames longer than 3 characters, simply add the following test after the first one in src/validate.js:

  test("username", "Username is too short", () => {
    enforce(data.username).longerThanOrEquals(3);
  });

Now, without any changes to our form our username field should be able to display both messages.

Adding a few more validation tests should be easy. Paste the following into your validation suite in src/validate.js. Here are some for our password and confirm_password inputs.

  test("password", "Password is required", () => {
    enforce(data.password).isNotEmpty();
  });

  test("password", "Password must be at least 6 chars long", () => {
    enforce(data.password).longerThanOrEquals(6);
  });

  test("confirm_password", "Passwords do not match", () => {
    enforce(data.confirm_password).equals(data.password);
  });

And in src/Form.js add the error property to the password and confirm_password inputs just as like we did with username:

      <Input
        name="password"
        label="Password"
        value={formState.password}
        onChange={handleChange}
        errors={result.getErrors("password")}
      />
      <Input
        name="confirm_password"
        label="Confirm Password"
        value={formState.confirm_password}
        onChange={handleChange}
        errors={result.getErrors("confirm_password")}
      />

If you've followed the last steps correctly, you should see the errors appearing for username, password and confirm password when making changes to the form.

The problem?
Because we pass the whole form data to vest, it validates all fields at once, even if the user did not interact with them yet. This is easily fixable.

Validating just the current field

Ideally, we want to only validate the field the user is currently interacting with, and the fields impacted by it. This is done with vest.only() (docs link).

To your suite's callback function add a second argument, call it currentField, it will hold the field we currently want to validate, and right below it, to your first line of your suite, add vest.only(currentField);.

export default vest.create((data = {}, currentField) => {
  vest.only(currentField);

This alone won't do anything, because we did not yet tell Vest which field is our current field, so back in src/Form.js, modify runValidate so that it passes the name of the field as the second argument to validate:

  const runValidate = (name, value) => {
    const res = validate({
      ...formState,
      ...{ [name]: value }
    }, name); // -> field name got added here
  };

If you try to insert data to your inputs now, you'll see that fields are being validated only as they are interacted with.

Cool.

What about styles? 🎨

It's cool that we can validate, but we also want to make UI decisions based on the validation result, for example, painting error fields in red.

Once again, Vest has got you covered. It has a classNames (docs)utility function that you can use to generate a class name for your field's validation results.

As a first argument it takes your validation result, and as a second argument, a key value map of a validation state and its output class.

In src/Form.js add the following import:

import classNames from 'vest/classNames';

And in the body of our Form component, add the following assignment:

  const cn = classNames(result, {
    invalid: "invalid",
    valid: "valid"
  });

What we basically did here is this:

We passed our validation result to classNames
We told classnames that we would like invalid fields to get the invalid class, and valid fields to get the valid class.
We stored the output in a const called cn for later access. Its value is a function.

The names you use are up to you, but in our tutorial we used these classes in our stylesheet file.

Now, you can go to our username, password and confirm_password inputs, and add a classNames property with a cn call with the respective field name as an argument.

      <Input
        name="username"
        label="Username"
        value={formState.username}
        onChange={handleChange}
        errors={result.getErrors("username")}
        className={cn("username")}
      />
      <Input
        name="password"
        label="Password"
        value={formState.password}
        onChange={handleChange}
        errors={result.getErrors("password")}
        className={cn("password")}
      />
      <Input
        name="confirm_password"
        label="Confirm Password"
        value={formState.confirm_password}
        onChange={handleChange}
        errors={result.getErrors("confirm_password")}
        className={cn("confirm_password")}
      />

Your inputs should now display the current validity state in color as well.

Validating Terms of Service checkbox

Now that we can display colors, it would be a good time to validate the terms of service checkbox and add a password strength warning.

In src/validate.js add:

  test('tos', () => {
    enforce(data.tos).isTruthy()
  })

And in src/Form.js add to our tos Checkbox component the appropriate className:

      <Checkbox
        name="tos"
        checked={formState.tos}
        onChange={handleChange}
        label="I have read and agreed to the terms of service."
        className={cn("tos")}
      />

Note that we did not add a failure message to our TOS field because it is already descriptive enough.

Adding a password strength warning

Password strength is a sort of a weird creature in the world of validations. It shouts at you, but it still lets you submit the form.

Vest supports non-failing validations with the vest.warn() hook (docs link). It essentially tells Vest to store this field's result in a different basket so you can later treat it differently in your app.

To start, in src/Form.js add to our classNames call a warning class:

  const cn = classNames(result, {
    warning: "warning",
    invalid: "invalid",
    valid: "valid"
  });

And to our validation suite in src/validate.js add a simple password strength test.

  test("password", "Password is weak, Maybe add a number?", () => {
    vest.warn(); // using vest.warn marks this test as warning
    enforce(data.password).matches(/[0-9]/);
  });

If you test our field now, you'll notice that it appears correctly, but without our warning message.

This is because we only added to our field the error messages for password. As we learned earlier - warnings are stored in a different "basket". We need to go back to src/Form.js and tell our password input to also take the warning messages:

      <Input
        name="password"
        label="Password"
        value={formState.password}
        onChange={handleChange}
        errors={[
          ...result.getErrors("password"),
          ...result.getWarnings("password")
        ]}
        className={cn("password")}
      />

Validating email

We saved email for this late stage because it is a tricky one. Of course, you can test an email Regular expression using enforce(data.email).matches(SomeEmailRegExp), and this is fine.

Another option is to extend enforce with a custom function.

In our example, let's extend enforce with isEmail from validator.js:

import vest, { test, enforce } from "vest";
import { isEmail } from 'validator';

enforce.extend({ isEmail })

and now you can add to your suite the email test:

  test("email", "Email Address is not valid", () => {
    enforce(data.email).isEmail();
  });

And for the last time, in src/Form.js, add the error messages and classes to our email input:

      <Input
        name="email"
        label="Email"
        value={formState.email}
        onChange={handleChange}
        errors={result.getErrors("email")}
        className={cn("email")}
      />

Fixing weird confirm behaviour

One thing you may notice when the password is empty and deleting whatever was inside confirm_password, it goes green - which is technically correct, the both password and confirm_password are empty. But this is kinda of wonky.

This is fairly easy to fix, simply wrap the confirm_password test in a condition that it should not be validated unless password is present.

  if (data.password) {
    test("confirm_password", "Passwords do not match", () => {
      enforce(data.confirm_password).equals(data.password);
    });
  }

Now, whenever the password is empty, confirm_password will not be validated at all.

Handling the submit button

Our very last step is disabling the submit button on error:

Let's add a disabled prop to our Button component, with the value of result.hasErrors().

result.hasErrors() Is a function that checks if we have any errors in our suite. If we also pass it a field name as an argument, it returns a boolean only for that field.

<Button disabled={result.hasErrors()}>Submit</Button>

Wrapping up.

That's it! I hope you have enjoyed this tutorial of Vest.
You can see the even with little effort you can write pretty complex form validations that's still easy to read and maintain.

You can carry on by yourself using Vest's documentation site, contribute to the on project on github, or hit me directly on twitter

Fight Validations Spaghetti with Vest.

Evyatar Alush — Wed, 15 Jan 2020 10:49:57 +0000

tl;dr - Vest is a new validations framework I have been working on. I believe it makes validations a little bit cleaner and easier to maintain.

One of the problems that I see repeating the most in many projects is related to form validations - regardless of whether the project uses one framework or another (or not at all).

I’m not saying that validating forms is difficult or complicated, but that it’s really easy to write them in ways that will lead us into trouble down the road.

I am trying to solve it with Vest (Validation tEST), an open-source project that I have been working on, and has proved its effectiveness in my previous workplace over and over again.

What's wrong with form validations?

Before I elaborate about Vest itself, I’ll try to touch on the main problems I see in the world of validations.

After a while, validation logic tends to grow and be filled with spaghetti code:
In the beginning, when we write a new feature with forms, we make sure everything is clean and tidy. Many times what happens is that a new product request arrives and adds or changes features in that form that changes the technical design of the feature itself. What we usually do to finish on time is just bash it in until it works. After a while, this becomes an unmaintainable monster.

Nothing is reusable:
The way people usually write JS validations is pretty much like this - we have an input and some change handler that takes care of it. We usually write it along with the form itself, because that’s where it makes the most sense. But what about validation logic that repeats in different places across the site - such as password, or email?
Since we write our validations inside our features itself, we can’t easily use it in other places, and what we do is make an overly generic function that takes care of too many stuff, or copy/paste our logic and make it a maintenance nightmare.

It is very hard to refactor features:
When we write our validations they will usually be tied to the framework we’re using, this leads to the fact that if we ever want to make a change, such as update or replace the framework we’re using, or just refactor the feature, we can’t do that without re-writing our validations from scratch.
These are not the only ones, and of course, not every one of them is relevant in every scenario, but I am sure there is a general agreement that working with form validations can very easily lead to a big mess - even if not always.

Welcome Vest

Vest is an open-source framework I have been on for the past couple of years. I implemented its early versions in my previous workplace, and it helped a lot with bloat and maintainability.

Vest introduces nothing new, really, but it tries to re-think form validations with structures you are already familiar with. With Vest, we structure our validations with unit-test-like syntax that's completely separate from our feature code.

The idea is to not worry about which framework we use, or what is our feature structure. We look at our validations as a series of tests that our data needs to go through to be considered valid.

The syntax is simple, intentionally similar to what you would expect to see in testing frameworks such as Jest and Mocha, only that instead of describe/it/expect, you use validate/test/enforce.

validate: Is your suite wrapper. It initiates a Vest instance.
test: A single validation unit, it takes a field name (you can have more than one test for a single field), the message to display to the user in case of an error, and the test body.
enforce: An assertion function, very much like expect, only focused on data validation.

Among Vest's features

Vest provides you with a large set of tools and features to describe and manage your validations, you should look at the documentation for a full list - but here are some of the more useful ones.

Warn only tests:
You don't always want failed validations to fail the whole suite, for example when validating password strength. You may want to just show a warning to the user instead, and allow them to register regardless. This can be done with the vest.warn() hook.
Excluding or including tests:
When validating user inputs, we usually want to only perform our validations on fields that the user interacted with. Vest includes the vest.skip() and the vest.only() hooks that allow you to determine which fields to tests.
Async tests support:
When validating your features, you might need to query the server for some data that do not exist in the browser, for example - if a username already exists. Vest supports Promise(or async/await) tests, so you can describe it is a part of your suite.

If you find any of these interesting, I would really appreciate it if you gave Vest a try. It helped me and others when working on features, you might find it helpful as well.

GitHub
npm
Documentation

Thanks!