Auth0 Actions ユニットテスト

Actions NPM (@auth0/actions) パッケージを使用すると、外部プロジェクトでTypeScriptによる開発が可能になり、開発者はベストプラクティスに従いながら、TypeScriptの型定義に基づいてユニットテストを改善できます。

仕組み

インストールとインポートのガイドラインについては、How Actions NPM works を参照してください。 Action の単体テストを行うには、Action 関数が受け取る event オブジェクトと api オブジェクトをモックする必要があります。これらのモックは、auth0/actions に含まれる TypeScript の定義を使って作成できるため、テストで本番環境を正確に再現できます。モックや機能のテストを管理するには、Jest のようなテストフレームワークが適しています。単体テストは、ローカル環境、バージョン管理環境、または CI/CD プロセスで実行できるため、Auth0 テナントに影響する変更を加える前の品質保証と検証を全体として強化できます。

例

以下の例では、必要なオブジェクトをモック化して、さまざまなシナリオを検証します。

これらの例では Jest (https://www.npmjs.com/package/jest) を使用していますが、テストライブラリはどれでも使用できます。

設定

package.json では、Action の作成時に IntelliSense の支援を受けられるよう、開発用の依存関係を定義します。

Javascript
TypeScript

{
  "name": "actions-js",
  "version": "1.0.0",
  "description": "Actions JS",
  "main": "example.js",
  "scripts": {
    "test": "jest"
  },
  "author": "John Doe",
  "license": "ISC",
  "devDependencies": {
    "@auth0/actions": "^0.7.1",
    "jest": "^29.7.0"
  }
}

{
  "name": "actions-ts",
  "version": "1.0.0",
  "description": "Actions TS",
  "main": "example.ts",
  "scripts": {
    "test": "jest"
  },
  "author": "John Doe",
  "license": "ISC",
  "devDependencies": {
    "@auth0/actions": "^0.7.1",
    "@types/jest": "^29.5.12",
    "@types/node": "22.14.0",
    "jest": "^29.7.0",
    "ts-jest": "^29.1.2",
    "typescript": "^5.9.2"
  }
}

tsconfig.json ファイルでは、TypeScript コンパイラの動作を定義します。

{
  "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
  },
  "include": [
    "**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

jest.config.js では、Jest の環境プリセットを定義します。

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

事前ユーザー登録時のアクセス制御とユーザーメタデータの設定

次の Action の例では、ユーザーのメールアドレスが禁止されたメールドメインかどうかを確認し、一致した場合は api.access.deny() を呼び出します。一致しない場合は、Custom Prompts の追加フィールドで氏名が指定されているかを確認し、指定されていればその氏名をユーザープロファイルの user_metadata に設定します。指定されていない場合は、Universal Login にバリデーションエラーを返します。

JavaScript
TypeScript

/** @import {Event, PreUserRegistrationAPI} from "@auth0/actions/pre-user-registration/v2" */

/**
* PreUserRegistration フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - 登録を試みているユーザーとコンテキストの詳細。
* @param {PreUserRegistrationAPI} api - サインアップの動作を変更するためのメソッドを提供するインターフェース。
*/
exports.onExecutePreUserRegistration = async (event, api) => {
  const user = event.user;

  if (user.email?.endsWith('@example.com')) {
    api.access.deny('forbidden', 'Forbidden email domain')
    return;
  }

  const fullName = event.request.body['ulp-fullName'];

  if (fullName === undefined) {
    api.validation.error('invalid_payload', 'Missing full name');
    return;
  }

  api.user.setUserMetadata('full_name', fullName);
}

import type { Event, PreUserRegistrationAPI } from '@auth0/actions/pre-user-registration/v2';

/**
* PreUserRegistration フローの実行中に呼び出されるハンドラー。
*
* @param {Event} event - 登録を試みているユーザーとコンテキストの詳細。
* @param {PreUserRegistrationAPI} api - サインアップの動作を変更するためのメソッドを提供するインターフェース。
*/
exports.onExecutePreUserRegistration = async (event: Event, api: PreUserRegistrationAPI) => {
  const user = event.user;

  if (user.email?.endsWith('@example.com')) {
    api.access.deny('forbidden', 'Forbidden email domain')
    return;
  }

  const fullName = event.request.body['ulp-fullName'];

  if (fullName === undefined) {
    api.validation.error('invalid_payload', 'Missing full name');
    return;
  }

  api.user.setUserMetadata('full_name', fullName);
};

このユニットテストでは、event オブジェクトと api オブジェクトをモック化して、コードカバレッジを最大化するための検証をいくつか行います。

Javascript
TypeScript

const { onExecutePreUserRegistration } = require('./preUserRegistration');

describe('onExecutePreUserRegistration', () => {
  const mockApi = {
    access: {
      deny: jest.fn(),
    },
    user: {
      setUserMetadata: jest.fn(),
    },
    validation: {
      error: jest.fn(),
    },
  };

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

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

  it('forbids email domain', async () => {
    const mockEvent = {
      user: {
        email: 'johndoe@example.com',
      }
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).toHaveBeenCalledWith('forbidden', 'Forbidden email domain');
    expect(mockApi.validation.error).not.toHaveBeenCalled();
    expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
  });

  it('allows email domain without full name', async () => {
    const mockEvent = {
      request: {
        body: {},
      },
      user: {
        email: 'johndoe@test.com',
      },
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).not.toHaveBeenCalled();
    expect(mockApi.validation.error).toHaveBeenCalledWith('invalid_payload', 'Missing full name');
    expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
  });

  it('allows email domain with full name', async () => {
    const mockEvent = {
      request: {
        body: {
          'ulp-fullName': 'John Doe'
        },
      },
      user: {
        email: 'johndoe@test.com',
      },
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).not.toHaveBeenCalled();
    expect(mockApi.validation.error).not.toHaveBeenCalled();
    expect(mockApi.user.setUserMetadata).toHaveBeenCalledWith('full_name', 'John Doe');
  });
});

const { onExecutePreUserRegistration } = require('./preUserRegistration');

describe('onExecutePreUserRegistration', () => {
  const mockApi = {
    access: {
      deny: jest.fn(),
    },
    user: {
      setUserMetadata: jest.fn(),
    },
    validation: {
      error: jest.fn(),
    },
  };

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

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

  it('forbids email domain', async () => {
    const mockEvent = {
      user: {
        email: 'johndoe@example.com',
      }
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).toHaveBeenCalledWith('forbidden', 'Forbidden email domain');
    expect(mockApi.validation.error).not.toHaveBeenCalled();
    expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
  });

  it('allows email domain without full name', async () => {
    const mockEvent = {
      request: {
        body: {},
      },
      user: {
        email: 'johndoe@test.com',
      },
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).not.toHaveBeenCalled();
    expect(mockApi.validation.error).toHaveBeenCalledWith('invalid_payload', 'Missing full name');
    expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
  });

  it('allows email domain with full name', async () => {
    const mockEvent = {
      request: {
        body: {
          'ulp-fullName': 'John Doe'
        },
      },
      user: {
        email: 'johndoe@test.com',
      },
    };

    await onExecutePreUserRegistration(mockEvent, mockApi);

    expect(mockApi.access.deny).not.toHaveBeenCalled();
    expect(mockApi.validation.error).not.toHaveBeenCalled();
    expect(mockApi.user.setUserMetadata).toHaveBeenCalledWith('full_name', 'John Doe');
  });
});

カスタムメールプロバイダーとHTTPリクエスト

次のActionの例では、HTTPリクエストを使用して外部サービスにメッセージを送信し、リクエストエラーが発生した場合は通知を破棄するように処理しています。外部サービスのURLと認証用APIキーにはsecretsを使用します。

Javascript
TypeScript

/** @import {Event, CustomEmailProviderAPI} from "@auth0/actions/custom-email-provider/v1" */

/**
* メール通知の送信時に実行されるハンドラー
*
* @param {Event} event - ユーザーの詳細と、そのユーザーがログインしているコンテキスト。
* @param {CustomEmailProviderAPI} api - メール通知の送信動作を変更するためのメソッドとユーティリティ。
*/
exports.onExecuteCustomEmailProvider = async (event, api) => {
  const notification = event.notification;
  const message = {
    body: notification.html
  };

  try {
    await fetch(event.secrets.URL, {
      method: 'POST',
      headers: {
        'X-API-Key': event.secrets.API_KEY,
      },
      body: JSON.stringify(message),
    });
  } catch (err) {
    api.notification.drop('External service failure');
  }
}

/** @import {Event, CustomEmailProviderAPI} from "@auth0/actions/custom-email-provider/v1" */

/**
* メール通知の送信時に実行されるハンドラー
*
* @param {Event} event - ユーザーの詳細と、そのユーザーがログインしているコンテキスト。
* @param {CustomEmailProviderAPI} api - メール通知の送信動作を変更するためのメソッドとユーティリティ。
*/
exports.onExecuteCustomEmailProvider = async (event, api) => {
  const notification = event.notification;
  const message = {
    body: notification.html
  };

  try {
    await fetch(event.secrets.URL, {
      method: 'POST',
      headers: {
        'X-API-Key': event.secrets.API_KEY,
      },
      body: JSON.stringify(message),
    });
  } catch (err) {
    api.notification.drop('External service failure');
  }
}

このUnit Testでは、コードカバレッジを最大化するために、fetch関数に加えてeventオブジェクトとapiオブジェクトをモック化し、いくつかの検証を行います。

Javascript
TypeScript

const { onExecuteCustomEmailProvider } = require('./customEmailProvider');

describe('onExecuteCustomEmailProvider', () => {
  const mockApi = {
    notification: {
      drop: jest.fn(),
    },
  };

  const mockEvent = {
    notification: {
      html: '<h1>Hello world</h1>',
    },
    secrets: {
      URL: 'https://example.com/service',
      API_KEY: 'ApiKeySecret1234.',
    },
    user: {
      email: 'johndoe@example.com',
    },
  };

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

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

  it('succeeds on external service request', async () => {
    jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.resolve({
      ok: true,
      status: 200,
      json: async () => ({ message: 'Success!' }),
    }));

    await onExecuteCustomEmailProvider(mockEvent, mockApi);

    expect(global.fetch).toHaveBeenCalled();
    expect(mockApi.notification.drop).not.toHaveBeenCalled();
  });

  it('fails on external service request', async () => {
    jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.reject({
      ok: false,
      status: 500,
      json: async () => ({ error: 'Server Error' }),
    }));

    await onExecuteCustomEmailProvider(mockEvent, mockApi);

    expect(mockApi.notification.drop).toHaveBeenCalledWith('External service failure');
  });
});

