Testing and developing Auth0 Actions locally
While developing a recent Auth0 Marketplace Action, we built a test framework for Auth0 Actions to make sure the integration met our standards for quality, reliable, maintainable code. Today, we’re open-sourcing that effort as the Auth0 Actions Testing library (NPM, GitHub) to help you test and develop Auth0 and Okta CIC Actions locally.
Auth0’s Action authoring experience today
Auth0 Actions allow you to execute custom JavaScript code when particular events occur in Auth0, such as when a user logs in. Auth0 offers an in-browser editing experience for developers to write custom code. It’s a solid effort, but one with room for improvement.
Here’s my report card, from best to worst:
- Code completion: A. A thorough set of TypeScript definitions provide useful hinting and completion while writing Actions.
- Management via API: A. You can create, update, delete, run, and deploy Actions effectively through the Management API.
- Editing experience: B. The editor is based on Visual Studio Code and offers an excellent in-browser experience. At the end of the day, though, any developer will take working with their preferred desktop editor and tools over typing code into a browser. (For those of us who work on laptop screens, it also badly needs more screen real-estate.)
- Version control and releases: B. Auth0 provides support for saving drafts, deploying changes when ready, and simple version history.
- Language and runtime: C. Although they provide TypeScript definitions for code completion, you can only write your Action in plain JavaScript. They’re also behind the times on Node.js versions. The most recent Long Term Support (LTS) version you can write an Auth0 Action in is v18, which was released two years ago. The current LTS version is v20 and its successor v22 is due out later this year. Surprisingly, you can still create a new Action using v16 or v14, both of which are no longer officially supported by the Node.js team.
- Debugging: C. Limited to
console.log
and trial-and-error. The Node.js debugger is not available. - Testing: D. A “Test” tab with a “Run” button allows you to execute your code using a simulated event. With close reference to the documentation, you can modify the event payload to test behaviour, but changes to the payload are forgotten when you leave the page.
Overall, I think Auth0 have done an admirable job, especially compared to peers. As an engineer, though, I’m missing some key tools that let me develop robust solutions. Chief among those is the ability to develop a test suite alongside the working code. Auth0 suggests a path to unit testing, but leaves the work of mocking the API and event data as an exercise to the reader.
Introducing the Auth0 Actions Testing library
The design goal for this library was to improve the development experience by providing tools and conveniences that allow engineers to develop and test Auth0 Actions locally.
Using the library you can:
- Write code using your own editor, while continuing to get code completion and type hinting
- Keep a robust test suite alongside your code
- Work with realistic, randomized, and customizable
event
payloads - Use the built-in Node.js debugger to diagnose issues
- Keep your code in source control (e.g. Git)
- Run your tests in CI tool like GitHub Actions
- Work with existing tools like
a0deploy
Take a look at the Auth0 Actions Testing library README to see examples and get started.
Improving the developer experience
After using the library, I think you’ll see a big improvement in your Actions authoring experience:
- Editing experience: B → A-. Bring your own editor and environment. (This is an “A-” for now because type hinting is currently limited to tests rather than code, although we’re working on it.)
- Version control and releases: B → A. Use the full power of version control software. Incorporate Pull Requests and CI testing into your Actions release cycle.
- Debugging: C → B. Use the Node.js debugger to inspect breakpoints during local development and test runs. (An “A” here would be being able to do this while testing Actions on Auth0 itself.)
- Testing: D → A. Your Actions can be thoroughly tested and changes can be made more safely. Tests are fast and can be run in a CI/CD pipeline.
Feedback welcome
The paint is still drying on this library. We’ve been testing it internally and are happy with our experience, but we’d love to hear yours. Send us feedback or feature requests via GitHub Issues.