Orion in Action: Testing a Real API

Introduction

In this article, we will learn how to automate acceptance tests for a REST API. This API provides endpoints to register and authenticate users (sign up/in). Additionally provides a secure endpoint to fetch data of a user. The service persists and fetches data in a mongo database.

The below flow diagram represents how the service works.

API Flow diagram

Prerequisites

Clone the Git repository that contains the

git clone git@github.com:ivancorrales/orion-test-api.git

Additionally, you should have Docker and Orion installed on your computer.

orion-test-api

We’ll go through the different files and folders in the repository.

repository content

docker-compose.yml

Specification for service and mongo database.

version: '3'
services:
app:
image: ivancorrales/demo-api-mongo:0.0.1
environment:
MONGODB_URI: mongodb://root:secret@mongodb:27017/admin
ports:
- 3000:3000
mongodb:
image: mongo:latest
environment:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: secret
ports:
- 27017:27017
volumes:
- mongodb_data_container:/data/db
volumes:
mongodb_data_container:

Let’s execute docker-compose up to launch the service and the mongo containers.

.env

It contains environment variables to be passed to Orion.

.includes

Files api.hcl and database.hcl in folder includes/* contain reusable functions to deal with both API and database.

main.hcl

This file will be used as an entrypoint to execute all the scenarios.

happyPath.hcl

The scenario that covers the happy path.

signIn-failures.hcl / signUp-failures.hcl / showProfile-failures.

Set of scenarios to cover the unhappy paths.

Let’s do it!

First of all, we launch the docker-compose with command docker-compose up. Service API is running on localhost:3000 and mongo on localhost:27017. Keep in mind that authentication is required to connect to mongo (root/secret).

Acceptance tests can be executed with command:

orion run --input main.hcl --vars env/local.hcl

but…. let’s deep dive into the Orion files!

includes/api.hcl

It contains the functions to consume the API endpoints. These functions are invoked from the scenarios.

Actually, It’s very straightforward to read what the functions do. As you will realize showProfile function needs to pass the header x-access-token since this is a secure endpoint.

Learn more about vars, input arguments, functions and action http

includes/database.hcl

It contains a function that will be used from the scenarios to clean the database before executing the scenarios. We define default values for database and collection input arguments.

includes/database.hcl

Learn more about vars, functions, and action mongo

happyPath.hcl

The happy path must verify that a user is registered, authenticated and then she/he can fetch her/his profile details.

You will realize that argument baseApi is not passed when we call functions in include/api.hcl . That‘s due to baseApi will be a global variable in the main.hcl ..

Learn more about scenarios, and actions call and assert.

main.hcl

This file is used as an entry point to run all the scenarios. It’s the responsible to include the other hcl files. Besides this, we use this file to define the global hooks and define the input arguments.

main.hcl

Learn more about hooks definitions, input arguments and includes

signUp-failures.hcl

We write two scenarios: “A user cannot be registered because input data is not valid” or “there’s already a user with this email”.

To represent the first scenario in which the request is bad, we will take advantage of scenarios with examples.

signIn-failures.hcl / showProfile.hcl

These files are empty… I encourage you to try to implement the scenarios on your own. Practicing is the only way I know to learn something… and of course, let me know if you need any help!

Links of interest

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store