@121watts/cypress-nextjs-auth0

cypress-nextjs-auth0

Contents

• Installation
• Usage
  • login()
  • logout()
  • Security considerations
• Contributing

Installation

Step 1: Install the addon

yarn add cypress-nextjs-auth0 --dev

Step 2: Import the commands

// cypress/support/index.js

import 'cypress-nextjs-auth0';

Step 2: Register the task

// cypress/plugins/index.js

const encryptTask = require('cypress-nextjs-auth0/encrypt');

module.exports = (on, config) => {
  on('task', encryptTask)
}

Step 3: Create a test user

Create a user in your Auth0 app that you will use specifically for testing.

In security considerations you will see that Auth0 recommends you use separate tenant for each environment (e.g. development, testing, production, etc). Consider creating this test user in a test-specific Auth0 tenant.

You'll need this user's email and password to complete auth0Username and auth0Password in step 4.

Step 4: Add Auth0 credentials

Add the following environment variables using one of Cypress' supported methods (this code example assumes you are using a cypress.env.json file).

Replacing values with your Auth0 application's values:

// cypress.env.json

{
  "auth0Audience": "https://lyft.auth0.com/api/v2/",
  "auth0Domain": "lyft.auth0.com",
  "auth0ClientId": "FNfof292fnNFwveldfg9222rf",
  "auth0ClientSecret": "FNo3i9f2fbFOdFH8f2fhsooi496bw4uGDif3oDd9fmsS18dDn",
  "auth0CookieSecret": "DB208FHFQJFNNA28F0N1F8SBNF8B20FBA0BXSD29SSJAGSL12D9922929D",
  "auth0Password": "mysupersecurepassword",
  "auth0Scope": "openid profile email",
  "auth0SessionCookieName": "appSession",
  "auth0Username": "[e-mail]"
}

Everything except auth0Username and auth0Password should match your app's existing Auth0 settings.

auth0Username and auth0Password are the email and password of the test user you created in step 3.

Step 5: Configure Auth0

Step 5.1: Go to your Auth0 Application settings and enable the Password Grant Type:

Step 5.2: Go to your Auth0 tenant's settings (make sure tenant name is correct in top-left of the page) and set the default directory to Username-Password-Authentication:

