1. Home
2. Reference documentation
3. Tools
4. Fiddle

The Tests option in a fiddle's request configuration allows you to write test assertions against the instrumentation data that is returned by Fiddle when you press RUN. Writing tests is a good way to express what parts of a fiddle are most important when sharing the solution with someone else, or to express a bug by demonstrating the gap between observed behavior and what you expected to see.

Each test should be written on a single line and be in the following format:

[LABEL] TARGET COMPARISON_TYPE REFERENCE_VALUE

For example:

[Cache TTL is positive] events.where(fnName=fetch)[0].attribs.ttl isMoreThan 0

The optional LABEL, which must be wrapped in square brackets if present, allows you to define a 'human readable' expression for the test. TARGET is the thing being tested, REFERENCE_VALUE is a literal value to compare it with, and COMPARISON_TYPE is the comparison you want to make.

You can write more than one test per request.

Test targets

Within a fiddle test case, TARGET should reference a property of the result data, based on the following schema:

For example, to target the headers that are sent by Fastly to the backend in an origin request, use the .req property of the first item in the originFetches collection:

originFetches[0].req includes "My-Custom-Header"

In some cases targets are more complex. For example, the TTL set in vcl_fetch is reported as the .ttl property of the vcl-sub event object created by the vcl_fetch subroutine, but it's not possible to know ahead of time the position of that event within the events array. Instead, use a filter function to narrow down events to just the events associated with the vcl_fetch subroutine, and then pick the first one:

events.where(fnName=fetch)[0].attribs.ttl isMoreThan 0

events.where(fnName=fetch)[0].ttl isMoreThan 0

The where(fnName=fetch) is an example of using an aggregation function to transform the test data and make it easier to target the values that you want to test. The available functions are:

Lastly, you need to assert something about this target data, which requires a comparison type and a reference value, together making up an assertion.

Assertions

We support the following options for COMPARISON_TYPE:

All comparisons can be negated by prefixing them with not, e.g. notOneOf, isNotJSON, notMatches. The word 'is' will be ignored so can be used purely to improve readability.

The REFERENCE_VALUE must be expressed in a way that can be interpreted as the appropriate type:

• JSON number: A plain number (3, 5.7, -42)
• JSON string: A double quoted string ("foo"; contained double-quotes must be escaped as \")
• JSON boolean: The word true or false
• JSON array: A JSON-parseable array containing any combination of numbers, strings and booleans as defined above ([1, "foo"])
• JS RegExp: Either a JavaScript regex literal (/(foo|bar)/ism) or the bare pattern, not quoted or delimited (foo|bar). In the latter case, the s, m and i flags will be applied to the pattern automatically.

Labels

Labelling your tests is optional but helps to illustrate your intent, as well as make test results easier to read. The LABEL portion of the test expression may contain any character other than square brackets ([]), and since test expressions must be one line, labels may also not include newline characters.

[Response is OK] clientFetch.status is 200

Example tests

Debugging tests

When a test fails, Fiddle will display a representation of the observed, 'actual' value of the target, so you can see why it didn't match. That observed value will often be undefined because the target didn't match anything. In that case, it can be helpful to shorten your target expression, to reveal the shape of the data structure and allow you to see what you can target:

Testing best practices

When constructing tests for your fiddle, consider the following best practices:

• Label your tests to better illustrate your intent
• Try to avoid asserting the nature of the implementation of the solution. Instead, assert the achievement of the overall goal. It should be possible to change the way the solution is achieved without having to change the tests.
• For solutions that act on the user's IP address, for example to block users from certain regions from accessing certain content, use the Client IP override in request options to ensure that the test results are reliably reproducible.
• Fiddle data arrives asynchronously, but not all instrumentation delays are created equal! Tests that target clientFetch will be fastest. Those that target originFetches will be slightly slower, and events is slowest. Fiddle will keep repeating your tests until they pass or a timeout is reached, to allow asynchronous data to arrive. Speed up your fiddle by using clientFetch and originFetch assertions instead of testing events or logs.