Matchers

Matchers are what make Capti so flexible when writing tests for HTTP endpoints. Often we don't know exactly what we're going to get back from the server (e.g. a unique ID value generated by the database). Using matchers, we can verify that the the response returns any value, or returns values that follow some sort of pattern or structure.

Here is an example test that makes heavy use of various matchers:

tests:
  - test: "get hello"
    description: "hello endpoint responds with some type of greeting"
    request:
      method: GET
      url: "http://localhost:3000/hello"
    expect:
      status: 2xx # match any 200 level status code
      headers:
        Content-Type: $regex /(json)+/ # match the provided regular expression
      body:
        message: $length >= 1 # ensure the message is not an empty string
        currentTime: $exists # match anything as long as it is present

Format

Matchers are always a keyword prefixed with a $ symbol, and followed by any number of arguments. The arguments, in some case, are also valid as matchers themselves, thus some matchers can be nested. Here are some examples:

# this matcher takes no arguments
$exists 

# this matcher takes one argument - a regex string used to match the response
$regex /[Hh]ello/ 

# this matcher checks whether the array at this position 
# contains an object with the property "id"
$includes { "id": "$exists" } 

# includes can also check any other valid YAML/JSON object, value, or matcher
$includes 5
$includes "hello, world!"
$includes $includes 5

# logical matchers can also be used to match multiple values conditionally or invert match results
$and ["$length 3", "$includes 5"]
$not $regex /[Ee]rror/

Matchers List

Basic Matchers

These matchers provide the base functionality for matching the most common assertions you will make.

• $exists - matches anything except null or missing values.
• $absent - matches null or missing values only. Great for asserting that a field like "password" should not be included in your response.
• $regex - compares the response value to a provided regular expression argument and matches any occurrences of that expression.

Array Matchers

Matching with arrays can be very tricky with Capti. Capti cannot easily determine which element should match which, so by default all elements are matched in order. However, you may not know the exact order when writing your assertions. Array matchers provide flexibility in matching array elements.

• $empty - asserts that the array is empty. This matcher also works for objects or strings.
• $length - allows you to match the length of the array using exact values or comparisons. Also works with strings and objects.
• $includes - asserts that the specified value or matcher matches at least one item in the array.
• $all - asserts that every item in an array matches the specified matcher argument

Logical Matchers

Logical matchers use basic logic concepts to allow to match multiple possible values and conditions in your responses.

• $and - provide multiple matchers as arguments to assert that your response matches all the arguments.
• $or - provide multiple matchers as arguments and assert that at least one argument matches your response.
• $not - invert the match result of the provided argument.
• $if - evaluates a secondary match conditionally based on the result of an initial match