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.
Prerequisites
Clone the Git repository that contains the
git clone git@github.com:ivancorrales/orion-test-api.gitAdditionally, 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.
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.hclbut…. 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.
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.
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!
