Testing with Backend Requests

Usually, our flows contain upstream requests to one or more backends that we use to provide the client response. Sometimes upstream requests use results of other upstream requests. Testing such flows can be a challenge.

In this example flow, we use the helpful tool httpbin.org to reflect a parameter.

The Swagger snippet is

basePath: /api
paths:
  /dashboard:
    x-flat-flow: dashboard.xml
    get:
      parameters:
        - name: count
          in: query
          description: number of notifications
          type: number

and the flow in dashboard.xml:

<flow>
  <request content="notifications">
   {
    "url": "https://httpbin.org/anything",
    "headers": {
      "accept": "application/json"
    },
    "query": {
      "noti": {{ $request/get/count ?? 1 }}
    }
  }
  </request>
  <break if="$upstream/*/error" />

  <template>
    {{$rsp := content("notifications")/json }}
    {
      "sites": [],
      "notifications": {{ number($rsp/args/noti) ?? 2 }}
    }
  </template>
</flow>

We use the client's count= parameter (or 1 if missing) to send it as noti= to httpbin.org.

A response for that upstream request could look like this:

{
  "args": {
    "noti": "8"
  }, 
  "headers": {
    "Accept": "*/*", 
    "Host": "httpbin.org", 
    "User-Agent": "curl/7.54.0"
  }, 
  "method": "GET", 
  "url": "https://httpbin.org/anything?noti=8"
}

The parameter is reflected back in the JSON responses args property. That is what we use in the response template, where it is finally called notifications.

Mocking the Backend

A naïve approach to writing a flat test would be a test-request with some assertions.

tests/test-notifications.xml:

<flat-test>
  <test-request>
  {
    "path": "/api/dashboard",
    "query": {
      "count": 5
    }
  }
  </test-request>

  <assert>
  [
    [ "json-parse($response)/notifications", 5 ]
  ]
  </assert>
</flat-test>

This actually works. However, our flow in fact sends the upstream request to httpbin.org. The test will fail if their server is down. And if we were mocking a single-sign-on service, we would need real credentials. That's not how we like our automated tests to work.

A backend-flow test action allows us to create a fake response for the upstream requests. We can use regular actions to set headers, status code, response bodies and so on.

We extend our flat-test with this backend-flow call as its first action:

<flat-test>
  <backend-flow request="notifications">
    <template>
    {
      "args": {
        "noti": 5
      }
    }
    </template>
  </backend-flow>
  …

Note that the backend-flow action only registers that flow for subsequent request actions. That's why we have to put it first.

You can register multiple backend flows for your requests. Upstream requests and flows are matched using their request ID. In our case, notifications.

💡If your mock response is a bit longer than ours here, you can store it in a separate file and use copy instead:

<backend-flow>
  <copy in="mock.json" />
</backend-flow>

Asserting Upstream Requests

Injecting a mocked response into your flow only allows to test one direction: downstream. How do we test that our flow has sent the right parameters to the upstream server?

You can use assert in backend-flow, too:

  <backend-flow request="notifications">
    <assert>
    [
      [ "$request/get/noti", 5 ]
    ]
    </assert>
    <template>
    {
      "args": {
        "noti": 5
      }
    }
    </template>
  </backend-flow>

This test will fail if we don't pass the count parameter as expected.

For this assertion we have made use of the pre-defined variable $request. You can use $body to inspect the upstream request body. These variables are overridden in backend flows and restored afterwards. All other global variables are shared between flow, backend flow and test flow! This allows for dynamic backend mocks and more assertion possibilities.

See also

• Testing API Requests (cookbook)
• Testing Templates (cookbook)
• Test Framework (reference)
• assert (reference)
• backend-flow (reference)
• test-request (reference)