Unit Test an Action That Uses a Module - Auth0 Docs

Project

Each example separates the action’s source code under src/ from its unit tests under test/, following the same structure across JavaScript and TypeScript projects.

/src

test

/src

test

Action

The following Post Login action imports a custom module to fetch the user’s roles from an external service and sets them as a custom claim on the access token, denying access if the module call fails.

test-an-action-module.js

/** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

const { getRoles } = require('actions:my-module');

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Handler that will be called during the execution of a PostLogin flow.
* 
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  try {
    const { roles } = await getRoles();

api.accessToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
  } catch (err) {
    api.access.deny(err.message);
  }
}

The action requires an Action Module named my-module, which fetches the roles from an external service:

my-module.js

module.exports = {
  /**
   * Returns the user's roles.
   *
   * @returns {{ roles: string[] }} The roles payload.
   */
  getRoles: async () => {
    const response = await fetch(actions.secrets.EVENT_SINK_URL, {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': actions.secrets.EVENT_SINK_API_KEY,
      }
    });

if (!response.ok) {
      throw new Error(`External service responded with status ${response.status}`);
    }

return response.json();
  }
};

test-an-action-module.ts

import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

const { getRoles } = require('actions:my-module');

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

/**
* Handler that will be called during the execution of a PostLogin flow.
* 
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
  try {
    const { roles } = await getRoles();

api.accessToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
  } catch (err) {
    api.access.deny((err as Error).message);
  }
};

The action requires an Action Module named my-module, which fetches the roles from an external service:

my-module.ts

/**
 * Returns the user's roles.
 *
 * @returns The roles payload.
 */
exports.getRoles = async (): Promise<{ roles: string[] }> => {
  const response = await fetch(actions.secrets.EVENT_SINK_URL, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': actions.secrets.EVENT_SINK_API_KEY,
    },
  });

if (!response.ok) {
    throw new Error(`External service responded with status ${response.status}`);
  }

return response.json();
};

Unit Test

The unit tests load the action alongside the custom module and mock fetch to verify roles are set on success, and that access is denied when the external service returns an error status or the request fails with a network error.

Jest

test-an-action-module.spec.js

const { getDefaultArguments, loadAction } = require('@auth0/actions/post-login/v3/test');
const path = require('path');

const DIRNAME = path.dirname('../');
const ACTION_PATH = path.resolve(DIRNAME, './src/test-an-action-module.js');

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

describe('onExecutePostLogin', () => {
  let loader;
  let event;
  let api;

beforeEach(async () => {
    [event, api] = getDefaultArguments();
  });

afterEach(() => {
      jest.resetAllMocks();
  });

it('uses a module to get roles and set them on the access token', async () => {
    loader = await loadAction(ACTION_PATH, [{ name: 'my-module', filename: path.resolve(DIRNAME, './src/my-module.js') }],);

jest.spyOn(api.accessToken, 'setCustomClaim');

jest.spyOn(global, 'fetch').mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => ({ roles: ['admin'] }),
    });

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.accessToken.setCustomClaim).toHaveBeenCalledWith(`${CUSTOM_CLAIM_NAMESPACE}/roles`, ['admin']);
  });

it('denies access when the external service responds with an error', async () => {
    loader = await loadAction(ACTION_PATH, [{ name: 'my-module', filename: path.resolve(DIRNAME, './src/my-module.js') }],);

jest.spyOn(api.access, 'deny');

jest.spyOn(global, 'fetch').mockResolvedValueOnce({
      ok: false,
      status: 500,
    });

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.access.deny).toHaveBeenCalledWith('External service responded with status 500');
  });

it('denies access when fetching roles fails with a network error', async () => {
    loader = await loadAction(ACTION_PATH, [{ name: 'my-module', filename: path.resolve(DIRNAME, './src/my-module.js') }],);

jest.spyOn(api.access, 'deny');

jest.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('Network error'));

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.access.deny).toHaveBeenCalledWith('Network error');
  });
});

