Orion in Action: Testing a Real API

Iván Corrales Solera
3 min readFeb 17, 2021


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


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.


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

repository content


Specification for service and mongo database.

version: '3'
image: ivancorrales/demo-api-mongo:0.0.1
MONGODB_URI: mongodb://root:secret@mongodb:27017/admin
- 3000:3000
image: mongo:latest
- 27017:27017
- mongodb_data_container:/data/db

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


It contains environment variables to be passed to Orion.


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


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


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!


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


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.


Learn more about vars, functions, and action mongo


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.


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.


Learn more about hooks definitions, input arguments and includes


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