# Testing with Backend Requests

Usually, our [flows](https://sevenval.gitbook.io/flat/develop/reference/flow) contain [*upstream requests*](https://sevenval.gitbook.io/flat/develop/reference/actions/request) 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](https://httpbin.org/) to reflect a parameter.

The Swagger snippet is

```yaml
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`:

```markup
<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:

```javascript
{
  "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](https://sevenval.gitbook.io/flat/develop/reference/testing) would be a `test-request` with some assertions.

`tests/test-notifications.xml`:

```markup
<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](https://sevenval.gitbook.io/flat/develop/reference/actions/backend-flow) allows us to create a fake response for the upstream requests. We can use regular [actions](https://sevenval.gitbook.io/flat/develop/reference/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:

```markup
<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`](https://sevenval.gitbook.io/flat/develop/reference/actions/copy) instead:

```markup
<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:

```markup
  <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`](https://sevenval.gitbook.io/flat/develop/reference/variables#predefined-variables). 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](https://sevenval.gitbook.io/flat/develop/cookbook/test-api-request) (cookbook)
* [Testing Templates](https://sevenval.gitbook.io/flat/develop/cookbook/test-templates) (cookbook)
* [Test Framework](https://sevenval.gitbook.io/flat/develop/reference/testing) (reference)
* [`assert`](https://sevenval.gitbook.io/flat/develop/reference/actions/assert) (reference)
* [`backend-flow`](https://sevenval.gitbook.io/flat/develop/reference/actions/backend-flow) (reference)
* [`test-request`](https://sevenval.gitbook.io/flat/develop/reference/actions/test-request) (reference)