Unit Testing on Stuart Forrest

Unit testing Auth0 custom database Action Scripts

Sun, 19 Sep 2021 15:10:12 +0000

I recently wrote about unit testing Cloudfront Functions which presented some challenges. This post is about unit testing Auth0 Action Scripts when using a custom database, which also presented some similar challenges but had a different solution.

What is Auth0?

Auth0 is an Identity-as-a-service (IaaS) provider.

What is a custom database and when would I use one?

When using Auth0 there is the facility to create one or more user databases that store users authenticating with a username/password combination (link). Should you need to, these stores can be connected to an external database that (presumably) you already control. A custom database is a database not controlled by Auth0, likely a SQL database but it doesn’t actually matter - it doesn’t really have to be a database at all, just return users.

The most likely use for a custom database is probably going to be lazily migrating users from an old identity provider to Auth0. Lazy migration will allow users to be moved over to Auth0 at the point of login without needing to change their password (link). Another use for a custom database is to not use Auth0 for storing users at all (link) but just to handle the authentication flows, I would expect this to be a less common usage but Auth0 facilitate it.

What is an Action Script and why are they are hard to unit test?

An Action Script is some custom code that is deployed into Auth0, it will be invoked under certain scenarios (eg. when a user logs in, link). There are various points at which Auth0 functionality can be extended/augmented in this way (rules, hooks, actions) and they all behave in slightly different ways (it’s a little frustrating). This post focuses on Action Scripts in the context of using a custom database.

The runtime in which these Action Scripts execute has some restrictions that your code must operate within (link). The relevant (and undocumented) one for this post is that top-level exports are not allowed. This makes structuring your code to facilitate unit testing a little tricky.

Effectively, neither of the following approaches will work:

export function handler() {
 // do something here
}

module.exports = {
 handler
}

The first approach using export will cause a syntax error and trying to access module will fail.

An approach to unit testing them Auth0 custom database Action Scripts

My approach to testing Cloudfront Functions using the rewire module is a possible solution to unit testing Auth0 custom database Action Scripts. It is not the one I used though, this is because if I can get away with not bringing in additional dependencies then that is desirable. Rewire is also a pretty invasive module that (I assume) fiddles with the inner workings of node’s module resolution process, which is a bit much if we don’t have to do it.

Whilst top-level exports are not permitted and module is undefined when accessed at the top-level, module is, surprisingly, available outside of the global scope. This is a perfect use case for an Immediately Invoked Function Expressions (IIFE). An IIFE is essentially a function that is run immediately after it has been defined but bounded in () that isolates its scope from the outer scope. This means it will be immediately invoked when the module is imported into the runtime which Auth0 has to do at some point to execute the code.

Taking advantage of these Javascript capabilities my first pass at writing a unit-testable Action Script looked something like this:

(() => {
 const doStuff = function() {
 console.log("handler ran");
 }

 if (module) {
 module.exports = {
 doStuff,
 }
 }

 return doStuff;
})()

The thinking was that because module is not available in the global scope, it isn’t available in the runtime at all. To account for this the exports are only set if module is defined, this means that when my unit tests attempt to import this module doStuff is importable. But when the module is executed in the Auth0 runtime trying to manipulate exports shouldn’t cause a runtime error and doStuff is available as an (almost) top level function.

This worked, handler ran is logged to the terminal in Auth0 when I tested it. Job done? Yes, and no. I pushed it a bit further and removed the conditional testing of module like so:

(() => {
 const doStuff = function() {
 console.log("handler ran");
 }

 module.exports = {
 doStuff,
 }

 return doStuff;
})()

I was very surprised when this worked, there were no runtime errors when I tested it in Auth0 and handler ran was logged to the terminal. I’m not really sure what is going on here, module not being available in the runtime is inconvenient but consistent. Whereas, module just not being available in the global scope is a little weird.

Auth0 do have a keen interest in securing the runtime for these custom database Action Scripts which is awesome, for example they vet third party modules to include in the runtime (link). Perhaps the behaviour witnessed is security related and they didn’t want exporting to be allowed (a la Cloudfront Functions), perhaps module being available in a nested scope is not intentional. It is though, and in this instance I took advantage of it.

Summary

Auth0 custom database Action Scripts exhibit some slightly odd runtime behaviour but with a little experimentation and taking advantage of some not always very useful Javascript features like IIFEs unit testing them was doable. Structuring your code a certain way to facilitate unit testing, as was the case here, I don’t consider a bad thing. Code that is hard to test is usually too complex or unobservable, if unit testing code helps to reduce the complexity, break it up or make it more observable then I consider that a good thing.

Get in contact

If you have comments, questions or better ways to do anything that I have discussed in this post then please get in contact via LinkedIn or email.

Unit testing Cloudfront Functions

Fri, 10 Sep 2021 07:13:47 +0000

I’ve recently taken an interest in Cloudfront Functions and started using them for some of this sites functionality. To read more about what I’ve been doing check out these posts that capture my experience so far:

This post is about my approach to unit testing the Cloudfront Function code which was a little challenging.

What are Cloudfront Functions?

