Testing API Requests

You have defined your API in swagger.yaml, provided a detailed schema and wrote flows for API paths. How can we test the flows?

Let's say you have invented an incredibly useful API route that can tell whether a given number is odd.

Example

swagger.yaml:

swagger: '2.0'
basePath: /api
info:
  title: Useful Tools
  version: '1.0'
x-flat-validate:
  request: true
paths:
  /is-odd:
    get:
      x-flat-flow: odd.xml
      description: tells whether {number} is odd
      parameters:
      - name: number
        in: query
        required: true
        description: the number
        type: number

Flow in odd.xml:

<flow>
  <if test="$request/get/number = 0">
    <set-response-headers>
    {
      "see-also": "https://en.wikipedia.org/wiki/Parity_of_zero"
    }
    </set-response-headers>
  </if>

  <template>
  {
    "odd":  {{ $request/get/number mod 2 != 0 }}
  }
  </template>
</flow>

Tests

Now let's test that! We could write a sub-flow based test like in Testing Templates. But this time, we want to actually call our API to make sure that validation works, status codes are correct and so on.

The test-request action does just that: You define the API path that should be called and all necessary request parameters.

The test-request sets these variables so that you can easily inspect the result:

$status the HTTP status code (number)
$response the response body (string)
$headers the response headers (array)

This is what we will use to assert that everything works as expected:

tests/test-even.xml:

<flat-test>
  <test-request>
  {
    "path": "/api/is-odd?number=4"
  }
  </test-request>

  <assert>
  [
    [ "$status", 200, "even is 200, too" ],
    [ "json-parse($response)/odd", false, "4 is not odd" ]
  ]
  </assert>
</flat-test>

Note that we have used json-parse() to check the odd property.

tests/test-odd.xml:

<flat-test>
  <test-request>
  {
    "path": "/api/is-odd?number=4711"
  }
  </test-request>

  <assert>
  [
    [ "$status", 200, "odd is 200" ],
    [ "json-parse($response)/odd", true, "4711 is odd" ]
  ]
  </assert>
</flat-test>

tests/test-zero.xml:

<flat-test>
  <test-request>
  {
    "path": "/api/is-odd?number=0"
  }
  </test-request>

  <assert>
  [
    [ "$status", 200 ],
    [ "json-parse($response)/odd", false, "zero is even" ],
    [ "$headers/see-also", "https://en.wikipedia.org/wiki/Parity_of_zero", "aha!" ]
  ]
  </assert>
</flat-test>

Run the tests with flat test:

$ flat test tests/*.xml

1..3
ok 1 GET /api/is-odd?number=4 (tests/test-even.xml): 2 assertions
ok 2 GET /api/is-odd?number=4711 (tests/test-odd.xml): 2 assertions
ok 3 GET /api/is-odd?number=0 (tests/test-zero.xml): 3 assertions
passed: 3, failed: 0

📝 Exercise: Add a test for negative numbers, for numbers with fractional parts (and correct the schema accordingly) and that also verifies that the see-also header is not set.

Example

Tests

See also