Add the test dependencies to package.json

{
  "name": "actions-npm-example-js-jest",
  "version": "1.0.0",
  "description": "Auth0 Actions unit testing example using Jest",
  "license": "MIT",
  "author": "Auth0",
  "type": "commonjs",
  "main": "module-usage.js",
  "scripts": {
    "test": "jest"
  },
  "devDependencies": {
    "@auth0/actions": "^0.33.0",
    "jest": "^30.4.2"
  },
  "jest": {
    "testEnvironment": "node"
  }
}

Configure jsconfig.json so the actions: import alias resolves to src/

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "checkJs": false,
    "baseUrl": ".",
    "paths": {
      "actions:*": ["src/*"]
    }
  },
  "include": ["src/**/*.js"]
}

test-an-action-module.test.ts

const { getDefaultArguments, loadAction } = require('@auth0/actions/post-login/v3/test');
const path = require('path');
const { compileActionModules } = require('./test-utils/load-compiled-action');

const DIRNAME = path.dirname('../');
const ACTION_PATH = path.resolve(DIRNAME, './src/test-an-action-module.ts');
const MODULE_PATH = path.resolve(DIRNAME, './src/my-module.ts');

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

describe('onExecutePostLogin', () => {
  let loader: any;
  let event: any;
  let api: any;

beforeEach(async () => {
    [event, api] = getDefaultArguments();
  });

afterEach(() => {
    jest.resetAllMocks();
  });

it('uses a module to get roles and set them on the access token', async () => {
    const { compiledActionPath, compiledModules } = compileActionModules(ACTION_PATH, [{ name: 'my-module', filename: MODULE_PATH },]);
    loader = await loadAction(compiledActionPath, compiledModules);

jest.spyOn(api.accessToken, 'setCustomClaim');

jest.spyOn(global, 'fetch').mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: async () => ({ roles: ['admin'] }),
    } as any);

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.accessToken.setCustomClaim).toHaveBeenCalledWith(`${CUSTOM_CLAIM_NAMESPACE}/roles`, ['admin']);
  });

it('denies access when the external service responds with an error', async () => {
    const { compiledActionPath, compiledModules } = compileActionModules(ACTION_PATH, [{ name: 'my-module', filename: MODULE_PATH },]);
    loader = await loadAction(compiledActionPath, compiledModules);

jest.spyOn(api.access, 'deny');

jest.spyOn(global, 'fetch').mockResolvedValueOnce({
      ok: false,
      status: 500,
    } as any);

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.access.deny).toHaveBeenCalledWith('External service responded with status 500');
  });

it('denies access when fetching roles fails with a network error', async () => {
    const { compiledActionPath, compiledModules } = compileActionModules(ACTION_PATH, [{ name: 'my-module', filename: MODULE_PATH },]);
    loader = await loadAction(compiledActionPath, compiledModules);

jest.spyOn(api.access, 'deny');

jest.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('Network error'));

await loader.execute('onExecutePostLogin', event, api);

expect(global.fetch).toHaveBeenCalled();
    expect(api.access.deny).toHaveBeenCalledWith('Network error');
  });
});

This test helper compiles the TypeScript action to a temporary file so it can be loaded at runtime:

load-compiled-action.ts

import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import * as ts from 'typescript';

export interface ModuleToCompile {
  name: string;
  filename: string;
}

function transpileToTemp(sourcePath: string): string {
  const source = fs.readFileSync(sourcePath, 'utf8');
  const { outputText } = ts.transpileModule(source, {
    compilerOptions: {
      module: ts.ModuleKind.CommonJS,
      target: ts.ScriptTarget.ES2020,
      esModuleInterop: true,
    },
  });

const tempPath = path.join(
    os.tmpdir(),
    `${path.basename(sourcePath, path.extname(sourcePath))}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.js`,
  );
  fs.writeFileSync(tempPath, outputText);
  return tempPath;
}