Cloudfront Functions, whilst not a successor to Lambda@Edge, are an evolution of them. Whereas Lambda@Edge allows fully fledged lambda functions to run within a regional edge cache (AWS region) closest to the request origin, Cloudfront Functions run right at the edge where the content is ideally going to be served from. In terms of Cloudfront architecture you cannot get closer to the user. There are some restrictions to Cloudfront Functions you have to bear in mind like having a limited runtime, execution time, memory allowance, package size and that they are javascript only with no network access.

Why are Cloudfront Functions hard to unit test?

Because there are no exports allowed. There are a bunch of restrictions within the Cloudfront Function runtime as highlighted, but it is the lack of any kind of export support that makes it difficult. This will work:

function handler() {
 // do something here
}

but any attempt at exporting will cause a runtime error when the Cloudfront Function is run. So anything akin to the following wont work:

export function handler() {
 // do something here
}

module.exports = {
 handler
}

Even this wont work, which surprised me:

export function handler() {
 // do something here
}

if (module) {
 module.exports = {
 handler
 }
}

If you cannot export a function (or import one) how can you test it in another file using a library like jest? Ordinarily you don’t want to test functions that are not exported because the public interface of a module (its exported functions) are the testing target - testing anything else becomes brittle and tests implementation as opposed to behaviour. I’ve not wanted to be able to this before but Cloudfront Functions are my special case!

What are the options?

I considered a few approaches to facilitate unit testing my Cloudfront Functions that I realised wouldn’t work or I didn’t like for various reasons:

Exporting a string template of the function body and then creating a Function object with it in both my Cloudfront Function at runtime and in my tests. Whilst this would work great for the testing part the Function class is not available in the Cloudfront Function runtime. Even if it worked there would be no support in VSCode for syntax highlighting etc. making the development experience unpleasant.
The function code was being placed inline in my Cloudformation template as required (covered here). This meant I could use sed or some regex/replacing to remove any export statements. This would have worked but felt too brittle and I also thought it would be confusing to mix supported and unsupported features in the file without much context.
Duplicate the code both in the Cloudformation template and again in a test file. This is possible but ensuring that when one is updated so is the other will inevitably lead to them going out of sync at some point even with the best intentions.
Use babel to transpile the code to something supported, unfortunately no form of exporting at all is allowed.
Don’t unit test it. This would work but if not unit testing something is the easy option (when isn’t it?!) it should probably be unit tested as there is some inherent complexity or lack of observability there. Also, it was a challenge by now that I wanted to solve and would undoubtedly learn something along the way.

An approach to unit-testing Cloudfront Functions

First I came across the rewire module but that only supports up to ES5 syntax and Cloudfront Functions blends syntax/features support from ES5, ES6, ES7 and beyond. Looking further afield I found a babel plugin called babel-plugin-rewire that brings the approach of rewire a bit more up to date.

My babel config looks like this:

module.exports = {
 presets: [["@babel/preset-env", { targets: { node: "current" } }]],
 // Only invoke rewire when tests are running
 plugins: process.env.NODE_ENV === "test" ? ["rewire"] : [],
};

I only want the plugin to run in a test environment, it takes quite invasive actions and I don’t want the possible side effects of that anywhere near production code. If I had more things to test (I don’t) I could also target the plugin only at my Cloudfront Function test files.

And my test setup looks like this:

import myModule from "./myModule";

describe("myModule tests", () => {
 it("should do some stuff", () => {
 // Arrange
 // Get unexported function
 const unexportedFunc = myModule.__get__("functionName");

 // Act
 const res = unexportedFunc();

 // Assert some stuff
 });
});

The benefits

Though the Cloudfront Function runtime still restricts the syntax and features that I use this babel-plugin-rewire gives me a decent amount more flexibility with how I can write the functions.

Using the approach of rewire means that I have what is hopefully a reliable and supported method of testing my functions in this way. When reading around I came across suggestions of reading the string contents of the file and using eval or Node’s vm to run it. This seems brittle, makes test setup pretty complex and are harder to reason about when I come back to the test code.

Some downsides

Babel had to be added to the project which is considerably more complex than adding the average dependency. Ideally that wouldn’t have been required, particularly as it is only being used by jest to run tests. Having said that, babel wasn’t really a necessity as I could have written my functions in entirely ES5 syntax but I didn’t want to. I value the developer experience as well as the speed and ease with which I can make changes to the site as required, this felt like the best way to facilitate both of those things.

Not all functions can be accessed even when using this approach and I don’t know why. The only mention I’ve found of this is this issue but there is no official response or progress. If super simple/light functions are untestable they are hopefully simple enough that the value of unit testing them is minimal. Testing them by testing other code that consumes them shouldn’t add too much complexity.

Summary

It took some reading and thinking around the problem to figure out the best way to unit test my Cloudfront Functions but I’ve implemented a solution I’m happy with. I’ve not worked on any commercial projects that have utilised Cloudfront Functions yet but hopefully save some time with this approach than having to solve the same challenge.

Get in contact

If you have comments, questions or better ways to do anything that I have discussed in this post then please get in contact via LinkedIn or email.