Rules Testing Best Practices

The End of Life (EOL) date of Rules and Hooks will be November 18, 2026, and they are no longer available to new tenants created as of October 16, 2023. Existing tenants with active Hooks will retain Hooks product access through end of life.We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public npm packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read Understand How Auth0 Actions Work.To help with your migration, we offer guides that will help you migrate from Rules to Actions and migrate from Hooks to Actions. We also have a dedicated Move to Actions page that highlights feature comparisons, an Actions demo, and other resources to help you on your migration journey.To read more about the Rules and Hooks deprecation, read our blog post: Preparing for Rules and Hooks End of Life.

The provides the facility to TRY a rule for the purpose of testing and debugging. This facility allows a mock user and context object to be defined, which is then passed to the rule as part of its execution. The resulting output from the rule (including any console logging) is displayed upon completion. While this provides an immediate at-a-glance way to unit test a rule, it is very much a manual approach, and one which is unable to leverage the use of automated testing tools such as Mocha or rewire. As a best practice, and as part of the recommended support for the Software Development Life Cycle, you should use a separate test tenant in Auth0 to test any rule/rule changes before deploying to production.

Automation

With the help of a little boilerplate, however, it is possible to implement in a way that enables a rule to be deployed and executed in an Auth0 Tenant and, without modification, to be consumed in any Continuous Integration/Continuous Deployment (CI/CD) automated (unit) testing environment:

const vm = require('vm');
  const fs = require('fs');
  var user = {
      "name":        "jdoe@foobar.com",
      "email":       "jdoe@foobar.com",
      "user_id":     "auth0|0123456789",
          .
          .
    };
  var context = {
      "clientID":            "123456789",
      "clientName":          "MyWebApp",
      "connection":          "MyDbConn",
      "connectionStrategy":  "auth0",
      "protocol":            "oidc-basic-profile",
          .
          .
    };

  global.configuration = {
    DEBUG: true
  };

  vm.runInThisContext(
      "(()=>{return " + fs.readFileSync('./rules/Normalized Profile Claims.js') + " })();", {
        // filename for stack traces
        filename: 'Normalized Profile Claims.js',
        displayErrors: true
      }
  )(
    user,
    context,
    function callback() {
      console.log("Complete");
    }
  );

As shown in the example above, some relatively straightforward testing can be implemented (in an independent node module) by using the Node.js VM to execute the rule to be tested. In this case, a rule named Normalized Profile Claims is read from a file, and some boilerplate is added around the rule (JavaScript) code prior to executing it (the boilerplate being in the strings that both prefix and suffix the filesystem call to read the file containing the rule code). The options object passed on the call to runInThisContext provides information that can be used to assist with debugging in the case where any exceptional error condition(s) may arise. Please see the Node.js documentation for further information regarding this function call. The first two objects passed to the rule during testing represent the user and context objects, and these can be mocked in a fashion similar to that employed in the Auth0 Dashboard TRY functionality. The callback function, supplied as the third parameter, can be implemented to simulate pipeline continuation, subsequently performing execution of the next rule in order. The callback function supplied can be used to ensure execution of the callback is performed at least once by having the (callback) function complete the test and/or provide an assertion. We also recommend providing implementation to also ensure that multiple execution of the callback is not performed by a rule. In addition, the (Node.js) global object can be used to provide both the configuration object and also an instance of the auth0 object if required. In the sample above, a global configuration object has been defined that aligns with recommended practices to assist with debugging (as described in the section above). The sample above also makes use of the file system directory structure provided by Auth0 Deploy CLI—the tooling which can assist with rule deployment.

​Automation

Automation