Writing BuildSpec Files to Run Automated API Tests

With this tutorial we’re going to look at another buildspec file. But this time it’s for the CodeBuild project that runs automated API tests against a newly deployed stack, rather than a conventional build project. As you’ll see, this buildspec file includes a lot of the tricks that we’ve covered previously in the course, such as combining stack queries with additional commands to get important configuration values. This file also demonstrates how to use Newton for API testing, and how to obtain an access token by authenticating against Cognito from the command line.

The Example Buildspec File

Here’s the full “test.buildspec.yml” file that we’ll be looking at here, found in the “/buildspec” folder of the aws-connectedcar-common repository:

Setting Up the Build Agent

On line 5 of this buildspec file, in the “install” phase, you can see that the build agent is set up with the Node.JS runtime. This runtime is then used to install Newman, on line 7, as shown below:

Setting Variables

The next set of commands are in the “pre_build” phase of the file:

The first command in this phase sets a pseudo-random “number” variable based on a timestamp. The next five commands set variables that will be needed as input parameters later, in the “build” phase of this file. These variables have values assigned by interpolating the number variable in various ways.

The next five lines, from 16-20, use the CloudFormation describe-stacks command to get stack output values. Lastly, lines 21-23 use some of these stack output values as arguments for additional commands. Lines 21 and 23 show AWS commands, while line 22 uses the openssl library to generate a hash based on the Cognito username and userPoolId. This hash will be needed in a later command, which we’ll see below.

Running API Tests

Finally, we have the commands in the “build” phase of the file:

This is where the Newton command line tool is used to run the API tests in the three Postman collections. The first two collections are simpler to execute because they require simple authentication variables that have already been set in the previous section of the file. The Admin API collection that’s executed on line 26, for example, only requires the apiKey variable for authentication. The Vehicle API collection that’s executed on line 27 only needs the vehicle VIN and PIN, both of which also have variables set.

However, the Customer API uses Cognito as its security mechanism, so for this API’s tests we have to run some extra commands. First, as you can see on line 29, the Cognito user that will have been created as part of the Admin API tests will need to have a permanent password assigned. Then, the “aws cognito-idp admin-initiate-auth” command is called on the next line, to authenticate the user against Cognito and obtain an access token. With the token variable assigned a value by this point, the final set of tests for the Customer API are executed on line 31.