getting started

Distilled is one of the nicest, friendliest testing libraries that you will ever use, so getting up to speed is pretty quick. If at any point you think of an experiment you'd like to try out, all of the code examples below are editable.

Running Distilled is easy. Create a new instance, and then just start adding tests. You can create as many instances of Distilled as you'd like, anywhere in your project.

When I'm starting out a new project, I like to add my tests to the same file as my prototype code. Then once I have a better grasp of how my code will be structured, I'll copy and paste my tests into another, more permanent file.

Writing Tests

The test method is how you add tests to a suite.

Tests in Distilled are hierarchical. This means that you can infinitely nest or chain tests as much as you want. Use tests to organize your tests!

Child tests will only be executed if their parents pass. This speeds up you testing suite by allowing you to abort tests early if a piece of setup or a pre-test fails.

Testing Harnesses

Distilled's API is designed to be simple and transparent. Just from the above code, you may already have some idea of how you could set up a dead-simple, custom testing harness for your next project.

For a fun challenge, try extending the above code so that you can conditionally run only certain parts of your test suite based on a flag or config setting.

The above example illustrates one of Distilled's important, underlying philosophies: testing harnesses and runners are easy to reason about if their underlying logic isn't obscured. In fact, becoming comfortable thinking about your tests this way opens the door for you to build creative things and to adapt Distilled to each project's unique testing needs.

Check out the full documentation for when and how tests are executed!

How Tests Pass or Fail

Of course, the test method isn't just for organization. It also runs tests.

Distilled is designed to accept a wide variety of assertion formats because different APIs call for different testing styles. In keeping with the theme of simplicity and extensibility, this also makes it easy to build new helper methods and wrappers around Distilled.

Because Distilled listens for standard exceptions inside of its test methods, it's also compatible out-of-the-box with most modern assertion libraries.

Tests in Distilled are always executed asynchronously. Period.

This is a decision made with experts in mind. Most well-written Javascript code is asynchronous. Therefore, Distilled is optimized for asynchronous code first and foremost.

A lot of work has gone into making sure that Distilled tests act like native Promises and resolve consistently with the native Promise chaining behavior that you're already used to. If you like using Promises and Async functions, Distilled is one of the nicest coding environments out there. No more jumping through hoops just to write clean async unit tests!

Because Distilled is focused on being as flexible as possible, tests can also be nested by chaining, via a parameter (handy for arrow functions), or through the this keyword.

Another trick that you'll quickly learn to love is recursively resolving assertions in your tests.

Recursively resolving assertions are the power-user feature that you never knew you wanted. They make it even easier to extend Distilled on-the-fly in powerful ways.

If you want to dig deeper into how Distilled resolves tests, check out the documentation for assert.

If you're ready to start extending Distilled and adding your own custom features, check out the documentation for then. This will allow you to run custom logic whenever a test finishes.

Custom Test Reporters

Distilled makes it easy to build custom test reporters. Distilled can be extended to stream test results as they finish, to pipe results across network requests, or to set up new criteria for whether or not a suite can be considered passed.

A reporter is a function that you pass into Distilled at initialization. Distilled's reporter will get called once per-test.

Want to dig deeper into how reporters work? There's documentation for that as well!

Summing up

And that's it! You're now equipped to start using Distilled in your own projects.