{"id":20730160,"url":"https://github.com/kilterset/auth0-actions-testing","last_synced_at":"2025-04-23T21:22:20.191Z","repository":{"id":231614189,"uuid":"780672378","full_name":"kilterset/auth0-actions-testing","owner":"kilterset","description":"Test and develop Auth0 Actions or Okta CIC Actions locally. Not affiliated with Auth0.","archived":false,"fork":false,"pushed_at":"2025-03-14T02:54:41.000Z","size":247,"stargazers_count":7,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-28T16:16:05.058Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kilterset.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-02T00:11:05.000Z","updated_at":"2025-02-11T17:59:25.000Z","dependencies_parsed_at":"2024-04-09T06:24:41.374Z","dependency_job_id":"0c446781-8c1b-4ff5-835d-774e3c545798","html_url":"https://github.com/kilterset/auth0-actions-testing","commit_stats":null,"previous_names":["kilterset/auth0-actions-testing"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilterset%2Fauth0-actions-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilterset%2Fauth0-actions-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilterset%2Fauth0-actions-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kilterset%2Fauth0-actions-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kilterset","download_url":"https://codeload.github.com/kilterset/auth0-actions-testing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250515326,"owners_count":21443371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T05:10:02.078Z","updated_at":"2025-04-23T21:22:20.178Z","avatar_url":"https://github.com/kilterset.png","language":"TypeScript","funding_links":[],"categories":["Developer Ecosystem"],"sub_categories":[],"readme":"# Auth0 Actions Testing\n\n[![Published on NPM](https://img.shields.io/npm/v/@kilterset/auth0-actions-testing)](https://www.npmjs.com/package/@kilterset/auth0-actions-testing)\n[![Built by Kilterset](https://img.shields.io/badge/built_by-Kilterset-ff5f16)](https://kilterset.com)\n\nAllows you to develop and test Auth0 Actions and Okta CIC Actions locally. This project is not affilliated with Auth0.\n\nThis library provides you with the setup to test complex actions. Customise test event payloads using realistic, randomized data. Test Action behaviour such as `fetch`ing an external service, providing event secrets, setting metadata, caching data, denying access, redirecting users mid-login, and more. Provides type-hinting to your editor.\n\nThe following [Flows](https://auth0.com/docs/customize/actions/flows-and-triggers) are supported:\n\n| Flow                   | Support       |\n| ---------------------- | ------------- |\n| Login                  | ✓ from v0.1.0 |\n| Machine to Machine     | ✓ from v0.2.0 |\n| Password Reset         | ✓ from v0.2.0 |\n| Pre User Registration  | ✓ from v0.2.0 |\n| Post User Registration | ✓ from v0.2.0 |\n| Post Change Password   | ✓ from v0.2.0 |\n| Send Phone Message     | ✓ from v0.2.0 |\n\n## Getting started\n\n### Switch to an Auth0-compatible version of Node.js\n\nActions written using both Node 22 LTS and Node 18 LTS are supported by this library. Older Actions are not supported.\n\nIf you have a newer version of Node installed, we recommend using a Node version manager such as [`nvm`](https://github.com/nvm-sh/nvm) or [n](https://github.com/tj/n).\n\n```sh\n$ node --version\nv22.14.0\n```\n\n### Set up your project\n\nCreate your project:\n\n```sh\nnpm init\n```\n\nAdd `\"engines\": { \"node\": \"^22.14.0\" }` to your `package.json` to enforce the correct version of Node.js:\n\n```diff\n{\n  \"name\": \"example\",\n  \"version\": \"1.0.0\",\n+ \"engines\": {\n+    \"node\": \"^22.14.0\"\n+  }\n}\n```\n\nInstall the library:\n\n```sh\nnpm install @kilterset/auth0-actions-testing --save-dev\n```\n\n### Writing your first test\n\nYou can write tests with the built-in [Node.js Test Runner](https://nodejs.org/docs/latest-v22.x/api/test.html) and [assertions](https://nodejs.org/docs/latest-v22.x/api/assert.html).\n\nHere's a simple Action which records a lucky number on the user's `app_metadata` if they don't already have one:\n\n```js\n// code.js\nexports.onExecutePostLogin = async (event, api) =\u003e {\n  const diceRoll = Math.round(Math.random() * event.secrets.MAX_LUCKY_NUMBER);\n  api.user.setAppMetadata(\"lucky_number\", diceRoll);\n};\n```\n\nLet's create a test scenario for this:\n\n```js\n// test.js\nconst test = require(\"node:test\");\nconst { ok, strictEqual } = require(\"node:assert\");\n\n// Import the action\nconst { onExecutePostLogin } = require(\"./code\");\n\n// Import the setup for Node Test Runner\nconst { nodeTestRunner } = require(\"@kilterset/auth0-actions-testing\");\n\ntest(\"Lucky Number\", async (t) =\u003e {\n  // Set up the test context\n  const { auth0 } = await nodeTestRunner.actionTestSetup(t);\n\n  // Each test case needs an `await t.test(...)` call\n  await t.test(\"records a lucky number\", async () =\u003e {\n    // Prepare the action, specifying any explicit preconditions.\n    // Any properties you omit will be filled by realistic, random data.\n    const action = auth0.mock.actions.postLogin({\n      secrets: {\n        MAX_LUCKY_NUMBER: 42, // simulate the secrets configured in the Action\n      },\n      user: auth0.mock.user({\n        app_metadata: {},\n        // ...any additional user properties you want to explicitly declare\n      }),\n      // ...other event customisations\n      // request: auth0.mock.request({ ... }),\n      // authentication: auth0.mock.authentication({ ... }),\n      // etc.\n    });\n\n    // Simulate your action\n    await action.simulate(onExecutePostLogin);\n\n    // Test how the user's app_metadata was updatd\n    const { lucky_number } = action.user.app_metadata;\n\n    // Checking equality (see deepStrictEqual for comparing objects)\n    strictEqual(\n      typeof lucky_number,\n      \"number\",\n      \"Expected the user's lucky number to be a number\"\n    );\n\n    // Checking truthiness\n    ok(\n      lucky_number \u003e= 0 \u0026\u0026 lucky_number \u003c= 42,\n      `Expected lucky number to be between 0 and 42 (got ${lucky_number})`\n    );\n  });\n});\n```\n\nRun this test with:\n\n```sh\nnode --test\n```\n\n(You can set this as your `test` script command in your `package.json`.)\n\nFor more examples, see [the examples directory](https://github.com/kilterset/auth0-actions-testing/tree/main/examples).\n\nThese include testing `fetch` requests, testing redirect JWTs, and more.\n\n## Using `require`\n\nIn Auth0, dependencies are configured in the Action editor.\n\nWhen testing locally, you'll need to adding the dependency to your `package.json` first:\n\n```sh\nnpm install axios --save-dev\n```\n\n## Customizing the `event`\n\nEach `event` contains realistic, randomized data by default. Each Flow's [documentation](https://auth0.com/docs/customize/actions/flows-and-triggers) explains the `event` object in detail.\n\nThe 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.\n\n```js\nconst action = auth0.mock.actions.postLogin();\nconsole.log(action.user);\n```\n\nThe first time you run this test, you might get:\n\n```js\n{ user_id: 'auth0|978f3d31c89b09fc1e841177', ... }\n```\n\nThe second time, you might get:\n\n```js\n{ user_id: 'adfs|822f97ea51247948366e0275', ... }\n```\n\nSome 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.\n\nIf the behaviour of your Action depends on a property of the event being a particular value, it should be expliclity defined in your test:\n\n```js\nconst action = auth0.mock.actions.postLogin({\n  user: auth0.mock.user({\n    user_id: \"an-explicit-id\",\n    name: \"Barry\",\n  }),\n});\n```\n\nIn 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.\n\n## Testing `api` calls\n\nEach Flow's [documentation](https://auth0.com/docs/customize/actions/flows-and-triggers) explains the `api` object in more detail.\n\nTesting is typically done by checking the state of the action after it's run. For example:\n\n```js\nexports.onExecutePostLogin = async (event, api) =\u003e {\n  api.access.deny(\"Nobody is allowed!\");\n};\n```\n\nThe test:\n\n```js\nconst action = auth0.mock.actions.postLogin();\nawait action.simulate(onExecutePostLogin);\n\nok(action.access.denied, \"Expected access to be denied\");\nmatch(action.access.denied.reason, /nobody is allowed/i, \"Unexpected message\");\n```\n\nTake a look at [the examples directory](https://github.com/kilterset/auth0-actions-testing/tree/main/examples) or the type hinting on the `actions` object to learn which properties to assert against.\n\n## Working with `a0deploy`\n\nWhile you can copy and paste Actions by hand, we recommend exporting and importing Actions with Auth0's [`a0deploy`](https://auth0.com/docs/deploy-monitor/deploy-cli-tool) command-line interface.\n\nFollow the [Configure the Deploy CLI](https://auth0.com/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli#auth0_included_only) guide to get started.\n\n`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:\n\n```json\n{\n  \"AUTH0_DOMAIN\": \"....auth0.com\",\n  \"AUTH0_CLIENT_ID\": \"...\",\n  \"AUTH0_CLIENT_SECRET\": \"...\",\n  \"AUTH0_INCLUDED_ONLY\": [\"actions\"]\n}\n```\n\nExample:\n\n```sh\na0deploy export -c=config.json --format=yaml --output_folder=.\n```\n\nActions will be stored like this:\n\n```\n.\n├── actions\n│   ├── My Custom Action 1\n│   │   └── code.js\n│   └── My Custom Action 2\n│       └── code.js\n├── config.json\n└── tenant.yaml\n```\n\nFollow the Getting Started instructions above to set up the project from here. We recommend adding your the tests alongside the action:\n\n```\n.\n└── actions\n    └── My Custom Action 1\n        ├── code.js\n        └── test.js\n```\n\n## Running in CI\n\nSee [our GitHub Actions example](https://github.com/kilterset/auth0-actions-testing/blob/main/examples/github-action.yml).\n\n## Contributors\n\nThanks to the following people who have contributed patches or suggestions:\n\n- [bartzwork](https://github.com/bartzwork)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilterset%2Fauth0-actions-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkilterset%2Fauth0-actions-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkilterset%2Fauth0-actions-testing/lists"}