1. Home
2. Learn to build on the Fastly platform
3. Tools
4. Fiddle

Testing fiddles

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 event object created by the vcl_fetch subroutine, but it's not possible to know ahead of time what index that event has 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 async data to arrive. Speed up your fiddle by using clientFetch and originFetch assertions instead of testing events or logs.

WAF rule data model

The .waf property of a VCL flow event contains details of the execution of the Web application firewall. WAF rules are classified as scoring or threshold and also into one of the following categories:

• sql: SQL injection
• rfi: Remote file inclusion
• lfi: Local file inclusion
• rce: Remote command execution
• php: PHP injection
• session: Session hijacking
• http: HTTP violation
• xss: Cross-site scripting

The .waf.categoryScores property provides total scores for each category plus anomaly, a total of all categories. This is a good way to test that a request triggers a rule in a particular category:

events.where(fnName=miss)[0].waf.categoryScores.xss isAbove 0

If you simply want to know whether the WAF was triggered at all, use one of the top level properties of the .waf data block:

events.where(fnName=miss)[0].waf.didBlock isTrue

Individual matched rules are reported in .waf.scoringRules and .waf.thresholdRules. These are both arrays of objects that have the following data model:

To check that a particular rule was triggered, the transpose() aggregation function can be useful:

events.where(fnName=miss)[0].waf.scoringRules.transpose().ruleID includes 1