---
title: Effiapi test suite
author: Lars Wirzenius
...

[yarn]: https://liw.fi/cmdtest/

# Introduction

This chapter descibes the effiapi API, using [yarn][] automated
scenario tests. It is meant to be understandable to Effi sysadmins,
and those writing applications using the API, as well as be an
executable test suite for the API.

The API is a simple RESTful HTTP API using JSON. This means that:

* each API call is an HTTP request, with a response

* all data is represented as JSON in the body of the request of
  response

* metadata about the data is represeneted as HTTP headers

* standard HTTP verbs (POST, PUT, GET, DELETE) are used to indicate
  the action

* standard HTTP status codes are used to indicate result of the
  request (200 = OK, 404 = not found, etc)

Examples will be provided.

# Test scenarios

## Manage memberships

This section shows the API calls to manage a memberhip: to create the
member, to update and retrieve it, and to search memberships.

    SCENARIO Manage memberships

    GIVEN An effiapi instance

    WHEN admin requests GET /status
    THEN HTTP status is 200
    AND body matches { "resources": 0 }

    WHEN admin requests POST /memb with body { "fullname": "James Bond" }
    THEN HTTP status is 201
    AND remember header Muck-Id as ID
    AND remember header Muck-Revision as REV1

    WHEN admin requests GET /status
    THEN HTTP status is 200
    AND body matches { "resources": 1 }

    WHEN admin requests GET /memb with header Muck-Id: ${ID}
    THEN HTTP status is 200
    AND body matches { "fullname": "James Bond" }
    AND header Muck-Revision is ${REV1}

    WHEN admin requests PUT /memb with id ${ID}, revision ${REV1},
    ... and body { "fullname": "Alfred Pennyworth" }
    THEN HTTP status is 200
    AND remember header Muck-Revision as REV2

    WHEN admin requests GET /memb with header Muck-Id: ${ID}
    THEN HTTP status is 200
    AND body matches { "fullname": "Alfred Pennyworth" }
    AND header Muck-Revision is ${REV2}

    FINALLY Effiapi is terminated

TODO:

* update
* delete
* search
* members can see their own data, and can't see each others'
* member follows authn link emailed to them

# Appendix: Yarn scenario step implementations

## Start and stop effiapi

    IMPLEMENTS GIVEN An effiapi instance
    effiapi.write_config()
    effiapi.start()

    IMPLEMENTS FINALLY Effiapi is terminated
    effiapi.terminate()

## Make HTTP requests

    IMPLEMENTS WHEN admin requests POST /memb with body (.+)
    body = get_json_match()
    effiapi.POST('/memb',  {}, body)

    IMPLEMENTS WHEN admin requests GET /status
    effiapi.GET('/status', {}, None)

    IMPLEMENTS WHEN admin requests PUT /memb with id (\S+), revision (\S+), and body (.+)
    rid = get_expanded_match()
    rev = get_expanded_match()
    body = get_json_match()
    print('rid', repr(rid))
    print('rev', repr(rev))
    print('body', repr(body))
    headers = {
        'Muck-Id': rid,
        'Muck-Revision': rev,
    }
    effiapi.PUT('/memb', headers, body)

    IMPLEMENTS WHEN admin requests GET /memb with header (\S+): (\S+)
    header = get_next_match()
    print('header', repr(header))
    value = get_expanded_match()
    print('value', repr(value))
    headers = {
        header: value,
    }
    V['xx'] = {
        'header': header,
        'value': value,
    }
    effiapi.GET('/memb', headers, None)

## Inspect HTTP responses

    IMPLEMENTS THEN HTTP status is (\d+)
    expected = int(get_next_match())
    actual = effiapi.get_status_code()
    print 'actual:', repr(actual)
    print 'expecting:', repr(expected)
    assertEqual(effiapi.get_status_code(), expected)

    IMPLEMENTS THEN remember header (\S+) as (.+)
    header = get_next_match()
    varname = get_next_match()
    value = effiapi.get_header(header)
    print 'header:', repr(header)
    print 'value:', repr(value)
    print 'varname:', repr(varname)
    save_for_expansion(varname, value)

    IMPLEMENTS THEN header (\S+) is (.+)
    header = get_next_match()
    expected = get_expanded_match()
    actual = effiapi.get_header(header)
    print 'header:', repr(header)
    print 'expected:', repr(expected)
    print 'actual:', repr(actual)
    assertEqual(actual, expected)

    IMPLEMENTS THEN body matches (.+)
    expected = get_json_match()
    actual = effiapi.get_json_body()
    print 'expected:', expected
    print 'actual:  ', actual
    assertEqual(actual, expected)