If you have changed the name of your default directory (i.e. your tenant's default database name), you should replace Username-Password-Authentication with your database's name, as it's shown in the Auth0 UI. Click on 'databases' in the sidebar of the Auth0 dashboard to view your database(s).

Step 5.3: Add your cypress port URL (e.g. http://localhost:3001) to your Auth0 Application's 'Allowed Origins (CORS)' list:

If you don't yet specify a port when you run Cypress you will need to add a port to your cypress.json file. For example:

// cypress.json

{
  "port": 3001
}

Sometimes user report needing to add disable chromeWebSecurity in Cypress too:

// cypress.json

{
  "port": 3001,
  "chromeWebSecurity": false
}

Usage

The following commands are now available in your test suite:

• login()
• logout()

login()

Property	Type	Default value	Required?
credentials	Object	None	No
credentials.username	String	Cypress.env('auth0Username')	No
credentials.password	String	Cypress.env('auth0Password')	No

Call login at the start of a test. For example:

context('Logging in', () => {
  it('should login', () => {
    cy.login().then(() => {

      // Now run your test...
      cy.request('/api/me').then(({ body: user }) => {
        expect(user.email).to.equal(Cypress.env('auth0Username'));
      });
    });
  });
});

Or in a beforeEach() loop. For example:

context('Logging in', () => {

  beforeEach(() => {
    cy.login();
  })

  it('should login', () => {
    cy.request('/api/me').then(({ body: user }) => {
      expect(user.email).to.equal(Cypress.env('auth0Username'));
    });
  });
});

You can also pass credentials to login():

context('Logging in', () => {
  it('should login', () => {
    cy.login({
      username: '[e-mail]',
      password: 'mygreatpassword',
    }).then(() => {

      // Now run your test...
      cy.request('/api/me').then(({ body: user }) => {
        expect(user.email).to.equal(Cypress.env('auth0Username'));
      });
    });
  });
});

If you want multiple test users, it's recommended to include their credentials in cypress.env.json rather than in your source code.

logout()

cy.logout();

Property	Type	Default value	Required?
returnTo	String	None	No

Call logout() anywhere in a test. For example:

context('Logging out', () => {

  it('should logout', () => {
    cy.login().then(() => {
      cy.visit('/');

      cy.request('/api/me').then(({ body: user }) => {
        expect(user.email).to.equal(Cypress.env('auth0Username'));
      });

      cy.logout();

      cy.request('/api/me', {
        failOnStatusCode: false,
      }).then((response) => {
        expect(response.status).to.equal(401); // Assert user is logged out
      });
    });
  });

});

You can pass a return URL to logout(), which the user will be taken to after a successful logout:

context('Logging out', () => {

  it('should logout', () => {
    cy.login().then(() => {
      cy.visit('/');

      cy.logout('/thanks-for-visiting');
    });
  });
});

You may want to logout after every test:

// cypress/support.index.js

import 'cypress-nextjs-auth0';

beforeEach(() => {
  cy.logout();
})

Security considerations

Use separate tenants

Auth0 recommends you use a separate tenant for each environment (e.g. development, testing, production, etc). This will help mitigate the risk of creating test users.

Therefore, if you don't have a dedicated tenant for your testing environment, it's recommended you create a new tenant and update its setting to match your development environment before following the installation steps.

Storing credentials

Put test credentials in cypress.env.json or a similar place that you can keep out of source control.

If you use cypress.env.json, add the file to your .gitignore and .npmignore files as follows:

# .gitignore

cypress.env.json

Continuous integration

If you use a platform for some of all of CI, like Travis, you will need to keep any sensitive data outside your test logs.

For more info on how to prevent 'leaky' Travis logs, see here.

Contributing

To contribute to this addon, clone the repo:

git clone https://github.com/sir-dunxalot/cypress-nextjs-auth0.git

Install dependencies:

yarn install

Run the dummy app server:

yarn dev

Finally, run the test suite (while the dummy app server is running):

yarn test:ui # or yarn test:headless for no UI

To run the test suites locally you will need to pass some environment variables to Next.js and Cypress...

The easiest way to do this is to add the following two files (they're excluded from source control), but you can also pass their contained environment variables in another way (e.g. export CYPRESS_auth0ClientId=FNfof292fnNFwveldfg9222rf):

• cypress.env.json
• cypress/dummy/.env

To get values for these environment variables you can:

• Open an PR and then ask @sir-dunxalot to share test credentials
• Use values from your own Auth0 test tenant and app (since these files are not check in to source control)
• Create a new (free tier) tenant and application in Auth0 and set it up as documented in the installation steps

If you use your own Auth0 tenant, notice that you need two test users (for auth0Username and auth0UsernameAlt).

Here are the Cypress environment variables (e.g. in cypress.env.json):

// cypress.env.json

{
  "auth0Audience": "https://lyft.auth0.com/api/v2/",
  "auth0Domain": "lyft.auth0.com",
  "auth0ClientId": "FNfof292fnNFwveldfg9222rf",
  "auth0ClientSecret": "FNo3i9f2fbFOdFH8f2fhsooi496bw4uGDif3oDd9fmsS18dDn",
  "auth0CookieSecret": "DB208FHFQJFNNA28F0N1F8SBNF8B20FBA0BXSD29SSJAGSL12D9922929D",
  "auth0Password": "mysupersecurepassword",
  "auth0PasswordAlt": "anothersupersecurepassword",
  "auth0Scope": "openid profile email",
  "auth0SessionCookieName": "appSession",
  "auth0Username": "[e-mail]",
  "auth0UsernameAlt": "[e-mail]"
}

Here are the Next.js app variables (e.g. in cypress/dummy/.env).

# cypress/dummy/.env

AUTH0_CLIENT_SECRET='FNo3i9f2fbFOdFH8f2fhsooi496bw4uGDif3oDd9fmsS18dDn'
AUTH0_SECRET='DB208FHFQJFNNA28F0N1F8SBNF8B20FBA0BXSD29SSJAGSL12D9922929D'

AUTH0_CLIENT_ID='FNfof292fnNFwveldfg9222rf'
AUTH0_AUDIENCE='https://lyft.auth0.com/api/v2/'
AUTH0_SCOPE='openid profile email'
AUTH0_ISSUER_BASE_URL='https://lyft.auth0.com'
AUTH0_BASE_URL='http://localhost:3000'

When you open a PR or push to a branch of this repo, Travis will run tests. You don't need to worry about adding environment variables since they've been added as Travis environment variables already.

Releasing

Project collaborators will build the project and release it using the yarn release command, which passes any params to the release-it package.

For example:

yarn release patch # e.g. 1.0.0 --> 1.0.1
yarn release minor # e.g. 1.0.0 --> 1.1.0
yarn release major # e.g. 1.0.0 --> 2.0.0
yarn release 1.2.4 # e.g. 1.0.0 --> 1.2.4