const { onExecuteCustomEmailProvider } = require('./customEmailProvider');

describe('onExecuteCustomEmailProvider', () => {
  const mockApi = {
    notification: {
      drop: jest.fn(),
    },
  };

  const mockEvent = {
    notification: {
      html: '<h1>Hello world</h1>',
    },
    secrets: {
      URL: 'https://example.com/service',
      API_KEY: 'ApiKeySecret1234.',
    },
    user: {
      email: 'johndoe@example.com',
    },
  };

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

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

  it('succeeds on external service request', async () => {
    jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.resolve({
      ok: true,
      status: 200,
      json: async () => ({ message: 'Success!' }),
    } as Response));

    await onExecuteCustomEmailProvider(mockEvent, mockApi);

    expect(global.fetch).toHaveBeenCalled();
    expect(mockApi.notification.drop).not.toHaveBeenCalled();
  });

  it('fails on external service request', async () => {
    jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.reject({
      ok: false,
      status: 500,
      json: async () => ({ error: 'Server Error' }),
    } as Response));

    await onExecuteCustomEmailProvider(mockEvent, mockApi);

    expect(mockApi.notification.drop).toHaveBeenCalledWith('External service failure');
  });
});

@auth0/actions の詳細は、https://www.npmjs.com/package/@auth0/actions を参照してください。 Actions の作成方法について詳しくは、初めての Action を作成するをご覧ください。

ブランドのカスタマイズ

コードのカスタマイズ

サードパーティによるカスタマイズ

Actions ユニットテスト

Auth0 Actions ユニットテスト

仕組み

例

設定

事前ユーザー登録時のアクセス制御とユーザーメタデータの設定

カスタムメールプロバイダーとHTTPリクエスト

​Auth0 Actions ユニットテスト

​仕組み

​例

​設定

​事前ユーザー登録時のアクセス制御とユーザーメタデータの設定

​カスタムメールプロバイダーとHTTPリクエスト

Auth0 Actions ユニットテスト

仕組み

例

設定

事前ユーザー登録時のアクセス制御とユーザーメタデータの設定

カスタムメールプロバイダーとHTTPリクエスト