@3t-transform/integration-testing-ccc

CCC Integration Test Helper

Provides a set of helper methods for setting up an environment for integration testing.

Installation

yarn add @3t-tranform/integration-testing-ccc

For further development of this library, you can use npm link

In platform-monorepo/tools/integration-testing-ccc

npm link

In the service you are writing tests for

npm link @3t-transform/integration-testing-ccc

Setup

If you're using Jest, you will need to set up your tests to transpile typescript and ES6 before running.

If you haven't already, add jest with yarn add --dev jest

Then add a command to run your integration tests to the scripts in your package.json. For example:

{
  ...,
  "scripts": {
    "test:integration": "jest tests/integration --maxWorkers=1"
  }
}

Which runs all the test files in the tests/integration directory.

Then add ts-jest. This will be our transpiler for typescript and ES6. yarn add --dev ts-jest

You'll also need some additional configuration in your package.json

{
  ...,
  "jest": {
    "transform": {
      "^.+\\.[t|j]sx?$": [
        "ts-jest", {
          "babelConfig": true,
          "tsConfig": {
            "allowJs": true
          }
        }
      ]
    },
  },
}

The last thing is adding babel configuration. Create a file called .babelrc in the root directory of your service, and copy the following into it.

{
  "presets": ["@babel/preset-env", "@babel/preset-typescript"]
}

You may need to install these presets as dependencies

yarn add --dev @babel/preset-env
yarn add --dev @babel/preset-typescript

The order does matter, as in this example, the typescript transpiler will get run first.

Usage in integration tests

Helpers are provided as instance methods on a class which holds the state of the test data. An instance of the helper class should be defined within the same block that sets up a user for testing and tears down the test data. Keeping our tests encapsulated in these contexts will lower the risk of cross-test data pollution and orphaned data in our testing environment.

Try not to create too many contexts for your tests. Each time we spin up a new user, we have to make several calls to AWS and await a response. This includes putting events on eventbridge and waiting a period for them to be picked up.

The helper class expects AWS_REGION and STAGE to be set and will throw an error if they're not. You can specify other required env variables by passing them to the constructor as an array of strings.

Several methods are provided for setting up data and cleaning up afterwards, which should be called in beforeAll and afterAll blocks, respectively.

A wait method is also provided to help prevent race conditions which may produce flaky tests

method name	parameters	returns	context
registerUser	N/A	The cognito id of the new user	Used to register a cognito user without a profile in the central identity service
login	N/A	An access token	Used after registering a user. Logs into the user that was just created.
setupTestData	An array of strings representing permissions	cognitoId: The cognito id of the new user	Sets up a user with a profile in the central identity service. Should be used instead of registerUser and login if you need permissions
		accessToken: An access token
		organisationId: Id of the new organisation created for the user
cleanupTestData	N/A	undefined	Removes all data from testing environment using data stored on the instance. Should be called in an afterAll
wait	A number of miliseconds to wait	N/A	Waits a number of miliseconds before allowing the test to move on

The name of the organisation that is created for the user when setupTestData is called is "test org". This will be passed through in requests for an authorisation check.

Jest example

import IntegrationProfileManager from '@3t-transform/integration-testing-ccc';

describe("user without profile", () => {
  const integrationProfileManager = new IntegrationProfileManager();
  let cognitoId

  beforeAll(async () => {
    cognitoId = await integrationProfileManager.registerUser();
    await integrationProfileManager.login();
  });

  it("tests response when user has no profile", () => {
    ...
  });

  afterAll(async () => {
    await integrationProfileManager.cleanupTestData();
  });
});

describe("user with permissions", () => {
  const integrationProfileManager = new IntegrationProfileManager();
  let accessToken, organisationId, cognitoId, organisationName;

  before(async () => {
    { accessToken, organisationId, cognitoId } = await integrationProfileManager.setupTestData(["examplepermission:read"]);
    organisationName = "test org";
  });

  after(async () => {
    await integrationProfileManager.cleanupTestData();
  });
});

describe("instantiating helper class with checks for service-specific env vars", () => {
  const integrationProfileManager = new IntegrationProfileManager(["THIRD_PARTY_API_BASE"]);

  before(async () => {
    await integrationProfileManager.setupTestData(["examplepermission:read"]);
  });

  after(async () => {
    await integrationProfileManager.cleanupTestData();
  });
});

Running in local environment

To run it for your staging environment, there's some environment variables that you'll need to set.

macOS/Linux

export AWS_REGION="eu-west-2"
export STAGE="Your Stage Name"

Windows

SET AWS_REGION="eu-west-2"
SET STAGE="Your Stage Name"

Powershell

$env:AWS_REGION="eu-west-2"
$env:STAGE="Your Stage Name"

You'll also need to get the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN from the AWS SSO.

If you have any service-specific env variables, you'll need to export them as well.

Setting up in github actions

You should run your integration tests in your deploy-uat job, after running the deploy script.

- run yarn
- run: chmod +x ./deploy.sh && ./deploy.sh $STAGE
- run: yarn test:integration