Orion in Action: Testing a Real API
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.
Clone the Git repository that contains the
git clone firstname.lastname@example.org: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.
Specification for service and mongo database.
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
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!