Auth0 Actions Testing

Allows you to develop and test Auth0 Actions and Okta CIC Actions locally. This project is not affilliated with Auth0.

This library provides you with the setup to test complex actions. Customise test event payloads using realistic, randomized data. Test Action behaviour such as fetching an external service, providing event secrets, setting metadata, caching data, denying access, redirecting users mid-login, and more. Provides type-hinting to your editor.

The following Flows are supported:

Flow	Support
Login	✓ from v0.1.0
Machine to Machine	✓ from v0.2.0
Password Reset	✓ from v0.2.0
Pre User Registration	✓ from v0.2.0
Post User Registration	✓ from v0.2.0
Post Change Password	✓ from v0.2.0
Send Phone Message	✓ from v0.2.0

Getting started

Switch to an Auth0-compatible version of Node.js

Actions written using both Node 22 LTS and Node 18 LTS are supported by this library. Older Actions are not supported.

If you have a newer version of Node installed, we recommend using a Node version manager such as nvm or n.

1$ node --version
2v22.14.0

Set up your project

Create your project:

1npm init

Add "engines": { "node": "^22.14.0" } to your package.json to enforce the correct version of Node.js:

1{
2  "name": "example",
3  "version": "1.0.0",
4+ "engines": {
5+    "node": "^22.14.0"
6+  }
7}

Install the library:

1npm install @kilterset/auth0-actions-testing --save-dev

Writing your first test

You can write tests with the built-in Node.js Test Runner and assertions.

Here's a simple Action which records a lucky number on the user's app_metadata if they don't already have one:

1// code.js
2exports.onExecutePostLogin = async (event, api) => {
3  const diceRoll = Math.round(Math.random() * event.secrets.MAX_LUCKY_NUMBER);
4  api.user.setAppMetadata("lucky_number", diceRoll);
5};

Let's create a test scenario for this:

1// test.js
2const test = require("node:test");
3const { ok, strictEqual } = require("node:assert");
4
5// Import the action
6const { onExecutePostLogin } = require("./code");
7
8// Import the setup for Node Test Runner
9const { nodeTestRunner } = require("@kilterset/auth0-actions-testing");
10
11test("Lucky Number", async (t) => {
12  // Set up the test context
13  const { auth0 } = await nodeTestRunner.actionTestSetup(t);
14
15  // Each test case needs an `await t.test(...)` call
16  await t.test("records a lucky number", async () => {
17    // Prepare the action, specifying any explicit preconditions.
18    // Any properties you omit will be filled by realistic, random data.
19    const action = auth0.mock.actions.postLogin({
20      secrets: {
21        MAX_LUCKY_NUMBER: 42, // simulate the secrets configured in the Action
22      },
23      user: auth0.mock.user({
24        app_metadata: {},
25        // ...any additional user properties you want to explicitly declare
26      }),
27      // ...other event customisations
28      // request: auth0.mock.request({ ... }),
29      // authentication: auth0.mock.authentication({ ... }),
30      // etc.
31    });
32
33    // Simulate your action
34    await action.simulate(onExecutePostLogin);
35
36    // Test how the user's app_metadata was updatd
37    const { lucky_number } = action.user.app_metadata;
38
39    // Checking equality (see deepStrictEqual for comparing objects)
40    strictEqual(
41      typeof lucky_number,
42      "number",
43      "Expected the user's lucky number to be a number"
44    );
45
46    // Checking truthiness
47    ok(
48      lucky_number >= 0 && lucky_number <= 42,
49      `Expected lucky number to be between 0 and 42 (got ${lucky_number})`
50    );
51  });
52});

Run this test with:

1node --test

(You can set this as your test script command in your package.json.)

For more examples, see the examples directory.

These include testing fetch requests, testing redirect JWTs, and more.

Using require

In Auth0, dependencies are configured in the Action editor.

When testing locally, you'll need to adding the dependency to your package.json first:

1npm install axios --save-dev

Customizing the event

Each event contains realistic, randomized data by default. Each Flow's documentation explains the event object in detail.

The philosophy behind this library is that you are more likely to catch bugs when you randomize data than if you test the same static data each time.

1const action = auth0.mock.actions.postLogin();
2console.log(action.user);

The first time you run this test, you might get:

1{ user_id: 'auth0|978f3d31c89b09fc1e841177', ... }

The second time, you might get:

1{ user_id: 'adfs|822f97ea51247948366e0275', ... }

Some event properties can be optional. On some test runs they will be undefined, on others they might be set to a valid value. Some properties may include variable lists of values. The length of these lists may change each test run.

If the behaviour of your Action depends on a property of the event being a particular value, it should be expliclity defined in your test:

1const action = auth0.mock.actions.postLogin({
2  user: auth0.mock.user({
3    user_id: "an-explicit-id",
4    name: "Barry",
5  }),
6});

In this example, auth0.mock.user will return a user with randomized properties except for user_id and name, which will now always return 'an-explicit-id' and 'Barry' for this test.

Testing api calls

Each Flow's documentation explains the api object in more detail.

Testing is typically done by checking the state of the action after it's run. For example:

1exports.onExecutePostLogin = async (event, api) => {
2  api.access.deny("Nobody is allowed!");
3};

The test:

1const action = auth0.mock.actions.postLogin();
2await action.simulate(onExecutePostLogin);
3
4ok(action.access.denied, "Expected access to be denied");
5match(action.access.denied.reason, /nobody is allowed/i, "Unexpected message");

Take a look at the examples directory or the type hinting on the actions object to learn which properties to assert against.

Working with a0deploy

While you can copy and paste Actions by hand, we recommend exporting and importing Actions with Auth0's a0deploy command-line interface.

Follow the Configure the Deploy CLI guide to get started.

a0deploy can help manage all of your Auth0 configuration, but you may want to limit it to Actions initially. You can optionally do this with the AUTH0_INCLUDED_ONLY option:

1{
2  "AUTH0_DOMAIN": "....auth0.com",
3  "AUTH0_CLIENT_ID": "...",
4  "AUTH0_CLIENT_SECRET": "...",
5  "AUTH0_INCLUDED_ONLY": ["actions"]
6}

Example:

1a0deploy export -c=config.json --format=yaml --output_folder=.

Actions will be stored like this:

.
├── actions
│   ├── My Custom Action 1
│   │   └── code.js
│   └── My Custom Action 2
│       └── code.js
├── config.json
└── tenant.yaml

Follow the Getting Started instructions above to set up the project from here. We recommend adding your the tests alongside the action:

.
└── actions
    └── My Custom Action 1
        ├── code.js
        └── test.js

Running in CI

See our GitHub Actions example.

Contributors

Thanks to the following people who have contributed patches or suggestions:

• bartzwork