cypress

Provides custom commands for E2E testing Hub apps with Cypress.

Refer for the E2E Testing Guide for a more in depth usage documentation.

Installation#

npm install @iqmetrix/cypress --save-dev

Usage#

Load the Module#

Register the package's commands for use in your tests.

/cypress/support/index.ts
import "@iqmetrix/cypress";

Store Auth Credentials#

Store your int login credentials for use by the commands.

These can be set any way you would prefer following the Cypress Environment Guide. For example, if you don't want to store these in your codebase or would like to set them at buildtime, you could set variables in your Azure DevOps pipeline and load them accordingly or use Azure Key Vaults as outlined below.

/cypress.json
{
"env": {
"auth": {
"username": "some.user@example.com",
"password": "asdf1234",
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET",
"envSuffix": "int"
}
}
}
describe("Example Flow", () => {
before(() => {
cy.login(Cypress.env("auth"));
});
after(() => {
cy.logout();
});
});

Access Credentials from Azure Key Vaults#

Use the Azure Portal to store test user credentials in a Key Vault, then access them for your tests.

This can be used to keep your secrets safely stored.

Store Credentials in an Azure Key Vault#

Secrets are expected to be named in a set format, prefixed with the user key, in order for the plugin to access them.

SecretKey FormatExample KeyExample Value
Username{user}-usernametestInt-usernametest@example.com
Password{user}-passwordtestInt-passwordAbcd1234
Client Id{user}-clientIdtestInt-clientIdiQmetrixHub
Client Secret{user}-clientSecrettestInt-clientSecretasdf1234asdf

Use in a Test Suite#

In order to use the Azure Key Vault plugin, you must store your Azure access information as environment variables (either locally or/and define environment variables on azure). These can all be found through the Azure Portal.

export AZURE_CLIENT_ID="generated-app-ID"
export AZURE_CLIENT_SECRET="random-password"
export AZURE_TENANT_ID="tenant-ID"

To validate the environment variables correctly stored:

echo "$AZURE_CLIENT_ID"
echo "$AZURE_CLIENT_SECRET"
echo "$AZURE_TENANT_ID"
describe("Example Azure Key Vault Flow", () => {
let credentials;
before(() => {
cy.getKeyVaultCredentials({
envSuffix: "int",
vault: "hubtests",
user: "demo",
}).then(result => (credentials = result));
});
beforeEach(() => {
cy.login(credentials);
});
after(() => {
cy.logout();
});
});

Commands#

cy.login(options: LoginOptions): Chainable#

Retrieves an int auth token and stores it in local and session storage.

interface LoginOptions {
username: string;
password: string;
clientId: string;
clientSecret: string;
envSuffix: string;
}

cy.logout(): Chainable#

Removes the auth token from storage.

cy.getKeyVaultCredentials(options: GetKeyVaultCredentialOptions): Chainable#

Fetches user credentials stored in an Azure Key Vault.

interface GetKeyVaultCredentialsOptions {
envSuffix: string;
user: string;
vault: string;
}

cy.loginWithKeyVaultCredentials(options: GetKeyVaultCredentialOptions): Chainable#

A helper command that fetches user credentials from a Azure Key and then logins with them.

cy.restoreToken(): Chainable#

Restores the previously fetched auth token into storage.This is only needed for older versions of @iqmetrix/get-authentication-token that do not use @iqmetrix/host-interop

cy.clearAuthToken(): Chainable#

Clears the previously fetched authentication token. The token can no longer be restored.

cy.addAuthInteropHandler(): Chainable#

Registers the host interop handler for get-authentication-token

cy.removeAuthInteropHandler(): Chainable#

Removes the host interop handler for get-authentication-token

cy.addEnvironmentInteropHandler(): Chainable#

Registers the host interop handler for get-environment

cy.removeEnvironmentInteropHandler(): Chainable#

Removes the host interop handler for get-environment

cy.addHostContextInteropHandler(): Chainable#

Registers the host interop handler for get-host-context

cy.removeHostContextInteropHandler(): Chainable#

Removes the host interop handler for get-host-context

cy.addHostInteropHandlers(): Chainable#

Registers all host interop handlers

cy.removeHostInteropHandlers(): Chainable#

Removes all host interop handlers

Sources#

Last updated on by Garrett Smith