vest 3.2.8-dev-6d7c74 → 3.2.8

package/README.md

@@ -0,0 +1,115 @@
+![Vest](https://cdn.jsdelivr.net/gh/ealush/vest@assets/vest-logo.png 'Vest')
+
+# Vest 🦺 Declarative Validation Testing
+
+![Github Stars](https://githubbadges.com/star.svg?user=ealush&repo=vest&style=flat)
+![Npm downloads](https://img.shields.io/npm/dt/vest?label=Downloads&logo=npm)
+
+[![npm version](https://badge.fury.io/js/vest.svg)](https://badge.fury.io/js/vest) [![Build Status](https://travis-ci.org/ealush/vest.svg?branch=latest)](https://travis-ci.org/ealush/vest) [![Known Vulnerabilities](https://snyk.io/test/npm/vest/badge.svg)](https://snyk.io/test/npm/vest)
+![minifiedSize](https://img.shields.io/bundlephobia/min/vest?color=blue&logo=npm)
+
+[![Join discord](https://img.shields.io/discord/757686103292641312?label=Join%20Discord&logo=discord&logoColor=green)](https://discord.gg/WmADZpJnSe)
+
+- [Documentation homepage](https://vestjs.dev)
+- **Try vest live**
+  - [Vanilla JS Example](https://stackblitz.com/edit/vest-vanilla-support-example?file=validation.js)
+  - ReactJS Examples:
+    - [Example 1 (groups)](https://codesandbox.io/s/ecstatic-waterfall-4i2ne?file=/src/validate.js)
+    - [Example 2 (Async)](https://codesandbox.io/s/youthful-williamson-loijb?file=/src/validate.js)
+    - [Example 3](https://stackblitz.com/edit/vest-react-support-example?file=validation.js)
+    - [Example 4](https://stackblitz.com/edit/vest-react-registration?file=validate.js)
+    - [Example 5 (Password validator)](https://codesandbox.io/s/password-validator-example-6puvy?file=/src/validate.js)
+  - [VueJS Example](https://codesandbox.io/s/vest-vue-example-1j6r8?file=/src/validations.js)
+  - [Svelte Example](https://codesandbox.io/s/vestdocssvelteexample-k87t7?file=/validate.js)
+
+## Tutorials
+
+[Step By Step React Tutorial](https://dev.to/ealush/dead-simple-form-validation-with-vest-5gf8)
+
+## [Release Notes](https://github.com/ealush/vest/releases)
+
+## 🦺 What is Vest?
+
+Vest is a validations library for JS apps that derives its syntax from modern JS unit testing frameworks such as Mocha or Jest. It is easy to learn due to its use of already common declarative patterns.
+It works great with user-input validation and with validating upon user interaction to provide the best possible user experience.
+
+The idea behind Vest is that your validations can be described as a 'spec' or a contract that reflects your form or feature structure. Your validations run in production, and they are framework agnostic - meaning Vest works well with React, Angular, Vue, or even without a framework at all.
+
+Using Vest for form validation can reduce bloat, improve feature readability and maintainability.
+
+**Basic Example**
+![full](https://cdn.jsdelivr.net/gh/ealush/vest@assets/demos/full_3.gif 'full')
+
+**Memoized async test**
+![memo](https://cdn.jsdelivr.net/gh/ealush/vest@assets/demos/memo.gif 'memo')
+
+## ✅ Motivation
+
+Writing forms is an integral part of building web apps, and even though it may seem trivial at first - as your feature grows over time, so does your validation logic grows in complexity.
+
+Vest tries to remediate this by separating validation logic from feature logic so it is easier to maintain over time and refactor when needed.
+
+## ✨ Vest's features
+
+- 🎨 Framework agnostic (BYOUI)
+- ⚡️ Rich, extendable, assertions library (enforce) ([doc](http://vestjs.dev/#/enforce))
+- 🚥 Multiple validations for the same field
+- ⚠️ Warning (non failing) tests ([doc](http://vestjs.dev/#/warn))
+- 📝 Validate only the fields the user interacted with ([doc](http://vestjs.dev/#/exclusion))
+- ⏳ Memoize async validations to reduce calls to the server ([doc](http://vestjs.dev/#/test?id=testmemo-for-memoized-tests))
+- 🚦 Test grouping ([doc](http://vestjs.dev/#/group))
+
+## Example code ([Run in sandbox](https://codesandbox.io/s/vest-react-tutorial-finished-ztt8t?file=/src/validate.js))
+
+```js
+import { create, only, test, enforce, warn, skipWhen } from 'vest';
+
+export default create('user_form', (data = {}, currentField) => {
+  only(currentField);
+
+  test('username', 'Username is required', () => {
+    enforce(data.username).isNotEmpty();
+  });
+
+  test('username', 'Username is too short', () => {
+    enforce(data.username).longerThanOrEquals(3);
+  });
+
+  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('password', 'Password is weak, Maybe add a number?', () => {
+    warn();
+    enforce(data.password).matches(/[0-9]/);
+  });
+
+  skipWhen(!data.password, () => {
+    test('confirm_password', 'Passwords do not match', () => {
+      enforce(data.confirm_password).equals(data.password);
+    });
+  });
+
+  test('email', 'Email Address is not valid', () => {
+    enforce(data.email).isEmail();
+  });
+
+  test('tos', () => {
+    enforce(data.tos).isTruthy();
+  });
+});
+```
+
+## Why Vest?
+
+- 🧠 Vest is really easy to learn. You can take your existing knowledge of unit tests and transfer it to validations.
+- ✏️ Vest takes into account user interaction and warn only validations.
+- 🧱 Your validations are structured, making it very simple to read and write. All validation files look the same.
+- 🖇 Your validation logic is separate from your feature logic, preventing the spaghetti code that's usually involved with writing validations.
+- 🧩 Validation logic is easy to share and reuse across features.
+
+**Vest is an evolution of [Passable](https://github.com/fiverr/passable) by Fiverr.**

package/any.d.ts

@@ -0,0 +1,3 @@
+declare function any(...args: any[]): boolean;
+
+export default any;

package/any.js

@@ -0,0 +1 @@
+"use strict";!function(e,n){"object"==typeof exports&&"undefined"!=typeof module?module.exports=n():"function"==typeof define&&define.amd?define(n):(e="undefined"!=typeof globalThis?globalThis:e||self)["any@anyone"]=n()}(this,(function(){var e=function(e){if("function"==typeof e)try{return n(e())}catch(e){return!1}return n(e)},n=function(e){return!!Array.isArray(e)||0!=e&&!!e};return function(){for(var n=arguments.length,t=Array(n),r=0;r<n;r++)t[r]=arguments[r];return t.some(e)}}));

package/classNames.d.ts

@@ -0,0 +1,14 @@
+import { IVestResult } from './vestResult';
+
+declare function classNames(
+  res: Partial<IVestResult>,
+  classes?: {
+    valid?: string;
+    tested?: string;
+    invalid?: string;
+    warning?: string;
+    untested?: string;
+  }
+): (fieldName: string) => string;
+
+export default classNames;

package/classNames.js

@@ -0,0 +1 @@
+"use strict";!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?module.exports=e():"function"==typeof define&&define.amd?define(e):(t="undefined"!=typeof globalThis?globalThis:t||self).classNames=e()}(this,(function(){function t(t){return!(isNaN(parseFloat(t))||isNaN(Number(t))||!isFinite(t))}return function(e,n){if(void 0===n&&(n={}),!e||"function"!=typeof e.hasErrors)throw Error("[vest/classNames]: Expected first argument to be Vest's result object.");var r={},s={tested:function(n){return Object.prototype.hasOwnProperty.call(r,n)?r[n]:((o=Object.prototype.hasOwnProperty.call(e.tests,n))&&(o=t(o=e.tests[n].testCount)&&t(0)&&Number(o)>Number(0)),r[n]=o,s.tested(n));var o},untested:function(t){return!s.tested(t)},invalid:function(t){return s.tested(t)&&e.hasErrors(t)},warning:function(t){return s.tested(t)&&e.hasWarnings(t)},valid:function(t){return s.tested(t)&&!e.hasWarnings(t)&&!e.hasErrors(t)}};return function(t){var e,r=[];for(e in n)s[e]&&s[e](t)&&r.push(n[e]);return r.join(" ")}}}));

package/docs/README.md

@@ -0,0 +1,115 @@
+![Vest](https://cdn.jsdelivr.net/gh/ealush/vest@assets/vest-logo.png 'Vest')
+
+# Vest 🦺 Declarative Validation Testing
+
+![Github Stars](https://githubbadges.com/star.svg?user=ealush&repo=vest&style=flat)
+![Npm downloads](https://img.shields.io/npm/dt/vest?label=Downloads&logo=npm)
+
+[![npm version](https://badge.fury.io/js/vest.svg)](https://badge.fury.io/js/vest) [![Build Status](https://travis-ci.org/ealush/vest.svg?branch=latest)](https://travis-ci.org/ealush/vest) [![Known Vulnerabilities](https://snyk.io/test/npm/vest/badge.svg)](https://snyk.io/test/npm/vest)
+![minifiedSize](https://img.shields.io/bundlephobia/min/vest?color=blue&logo=npm)
+
+[![Join discord](https://img.shields.io/discord/757686103292641312?label=Join%20Discord&logo=discord&logoColor=green)](https://discord.gg/WmADZpJnSe)
+
+- [Documentation homepage](https://vestjs.dev)
+- **Try vest live**
+  - [Vanilla JS Example](https://stackblitz.com/edit/vest-vanilla-support-example?file=validation.js)
+  - ReactJS Examples:
+    - [Example 1 (groups)](https://codesandbox.io/s/ecstatic-waterfall-4i2ne?file=/src/validate.js)
+    - [Example 2 (Async)](https://codesandbox.io/s/youthful-williamson-loijb?file=/src/validate.js)
+    - [Example 3](https://stackblitz.com/edit/vest-react-support-example?file=validation.js)
+    - [Example 4](https://stackblitz.com/edit/vest-react-registration?file=validate.js)
+    - [Example 5 (Password validator)](https://codesandbox.io/s/password-validator-example-6puvy?file=/src/validate.js)
+  - [VueJS Example](https://codesandbox.io/s/vest-vue-example-1j6r8?file=/src/validations.js)
+  - [Svelte Example](https://codesandbox.io/s/vestdocssvelteexample-k87t7?file=/validate.js)
+
+## Tutorials
+
+[Step By Step React Tutorial](https://dev.to/ealush/dead-simple-form-validation-with-vest-5gf8)
+
+## [Release Notes](https://github.com/ealush/vest/releases)
+
+## 🦺 What is Vest?
+
+Vest is a validations library for JS apps that derives its syntax from modern JS unit testing frameworks such as Mocha or Jest. It is easy to learn due to its use of already common declarative patterns.
+It works great with user-input validation and with validating upon user interaction to provide the best possible user experience.
+
+The idea behind Vest is that your validations can be described as a 'spec' or a contract that reflects your form or feature structure. Your validations run in production, and they are framework agnostic - meaning Vest works well with React, Angular, Vue, or even without a framework at all.
+
+Using Vest for form validation can reduce bloat, improve feature readability and maintainability.
+
+**Basic Example**
+![full](https://cdn.jsdelivr.net/gh/ealush/vest@assets/demos/full_3.gif 'full')
+
+**Memoized async test**
+![memo](https://cdn.jsdelivr.net/gh/ealush/vest@assets/demos/memo.gif 'memo')
+
+## ✅ Motivation
+
+Writing forms is an integral part of building web apps, and even though it may seem trivial at first - as your feature grows over time, so does your validation logic grows in complexity.
+
+Vest tries to remediate this by separating validation logic from feature logic so it is easier to maintain over time and refactor when needed.
+
+## ✨ Vest's features
+
+- 🎨 Framework agnostic (BYOUI)
+- ⚡️ Rich, extendable, assertions library (enforce) ([doc](http://vestjs.dev/#/enforce))
+- 🚥 Multiple validations for the same field
+- ⚠️ Warning (non failing) tests ([doc](http://vestjs.dev/#/warn))
+- 📝 Validate only the fields the user interacted with ([doc](http://vestjs.dev/#/exclusion))
+- ⏳ Memoize async validations to reduce calls to the server ([doc](http://vestjs.dev/#/test?id=testmemo-for-memoized-tests))
+- 🚦 Test grouping ([doc](http://vestjs.dev/#/group))
+
+## Example code ([Run in sandbox](https://codesandbox.io/s/vest-react-tutorial-finished-ztt8t?file=/src/validate.js))
+
+```js
+import { create, only, test, enforce, warn, skipWhen } from 'vest';
+
+export default create('user_form', (data = {}, currentField) => {
+  only(currentField);
+
+  test('username', 'Username is required', () => {
+    enforce(data.username).isNotEmpty();
+  });
+
+  test('username', 'Username is too short', () => {
+    enforce(data.username).longerThanOrEquals(3);
+  });
+
+  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('password', 'Password is weak, Maybe add a number?', () => {
+    warn();
+    enforce(data.password).matches(/[0-9]/);
+  });
+
+  skipWhen(!data.password, () => {
+    test('confirm_password', 'Passwords do not match', () => {
+      enforce(data.confirm_password).equals(data.password);
+    });
+  });
+
+  test('email', 'Email Address is not valid', () => {
+    enforce(data.email).isEmail();
+  });
+
+  test('tos', () => {
+    enforce(data.tos).isTruthy();
+  });
+});
+```
+
+## Why Vest?
+
+- 🧠 Vest is really easy to learn. You can take your existing knowledge of unit tests and transfer it to validations.
+- ✏️ Vest takes into account user interaction and warn only validations.
+- 🧱 Your validations are structured, making it very simple to read and write. All validation files look the same.
+- 🖇 Your validation logic is separate from your feature logic, preventing the spaghetti code that's usually involved with writing validations.
+- 🧩 Validation logic is easy to share and reuse across features.
+
+**Vest is an evolution of [Passable](https://github.com/fiverr/passable) by Fiverr.**

package/docs/_sidebar.md

@@ -0,0 +1,19 @@
+- [Getting Started](./getting_started)
+- [enforce](./enforce)
+  - [List of Enforce rules](./n4s/rules)
+  - [Creating Custom Rules](./n4s/custom)
+  - [Shape and schema validation](./n4s/compound)
+  - [Enforce templates](./n4s/template)
+  - [Consuming external rules](./n4s/external)
+- [The result object](./result)
+- [test](./test)
+  - [How to fail a test](./test#failing_a_test)
+  - [Warn only tests](./warn)
+  - [Grouping tests](./group)
+  - [Optional Tests](./optional)
+- Advanced cases
+  - [Cross Field Validations](./cross_field_validations)
+  - [Excluding or including tests](./exclusion)
+  - [Using with node](./node)
+  - [Utilities](./utilities)
+- [Migration Guides](./migration)

package/docs/_sidebar.md.bak

@@ -0,0 +1,14 @@
+- [Getting Started](./getting_started)
+- [enforce](./enforce){{ENFORCE_DOCS}}
+- [The result object](./result)
+- [test](./test)
+  - [How to fail a test](./test#failing_a_test)
+  - [Warn only tests](./warn)
+  - [Grouping tests](./group)
+  - [Optional Tests](./optional)
+- Advanced cases
+  - [Cross Field Validations](./cross_field_validations)
+  - [Excluding or including tests](./exclusion)
+  - [Using with node](./node)
+  - [Utilities](./utilities)
+- [Migration Guides](./migration)

package/docs/cross_field_validations.md

@@ -0,0 +1,79 @@
+# Cross Field Validations
+
+Sometimes it is not enough to only validate a field by itself, because its validity is dependant on the validity or invalidity of a different field.
+
+Take for example the password confirmation field, by itself it serves no purpose, and as long as the password itself is not field, you might choose to not validate it to begin with. That's an **AND** relationship between fields. There can also be an **OR** relationship between fields, for example - either email address or phone number have to be filled, but neither is required as long the other was filled by the user.
+
+All these cases can be easily handled with Vest in different ways, depending on your requirements and validation strategy.
+
+## The Any utility
+
+Your specific example can be handled with the `any` utility function. The `any` utility function takes a series of functions or expressions, and as long as at least one evaluates to `true`, it will mark your validation as passing.
+
+### Use any to use different conditions in the same test
+
+You could also use any within your test, if you have a joined test for both scenarios. This means that you have to return a boolean from your tests.
+
+Demo: https://codesandbox.io/s/demo-forked-ltn8l?file=/src/validate.js
+
+```js
+import { create, test, enforce } from 'vest';
+import any from 'vest/any';
+
+export default create('form_name', (data = {}) => {
+  test('email_or_phone', 'Email or phone must be set', () =>
+    any(
+      () => {
+        enforce(data.email).isNotEmpty();
+        return true;
+      },
+      () => {
+        enforce(data.phone).isNotEmpty();
+        return true;
+      }
+    )
+  );
+});
+```
+
+## skipWhen for conditionally skipping fields
+
+If your field depends on a different field's existence or a different simple condition, you could use skipWhen.
+In the following example I only validate `confirm` if password is not empty:
+
+DEMO: https://codesandbox.io/s/demo-forked-z2ur9?file=/src/validate.js
+
+```js
+import { create, test, enforce, skipWhen } from 'vest';
+export default create('user_form', (data = {}) => {
+  test('password', 'Password is required', () => {
+    enforce(data.password).isNotEmpty();
+  });
+  skipWhen(!data.password, () => {
+    test('confirm', 'Passwords do not match', () => {
+      enforce(data.confirm).equals(data.password);
+    });
+  });
+});
+```
+
+## skipWhen for conditionally skipping field based on a previous result
+
+Sometimes you might want to run a certain validation based on the validation result of a previously run test, for example - only test for password strength if password DOESN'T have Errors. You could access the intermediate validation result and use it mid-run.
+
+This requires using the function created from create():
+
+```js
+import { create, test, enforce, skipWhen } from 'vest';
+const suite = create('user_form', (data = {}) => {
+  test('password', 'Password is required', () => {
+    enforce(data.password).isNotEmpty();
+  });
+  skipWhen(suite.get().hasErrors('password'), () => {
+    test('password', 'Password is weak', () => {
+      enforce(data.password).longerThan(8);
+    });
+  });
+});
+export default suite;
+```

package/docs/enforce.md

@@ -0,0 +1,18 @@
+# Enforce
+
+Enforce is Vest's assertion library. It is used to validate values within, or outside of a Vest test.
+
+```js
+import { enforce, test } from 'vest';
+
+test('username', 'Must be at least three characters long', () => {
+  enforce(username).longerThan(2);
+});
+```
+
+- Further Reading:
+  - [List of Enforce rules](./n4s/rules)
+  - [Creating Custom Rules](./n4s/custom)
+  - [Shape and schema validation](./n4s/compound)
+  - [Enforce templates](./n4s/template)
+  - [Consuming external rules](./n4s/external)

package/docs/enforce.md.bak

@@ -0,0 +1,13 @@
+# Enforce
+
+Enforce is Vest's assertion library. It is used to validate values within, or outside of a Vest test.
+
+```js
+import { enforce, test } from 'vest';
+
+test('username', 'Must be at least three characters long', () => {
+  enforce(username).longerThan(2);
+});
+```
+
+- Further Reading:{{ENFORCE_DOCS}}

package/docs/exclusion.md

@@ -0,0 +1,128 @@
+# Excluding and including tests
+
+When performing validations in real world-scenarios, you may need to only run tests of a single field in your suite, or skip certain tests according to some logic. That's why Vest includes `skip()` and `only()`.
+
+`skip()` and `only()` are functions that take a name of the test, or a list of names to either include or exclude fields from being validated. They should be called from the body of suite callback, and in order for them to take effect, they should be called before anything else.
+
+!> **NOTE** When using `only()` or `skip()` you must place them before any of the tests defined in the suite. Hooks run in order of appearance, which means that if you place your `skip` hook after the field you're skipping - it won't have any effect.
+
+### Only running specific tests (including)
+
+When validating upon user interactions, you will usually want to only validate the input the user currently interacts with to prevent errors appearing in unrelated places. For this, you can use `only()` with the name of the test currently being validated.
+
+In the example below, we're assuming the argument `fieldName` is being populated with the name of the field we want to test. If none is passed, the call to `only` will be ignored, and all tests will run as usual. This allows us to test each field at a time during the interaction, but test all on form submission.
+
+```js
+import { create, enforce, test, only } from 'vest';
+
+const suite = create('New User', (data, fieldName) => {
+  only(fieldName);
+
+  test('username', 'Username is invalid', () => {
+    /* some validation logic*/
+  });
+  test('email', 'Email is invalid', () => {
+    /* some validation logic*/
+  });
+  test('password', 'Password is invalid', () => {
+    /* some validation logic*/
+  });
+});
+
+const validationResult = suite(formData, changedField);
+```
+
+### Skipping tests
+
+There are not many cases for skipping tests, but they do exist. For example, when you wish to prevent validation of a promo code when none provided.
+
+In this case, and in similar others, you can use `skip()`. When called, it will only skip the specified fields, all other tests will run as they should.
+
+```js
+import { create, enforce, test, skip } from 'vest';
+
+const suite = create('purchase', data => {
+  if (!data.promo) skip('promo');
+
+  // this test won't run when data.promo is falsy.
+  test('promo', 'Promo code is invalid', () => {
+    /* some validation logic*/
+  });
+});
+
+const validationResult = suite(formData);
+```
+
+## Conditionally excluding portions of the suite
+
+In some cases we might need to skip a test or a group based on a given condition, for example - based on the intermediate state of the currently running suite. To allow this, can use `skipWhen`.
+
+In the following example we're skipping the server side verification of the username if the username is invalid to begin with:
+
+```js
+import { create, test, enforce, skipWhen } from 'vest';
+
+const suite = create('user_form', (data = {}) => {
+  test('username', 'Username is required', () => {
+    enforce(data.username).isNotEmpty();
+  });
+
+  skipWhen(suite.get().hasErrors('username'), () => {
+    test('username', 'Username already exists', () => {
+      // this is an example for a server call
+      return doesUserExist(data.username);
+    });
+  });
+});
+export default suite;
+```
+
+!> **Note** Using suite.get() within the suite runs returns a **DRAFT** result. This means that it may not contain the final validation result.
+
+## Including and excluding groups of tests
+
+Similar to the way you use `skip` and `only` to include and exclude tests, you can use `skip.group` and `only.group` to exclude and include whole groups.
+
+These two functions are very powerful and give you control of whole portions of your suite at once.
+
+```js
+import { create, test, group, enforce, skip } from 'vest';
+
+create('authentication_form', data => {
+  skip.group(data.userExists ? 'signUp' : 'signIn');
+
+  test('userName', "Can't be empty", () => {
+    enforce(data.username).isNotEmpty();
+  });
+  test('password', "Can't be empty", () => {
+    enforce(data.password).isNotEmpty();
+  });
+
+  group('signIn', () => {
+    test(
+      'userName',
+      'User not found. Please check if you typed it correctly.',
+      findUserName(data.username)
+    );
+  });
+
+  group('signUp', () => {
+    test('email', 'Email already registered', isEmailRegistered(data.email));
+
+    test('age', 'You must be at least 18 years old to join', () => {
+      enforce(data.age).largerThanOrEquals(18);
+    });
+  });
+});
+```
+
+## Things to know about how these functions work:
+
+**only.group()**:
+When using `only.group`, other groups won't be tested - but top level tests that aren't nested in any groups will. The reasoning is that the top level space is a shared are that will always be executed. If you want only your group to run, nest everything else under groups as well.
+
+If you combine `only.group` with `skip`, if you skip a field inside a group that is included, that field will be excluded during this run regardless of its group membership.
+
+**skip.group()**
+
+If you combine `skip.group` with `only` your included field declared within the skipped tests will be ignored.

package/docs/getting_started.md

@@ -0,0 +1,79 @@
+# Installation
+
+To install the stable version of Vest:
+
+```
+npm install vest
+```
+
+You can also add Vest directly as a script tag to your page:
+
+```html
+<script src="https://unpkg.com/vest@3"></script>
+```
+
+Vest tests are very much like unit tests, with only slight differences. Instead of using `describe/it/expect`, you will use `validate/[test](./test)/[enforce](./enforce)`.
+
+- `test`: A single validation unit, validating a field or a single value. It takes the name of the field being validated, a failure message (to display to the user), and a callback function that contains the validation logic. [Read more about test].
+- `enforce`: This is our assertion function. We’ll use it to make sure our validations pass. [Read more about enforce].
+
+## Writing tests
+
+First, you need to initialize your validation suite using `create()`. This initializes your validation suite state and allows validation results to be merged with future validations.
+
+```js
+import { create } from 'vest';
+
+const suite = create('formName', () => {
+  // validation suite content goes here.
+});
+
+const validationResult = suite();
+```
+
+`create()` takes the following arguments:
+
+| Name     | Type       | Optional | Description                                                    |
+| -------- | ---------- | -------- | -------------------------------------------------------------- |
+| `name`   | `string`   | Yes      | Suite name.                                                    |
+| callback | `function` | No       | Your validation suite's body. This is where your tests reside. |
+
+`create` returns a "suite" function which runs your validation suite. All the arguments you pass to it are being forwarded to your tests callback. You can use it to pass form data to your validation, excluded fields, and anything required for during your validation runtime.
+
+A simple validation suite would look somewhat like this:
+
+```js
+// suite.js
+import { create, test, enforce } from ‘vest’;
+
+const suite = create('NewUserForm', (formData) => {
+    test('username', 'Must be between 2 and 10 chars', () => {
+        enforce(formData.username)
+            .longerThanOrEquals(2)
+            .shorterThan(10);
+    });
+
+    test('password', 'Must contain at least one digit', () => {
+        enforce(formData.password)
+            .matches(/(?=.*[0-9])/);
+    });
+});
+
+export default suite;
+```
+
+```js
+// myFeature.js
+
+import suite from './suite.js';
+
+const res = suite(formData);
+```
+
+In the above example, we validate a form called `NewUserForm` containing username and a password.
+
+**Read next about:**
+
+- [Vest's result object](./result).
+- [Using the test function](./test).
+- [Asserting with enforce](./enforce).