assert

If at any point you think of an experiment you'd like to try out, all of the code examples below are editable.

assert is a power-user method that exposes how Distilled tells whether a given test assertion should pass or fail. assert can be used to check whether a test will pass or fail before it's run.

If you're extending Distilled, you can even override the assert method to easily add your own custom behaviors.

While you probably won't interact with assert directly most of the time you're using Distilled, this section may still be helpful in showing exactly when a Distilled test will pass or fail.

assert uses basic value types to tell if an assertion should pass or fail. Truthy values pass, and falsy (non-null) values fail.

One of assert's most powerful features is its ability to recursively execute functions. This means that if assert is passed a function, it will asynchronously execute that function. Then it will treat the result like a new assertion.

If the result is a basic type (see above), assert will resolve. If it's another function, the whole process will be repeated. To maintain compatibility with most other assertion libraries, assert will reject if an exception is thrown during a function call.

Recursively resolving assertions are a feature that may seem gimmicky until you start to extend Distilled and create helper methods for your tests. In that situation, you'll quickly find that being able to quickly and seamlessly wrap assertions in custom logic makes your life a lot easier -- and reduces boilerplate!

Distilled is an async-first library. All assertions are resolved asynchronously, period. This means you can use Promises the exact same way as you use functions to nest assertions inside of each other.

Put it all together, and you can end up with some pretty crazy tests. Note that you probably don't want to write tests like this -- they're hard to read!

The point of recursively resolving tests is to allow you to eliminate boilerplate and hard to read logic from your tests, so the below code is just an example of what's possible.

As a convenience feature, assertions will time out and fail after 500 milliseconds. This behavior can be customized by passing in a timeout option when initializing Distilled.

Bugs

Code samples in this section demonstrate bug fixes. They're not particularly relevant to the documentation, but they help make sure that Distilled never has any regressions.