DEV Community

Cover image for Connecting AWS Account with Cypress Automation: A Simple STS Connection Test
Cypress profile image Sehani Chathurangi
Sehani Chathurangi for Cypress

Posted on

Connecting AWS Account with Cypress Automation: A Simple STS Connection Test

#automation #aws #testing #cypress

When building Cypress automation that interacts with AWS services, the first step is verifying that your test framework can successfully authenticate and communicate with your AWS account.

In this article, you'll learn how to connect Cypress to AWS and perform a simple authentication test using AWS Security Token Service (STS) and the GetCallerIdentity API.

This approach helps confirm that:

  • AWS credentials are correctly configured.
  • Cypress can invoke AWS SDK operations through Node.js tasks.
  • The automation environment is connected to the expected AWS account.

Establishing this connection first provides a solid foundation before automating interactions with services such as AWS Lambda, Amazon S3, Amazon DynamoDB, Amazon SNS, or Amazon SQS.

Prerequisites

Before getting started, ensure you have:

  • Node.js installed
  • A Cypress project
  • Valid AWS credentials:
    • AWS Access Key ID
    • AWS Secret Access Key
    • AWS Session Token (if using temporary credentials)
    • AWS Region

Note:If you're running Cypress in an AWS environment (such as AWS CodeBuild, an EC2 instance with an IAM role, or GitHub Actions using OpenID Connect), you may not need to provide credentials manually. The AWS SDK can automatically retrieve credentials from the execution environment.

Step 1: Install the AWS SDK

Install the AWS STS client package:

npm install @aws-sdk/client-sts
Enter fullscreen mode Exit fullscreen mode

For this connectivity test, we only need the AWS Security Token Service (STS) client.

The package provides:

  • STSClient – Creates a client for communicating with AWS STS.
  • GetCallerIdentityCommand – Returns details about the authenticated AWS identity associated with the configured credentials.

Step 2: Configure AWS Credentials

For local development, create or update your cypress.env.json file.

{
  "AWS_ACCESS_KEY_ID": "",
  "AWS_SECRET_ACCESS_KEY": "",
  "AWS_SESSION_TOKEN": "",
  "AWS_REGION": ""
}
Enter fullscreen mode Exit fullscreen mode

Populate the file with your AWS credentials.

Example:

{
  "AWS_ACCESS_KEY_ID": "your-access-key",
  "AWS_SECRET_ACCESS_KEY": "your-secret-key",
  "AWS_SESSION_TOKEN": "your-session-token",
  "AWS_REGION": "us-east-1"
}
Enter fullscreen mode Exit fullscreen mode

Important: Never commit cypress.env.json containing real AWS credentials to source control. Add it to your .gitignore file.

Best Practice: For CI/CD pipelines, prefer environment variables, IAM roles, or OpenID Connect (OIDC) instead of storing credentials in a file.

Step 3: Configure Cypress to Use AWS Credentials

Update your cypress.config.ts.

First, import the required AWS SDK classes.

import { defineConfig } from "cypress";
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
Enter fullscreen mode Exit fullscreen mode

Inside setupNodeEvents, map the Cypress environment variables to Node.js environment variables.

setupNodeEvents(on, config) {

  const awsKeys = [
    "AWS_ACCESS_KEY_ID",
    "AWS_SECRET_ACCESS_KEY",
    "AWS_SESSION_TOKEN",
    "AWS_REGION",
  ] as const;

  for (const key of awsKeys) {
    if (config.env[key]) {
      process.env[key] = config.env[key];
    }
  }

}
Enter fullscreen mode Exit fullscreen mode

Cypress stores environment variables in config.env, while the AWS SDK automatically reads credentials from the standard Node.js environment (process.env).

By copying the values into process.env, the AWS SDK can authenticate automatically without requiring any additional credential configuration.

The AWS SDK follows the AWS Credential Provider Chain, and environment variables are one of the first credential sources it checks.

Step 4: Create an AWS Connection Task

Create a Cypress task that authenticates with AWS using STS.

on("task", {
  async awsConnectionTest() {
    try {
      const client = new STSClient({
        region: process.env.AWS_REGION || "us-east-1",
      });

      const response = await client.send(
        new GetCallerIdentityCommand({})
      );

      return {
        Account: response.Account,
        Arn: response.Arn,
        UserId: response.UserId,
      };
    } catch (error) {
      throw new Error(`AWS authentication failed: ${error}`);
    }
  },
});
Enter fullscreen mode Exit fullscreen mode

Why use a Cypress task?

AWS SDK calls must run in Cypress tasks because tasks execute in the Node.js process.

Cypress test code runs in the browser context, where direct access to Node.js APIs is not available. Using cy.task() allows your tests to securely execute backend operations such as invoking AWS services.

What happens during this task?

  1. Cypress calls the awsConnectionTest task.
  2. The AWS SDK creates an STS client using the configured region.
  3. The SDK automatically resolves credentials from the environment.
  4. AWS validates the credentials.
  5. STS returns details about the authenticated IAM user or role.

A successful response looks like this:

{
  "Account": "123456789012",
  "Arn": "arn:aws:iam::123456789012:user/test-user",
  "UserId": "AIDAxxxxxxxx"
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Create a Cypress Test

Create a new test file.

testing/awsConnection.cy.ts
Enter fullscreen mode Exit fullscreen mode

Add the following test:

describe("AWS connection", () => {

  it("connects to AWS using STS GetCallerIdentity", () => {

    cy.task("awsConnectionTest").then((identity) => {

      cy.log(JSON.stringify(identity));

      expect(identity).to.have.property("Account");
      expect(identity).to.have.property("Arn");
      expect(identity).to.have.property("UserId");

    });

  });

});
Enter fullscreen mode Exit fullscreen mode

Step 6: Run the Cypress Test

Execute either of the following commands:

npx cypress open
Enter fullscreen mode Exit fullscreen mode

or

npx cypress run
Enter fullscreen mode Exit fullscreen mode

If authentication is successful, Cypress logs the authenticated AWS identity, including:

  • AWS Account ID
  • IAM User or Role ARN
  • User ID

This confirms that Cypress can successfully authenticate with your AWS account.

Why Start with GetCallerIdentity?

Before interacting with AWS services such as:

  • AWS Lambda
  • Amazon S3
  • Amazon DynamoDB
  • Amazon SNS
  • Amazon SQS

it's recommended to verify that authentication is working correctly.

GetCallerIdentity is ideal because it:

  • Confirms that authentication is successful.
  • Identifies the AWS account and IAM identity being used.
  • Helps diagnose credential-related issues early.
  • Does not require permissions beyond the ability to authenticate.

Conclusion

Successfully calling GetCallerIdentity confirms that Cypress can authenticate with AWS using the configured credentials.

In this article, you learned how to:

  1. Install the AWS STS SDK.
  2. Configure AWS credentials for local development.
  3. Map Cypress environment variables to the Node.js environment.
  4. Create a Cypress task that authenticates with AWS.
  5. Validate the connection using GetCallerIdentity.

Once this authentication step is working, you can extend the same approach to automate testing against other AWS services such as Lambda functions, S3 buckets, DynamoDB tables, SNS topics, SQS queues, and many more.

Top comments (0)