/**
 * loadAction() (from @auth0/actions/*\/test) reads its target file from disk and
 * runs it via vm.compileFunction, so it never goes through ts-node/Vitest's own
 * TS transform. Action sources (and any actions:-registered modules) must be
 * transpiled to plain JS on disk first.
 */
export function compileActionModules(actionPath: string, modules: ModuleToCompile[] = []) {
  const compiledActionPath = transpileToTemp(actionPath);
  const compiledModules = modules.map((m) => ({
    name: m.name,
    filename: transpileToTemp(m.filename),
  }));

return { compiledActionPath, compiledModules };
}

Add the test dependencies to package.json

{
  "name": "actions-npm-example-ts-jest",
  "version": "1.0.0",
  "description": "Auth0 Actions unit testing example using Jest and TypeScript",
  "main": "example.ts",
  "scripts": {
    "test": "jest"
  },
  "author": "Auth0",
  "license": "MIT",
  "devDependencies": {
    "@auth0/actions": "^0.33.0",
    "@types/jest": "^29.5.12",
    "@types/node": "22.14.0",
    "jest": "^29.7.0",
    "ts-jest": "^29.1.2",
    "typescript": "^5.9.2"
  }
}

Configure Jest to compile TypeScript with jest.config.js

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
};

Configure tsconfig.json so the actions: import alias resolves to src/

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "outDir": "dist",
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "noEmit": true,
    "paths": {
      "actions:*": ["./src/*"]
    }
  },
  "exclude": ["node_modules","dist"],
  "include": ["**/*.ts"],
  "ts-node": {
    "transpileOnly": true
  }
}

Node.js Test Runner

test-an-action-module.spec.js

const assert = require('node:assert');
const { describe, it, beforeEach, afterEach, mock } = require('node:test');
const { getDefaultArguments, loadAction } = require('@auth0/actions/post-login/v3/test');
const path = require('path');

const DIRNAME = path.dirname('../');
const ACTION_PATH = path.resolve(DIRNAME, './src/test-an-action-module.js');

const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';
describe('onExecutePostLogin', () => {
  let loader;
  let event;
  let api;

beforeEach(async () => {
    [event, api] = getDefaultArguments();
  });

afterEach(() => {
    mock.reset();
  });

mock.method(api.accessToken, 'setCustomClaim');

mock.method(global, 'fetch', async () => ({
      ok: true,
      status: 200,
      json: async () => ({ roles: ['admin'] }),
    }));

await loader.execute('onExecutePostLogin', event, api);

assert.strictEqual(global.fetch.mock.calls.length, 1);
    assert.deepEqual(api.accessToken.setCustomClaim.mock.calls[0].arguments, [`${CUSTOM_CLAIM_NAMESPACE}/roles`, ['admin']]);
  });

mock.method(api.access, 'deny');

mock.method(global, 'fetch', async () => ({
      ok: false,
      status: 500,
    }));

await loader.execute('onExecutePostLogin', event, api);

assert.strictEqual(global.fetch.mock.calls.length, 1);
    assert.deepEqual(api.access.deny.mock.calls[0].arguments, ['External service responded with status 500']);
  });

mock.method(api.access, 'deny');

mock.method(global, 'fetch', async () => {
      throw new Error('Network error');
    });

await loader.execute('onExecutePostLogin', event, api);

assert.strictEqual(global.fetch.mock.calls.length, 1);
    assert.deepEqual(api.access.deny.mock.calls[0].arguments, ['Network error']);
  });
});

Add the test dependencies to package.json

{
  "name": "actions-npm-example-js-node-test",
  "version": "1.0.0",
  "description": "Auth0 Actions unit testing example using the Node.js built-in test runner",
  "license": "MIT",
  "author": "Auth0",
  "type": "commonjs",
  "main": "module-usage.js",
  "scripts": {
    "test": "node --test src/*.spec.js"
  },
  "devDependencies": {
    "@auth0/actions": "^0.33.0"
  }
}

Configure jsconfig.json so the actions: import alias resolves to src/