- cypress-nextjs-auth0
- For
@auth0/nextjs-auth0
version^1.0.0
use^2.0.0
of this library (documentation is on main branch) - For
@auth0/nextjs-auth0
version^0.0.0
use^1.0.0
of this library (documentation is here)
yarn add cypress-nextjs-auth0 --dev
// cypress/support/index.js
import 'cypress-nextjs-auth0';
// cypress/plugins/index.js
const encrypt = require('cypress-nextjs-auth0/encrypt');
module.exports = (on, config) => {
on('task', { encrypt });
};
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.
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",
"auth0Scope": "openid profile email",
"auth0SessionCookieName": "appSession",
"auth0LogoutUrl": "/api/auth/logout",
"auth0ReturnToUrl": "/",
"auth0Username": "testuser@lyft.com",
"auth0Password": "mysupersecurepassword"
}
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 6.1: Go to your Auth0 Application settings and enable the Password
Grant Type:
Step 6.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 6.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
}
If you have further customized your Auth0 cookie (see CookieConfig), you have to add the following environment variables to your Cypress configuration:
// cypress.env.json
{
"auth0CookieDomain": "localhost"
"auth0CookiePath": "/",
"auth0CookieHttpOnly": "true",
"auth0CookieCookieSameSite": "lax" ,
"auth0CookieCookieSecure": "true",
"auth0CookieTransient": "false",
}
Please, take a look at the offical documentation for more details.
Make sure you have authorized the @auth0/nextjs-auth0
callback in your tenant
settings Allowed Callback URLs
field:
http://localhost:3000/api/auth/callback
Some developers report needing to disable chromeWebSecurity
in Cypress:
// cypress.json
{
"port": 3001,
"chromeWebSecurity": false
}
The following commands are now available in your test suite:
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/auth/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/auth/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: 'anothertestuser@lyft.com',
password: 'mygreatpassword',
}).then(() => {
// Now run your test...
cy.request('/api/auth/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.
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/auth/me').then(({ body: user }) => {
expect(user.email).to.equal(Cypress.env('auth0Username'));
});
cy.logout();
cy.request({
url: '/api/auth/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. Make sure you have added the returnTo
URL to your Auth0
Application's Allowed Logout URLs
field.
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();
});
cy.clearAuth0Cookies();
Call clearAuth0Cookies()
anywhere in a test. For example:
context('Cookie expires', () => {
it('should logout when cookie expires', () => {
cy.login().then(() => {
cy.visit('/');
cy.request('/api/auth/me').then(({ body: user }) => {
expect(user.email).to.equal(Cypress.env('auth0Username'));
});
// similar to cy.logout() except that it does not redirect the user, it
// can be used to mimic the behaviour of expired cookies.
cy.clearAuth0Cookies();
cy.request({
url: '/api/auth/me',
failOnStatusCode: false,
}).then(response => {
expect(response.status).to.equal(401); // Assert user is logged out
});
});
});
});
cy.preserveAuth0CookiesOnce();
preserveAuth0CookiesOnce()
preserves cookies through multiple tests. It's best
used in the beforeEach
hook. For example:
context('Cookie', () => {
before(() => {
cy.login();
});
beforeEach(() => {
cy.preserveAuth0CookiesOnce();
});
it('user login should preserve cookies', () => {
cy.visit('/');
cy.request('/api/auth/me').then(({ body: user }) => {
expect(user.email).to.equal(Cypress.env('auth0Username'));
});
});
it('user should be logged in still', () => {
cy.visit('/');
// or if you use @testing-library/cypress
// cy.findByTestId('user-email').should(
// 'have.text',
// Cypress.env('auth0Username'),
// );
cy.get('[data-testid="user-email"]').should(e =>
expect(e).to.contain(Cypress.env('auth0Username')),
);
});
});
cypress-nextjs-auth0
automatically preserves cookies between tests.
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.
Put test credentials in cypress.env.json
or a similar place (e.g. .env
) that
you can keep out of source control.
If you use one of those, add the file to your .gitignore
and .npmignore
files as follows:
# .gitignore
.env
cypress.env.json
If you use a platform for some of all of CI, like GitHub Actions, you will need to keep any sensitive data outside your test logs.
For more info on how to prevent 'leaky' logs, see here.
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):
.env
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
AUTH0_USERNAME
and AUTH0_USERNAMEALT
).
Here are the Cypress environment variables (e.g. in .env
):
# .env
# Auth0 Settings
AUTH0_AUDIENCE="https://lyft.auth0.com/api/v2/",
AUTH0_DOMAIN="lyft.auth0.com",
AUTH0_CLIENT_ID="FNfof292fnNFwveldfg9222rf",
AUTH0_CLIENT_SECRET="FNo3i9f2fbFOdFH8f2fhsooi496bw4uGDif3oDd9fmsS18dDn",
AUTH0_SECRET="DB208FHFQJFNNA28F0N1F8SBNF8B20FBA0BXSD29SSJAGSL12D9922929D",
AUTH0_SCOPE="openid profile email",
AUTH0_SESSION_COOKIE_NAME="appSession",
# cypress-nextjs-auth0 settings
AUTH0_LOGOUT_URL="/api/auth/logout"
AUTH0_RETURN_TO_URL="/"
# Cookie Settings
# AUTH0_COOKIE_DOMAIN=
# AUTH0_COOKIE_PATH=
# AUTH0_COOKIE_HTTP_ONLY=
# AUTH0_COOKIE_SAME_SITE=
# AUTH0_COOKIE_SECURE=
# AUTH0_COOKIE_TRANSIENT=
# Test Case Settings
AUTH0_USERNAME="testuser@lyft.com",
AUTH0_PASSWORD="mysupersecurepassword",
AUTH0_USERNAMEALT="testuser@lyft.com"
AUTH0_PASSWORDALT="anothersupersecurepassword",
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, GitHub Actions will run tests. You don't need to worry about adding environment variables since they've been added as Repository Secrets already.
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
Thanks goes to these wonderful people (emoji key):
Duncan Walker π€ π» |
Stefan Natter π» |
Adam Mcgrath π» |
Mark Lawlor π |
This project follows the all-contributors specification. Contributions of any kind welcome!