Forem: Daniel

Writing Shared Scripts for CircleCI Orbs

Daniel — Wed, 10 Aug 2022 05:09:00 +0000

This article was originally published on my blog here.

Problem

CircleCI Orbs provide an include directive that can be used to include scripts in an orb's command configurations. Unfortunately, this directive doesn't provide an obvious way of referencing other, shared scripts from within the included script.

In fact, it turns out the include directive is just a macro that prompts CircleCI to replace the include directive with the text body of the referenced script. This means that other scripts included with the include directive are not reference-able in a direct way, making shared scripting modules difficult to create.

Motivation

Lately I've been centralizing DevOps tooling for my projects in a custom CircleCI Orb. The orb is meant to abstract away typical actions on standardized repos that I plan to create for current and future projects.

I've been working on a monorepo generator using an Nx plugin with a custom workspace preset. For test coverage reports with Codecov integration, I'd like to dynamically upload one coverage report per package in my monorepo and assign a matching Codecov flag to it.

Unfortunately, the official Codecov CircleCI Orb isn't quite powerful enough to handle this use case on its own, so I ended up poaching some of their scripts to create something that understands an Nx workspace configuration and automatically perform the coverage upload segmented by package.

In the process, I wanted the ability to write shared scripts with functions that could get re-used in other scripts, allowing me to write more modular and testable scripts and allowing me to DRY up my scripts.

Solution

Fortunately, the include directive can be used anywhere in an orb's configurations, not just within the command property of a step.

I can even use an include directive to provide the body of my shared script as an environment variable to some other command.

Not recommended: `eval` the body of the shared script

My first pass at solving this issue was to use include to provide the body of my shared script as an environment variable, and then eval those contents.

Obviously, this isn't the safest, and use of eval in this way is a bit of a smell. However, it did solve the problem.

src/commands/upload-monorepo-coverage.yml:

steps:
  - run:
      name: Upload Monorepo Coverage Results
      command: << include(scripts/uploadMonorepoCoverageResults.sh) >>
      environment:
        PARSE_NX_PROJECTS_SCRIPT: << include(scripts/parseNxProjects.sh >>

src/scripts/parseNxProjects.sh:

#! /usr/bin/env bash

# A common function I'd like to use in another file
parse_nx_projects() {
  # ...
}

src/scripts/uploadMonorepoCoverageResults.sh:

#! /usr/bin/env bash

eval "$PARSE_NX_PROJECTS_SCRIPT"

# This shared function from the `parseNxProjects.sh` is now callable
parse_nx_projects

# ...

Slightly better: writing the contents of the shared script to disk

Using eval in the way above offended my sensibilities. Though I'm not convinced it's actually more secure, I ended up with a different approach inspired by the eval approach. That is, using the include directive, I write the contents of the shared script to somewhere predictable on disk, then provide the path to the shared script to any scripts that need to consume it.

This way I'm able to use source to read my shared functions, which feels a little better.

I wrote a specific command to handle this for me, which I called write-shared-script.

This is what the source of the command looks like:

description: >
  This command writes shared scripts to disk so they can be consumed by other scripts

parameters:
  script-dir:
    type: string
    default: ~/@chiubaka/circleci-orb/scripts
    description: Path to the directory to write shared scripts to.
  script-name:
    type: string
    description: Name of the script to write
  script:
    type: string
    description: The script to write. Should be included here using the include directive.

steps:
  - run:
      name: Write << parameters.script-name >> to disk
      command: << include(scripts/writeSharedScript.sh) >>
      environment:
        SCRIPT: << parameters.script >>
        SCRIPT_DIR: << parameters.script-dir >>
        SCRIPT_NAME: << parameters.script-name >>

And here's writeSharedScript.sh:

#! /usr/bin/env bash

SCRIPT_PATH="$SCRIPT_DIR/$SCRIPT_NAME"

mkdir -p "$SCRIPT_DIR"
echo "$SCRIPT" > "$SCRIPT_PATH"
chmod +x "$SCRIPT_PATH"

Now the steps of the command that requires the shared script look more like this:

  - write-shared-script:
      script-name: parseNxProjects.sh
      script: << include(scripts/parseNxProjects.sh) >>
  - run:
      name: Upload Monorepo Coverage Results
      command: << include(scripts/uploadMonorepoCoverageResults.sh) >>
      environment:
        PARSE_NX_PROJECTS_SCRIPT: ~/@chiubaka/circleci-orb/scripts/parseNxProjects.sh

Finally, the uploadMonorepoCoverageResults.sh script now looks like this:

#! /usr/bin/env bash

source "$PARSE_NX_PROJECTS_SCRIPT"

# This shared function from the `parseNxProjects.sh` is now callable
parse_nx_projects

# ...

Security Considerations

Arguably, in the context of CircleCI the difference between these two approaches isn't huge. Realistically, the input to eval here is always in my control so long as CircleCI is working normally. If there were to be a security breach in CircleCI allowing an attacker access to control the input of this eval statement, then there's a bigger problem here dealing with an entirely different threat model.

Technically, if an attacker could control the input of that eval statement, that same attacker could likely control the contents of the shared script on disk, which would amount to an attack of similar gravity.

Still, it feels better to avoid the cardinal sin of using eval, and at least this way my orb scripts are a bit more debuggable in production, since the shared scripts are written to disk.

Faithful E2E Testing of Nx Preset Generators

Daniel — Tue, 02 Aug 2022 22:51:00 +0000

This article was originally published on my blog.

TLDR: Here's a full working example of a faithful E2E test for an Nx preset generator since the default generated E2E harness isn't correct.

Putting it all together, here's a full sample test suite:

import {
  checkFilesExist,
  cleanup,
  runNxCommandAsync,
  tmpProjPath,
} from "@nrwl/nx-plugin/testing";
import { ChildProcess, execSync, fork } from "node:child_process";
import path from "node:path";
import { getPortPromise as getOpenPort } from "portfinder";

// These tests can take awhile to run. Modify or remove this depending on how long this takes
// on your machine or in your environment.
jest.setTimeout(60_000);

const startVerdaccio = async (port: number): Promise<ChildProcess> => {
  const configPath = path.join(__dirname, "../verdaccio.yaml");
  return new Promise((resolve, reject) => {
    const child = fork(require.resolve("verdaccio/bin/verdaccio"), [
      "-c",
      configPath,
      "-l",
      `${port}`,
    ]);

    child.on("message", (message: { verdaccio_started: boolean }) => {
      if (message.verdaccio_started) {
        resolve(child);
      }
    });
    child.on("error", (error: any) => reject([error]));
    child.on("disconnect", (error: any) => reject([error]));
  });
};

describe("nx-plugin e2e", () => {
  let verdaccioProcess: ChildProcess;

  beforeAll(async () => {
    cleanup();

    const verdaccioPort = await getOpenPort();
    verdaccioProcess = await startVerdaccio(verdaccioPort);

    const verdaccioUrl = `http://localhost:${verdaccioPort}`;

    execSync(`yarn config set registry ${verdaccioUrl}`);

    execSync(
      `npx npm-cli-login -u chiubaka -p test -e test@chiubaka.com -r ${verdaccioUrl}`,
    );
    execSync(`npm publish --registry=${verdaccioUrl}`, {
      cwd: path.join(__dirname, "../../../dist/packages/nx-plugin"),
    });

    const destination = path.join(tmpProjPath(), "..");
    const workspaceName = path.basename(tmpProjPath());

    execSync(
      `npm_config_registry=${verdaccioUrl} npx create-nx-workspace ${workspaceName} --preset=@chiubaka/nx-plugin --nxCloud=false`,
      {
        cwd: destination,
      },
    );
  });

  afterAll(async () => {
    // `nx reset` kills the daemon, and performs
    // some work which can help clean up e2e leftovers
    await runNxCommandAsync("reset");

    execSync(`yarn config set registry https://registry.yarnpkg.com`);

    verdaccioProcess.kill();
  });

  it("should not create an apps dir", () => {
    expect(() => {
      checkFilesExist("apps");
    }).toThrow();
  });
});

Be sure that you have _debug: true somewhere in your verdaccio.yml and that you have verdaccio, verdaccio-auth-memory, and verdaccio-memory installed as devDependencies.

The Problem

Nx models custom presets as ordinary generators that get treated differently by Nx's internals when generating a workspace. The suggested command for scaffolding a preset generator is the exact same command used for scaffolding generators for other use cases with only the caveat that a preset generator must be named preset.

Unfortunately, the preset generator use case is sufficiently different from other generator use cases (e.g. generating a project within a pre-existing workspace) that this mental model and a lot of the generated scaffolding turns out to be misleading.

Specifically, I've found that neither the unit nor the E2E testing harnesses for the preset generator are terribly faithful. By "faithful" I mean: does this testing set up accurately reflect the real context my code will run in?

In the case of the default E2E testing harness, the answer is a definite no. Out of the box, this harness is designed to test a generator by running it inside of a pre-existing workspace as if it were a library or app generator, which it's not.

This harness:

Generates a new workspace with the empty preset.
Patches the package.json file in the newly generated workspace to install my plugin from the local filesystem.
Invokes nx generate @my-org/my-plugin:preset project to run the preset generator as a normal generator.

For awhile this seemed fine, but as my preset generator grew more complex, I started noticing places where real workspace generation would fail, but my E2E tests were passing. It didn't take long to realize that this was because my generator gets run differently in production than it does in these E2E tests.

Tests that don't reliably tell me when my code is broken aren't doing their job 🙃!

Motivation

Lately I've been writing a custom Nx workspace preset. The goal of a custom preset is to allow customization of the workspace creation process.

I'm hoping to use this to create a batteries-included standardized monorepo generator complete with my preferred configuration for things like linting, testing, CI, and even GitHub project settings.

Unfortunately, this use case isn't very well-documented within Nx. In fact, in a lot of cases the documentation and provided scaffolding for preset generators is, in my humble opinion, seriously misleading. I've had to figure things out by reading through Nx's open source codebase and doing a lot of experimentation.

This article is my attempt at saving someone else all that time and pain :).

The Solution

It was a little tricky getting a full E2E test for workspace generation itself, but I managed to piece a solution together.

Here's the outline:

Start up a Verdaccio server before running tests.
1. Verdaccio is a lightweight registry that's easy to install and use locally.
Authenticate with the Verdaccio registry to allow publishing.
Publish the built Nx plugin locally to the Verdaccio registry.
Run create-nx-workspace with my preset, making sure to hit the local Verdaccio registry to grab the plugin.

Why Verdaccio?

The challenge in E2E testing a preset generator is that preset generators are usually invoked through create-nx-workspace and passed as a package name in the preset argument.

Behind the scenes, create-nx-workspace resolves the package name from NPM in order to run the preset.

In our tests, we obviously don't want to pull in a real published version of the plugin. We'd like to bundle the current state of the plugin and run the E2E tests against that.

Since create-nx-workspace is a CLI, often run through npx, we can't use other common local package linking methods like npm link or modifying a package.json file (because there isn't one yet!). Instead, the strategy is to actually publish the package, but to a local registry that won't affect anything outside of our tests.

Verdaccio fills this role perfectly. By default, it acts as a proxy for NPM, pulling any packages that aren't found in the local registry from the remote registry. This means we can publish our plugin registry and expect Verdaccio to return the development version of our own packages, while still correctly pulling in other dependencies from elsewhere.

Starting an ephemeral Verdaccio server in tests

One of the trickier parts of getting this E2E harness to work was figuring out how to reliably run an ephemeral Verdaccio server as part of my test set up. As it turns out, the Verdaccio documentation is a bit rough around the edges, as well. There are two relevant pages, one about End to End Testing, which doesn't provide a lot of context and another about the Node.js API, which is ostensibly not about E2E testing at all.

I was most drawn to the idea of running Verdaccio programmatically using the module API, but had trouble getting this to work. In most cases it seemed that the server would not start up properly and my tests would just hang.

Ultimately the approached that work was running Verdaccio as a child process using fork. I took cues from the example code in the Verdaccio documentation as well as from this sample repo that contains a complete example of this set up.

For my test setup and tear down I ended with something like this:

import { ChildProcess, fork } from "node:child_process";
import { getPortPromise as getOpenPort } from "portfinder";

const startVerdaccio = async (port: number): Promise<ChildProcess> => {
  const configPath = path.join(__dirname, "../verdaccio.yaml");
  return new Promise((resolve, reject) => {
    const child = fork(require.resolve("verdaccio/bin/verdaccio"), [
      "-c",
      configPath,
      "-l",
      `${port}`,
    ]);

    child.on("message", (message: { verdaccio_started: boolean }) => {
      if (message.verdaccio_started) {
        resolve(child);
      }
    });
    child.on("error", (error: any) => reject([error]));
    child.on("disconnect", (error: any) => reject([error]));
  });
};
describe("nx-plugin e2e", () => {
  let verdaccioProcess: ChildProcess;

  beforeAll(async () => {
      const verdaccioPort = await getOpenPort();
      verdaccioProcess = await startVerdaccio(verdaccioPort);
  });

  afterAll(async () => {
    verdaccioProcess.kill();
  });
});

I created a verdaccio.yaml file that looks like this:

# verdaccio-memory
store:
  memory:
    limit: 1000
# verdaccio-auth-memory plugin
auth:
  # htpasswd:
  #   file: ./htpasswd
  auth-memory:
    users:
      foo:
        name: foo
        password: bar
      admin:  
        name: foo
        password: bar
# uplinks
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
  verdacciobk:
    url: http://localhost:8000/
    auth:
      type: bearer
      token: dsyTcamuhMd8GlsakOhP5A==
packages:
  "@*/*":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs
  "react":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: verdacciobk
  "**":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs

# rate limit configuration
rateLimit:
  windowMs: 1000
  max: 10000

middlewares:
  audit:
    enabled: true

security: 
  api: 
    jwt: 
     sign: 
      expiresIn: 1d    

logs: { type: file, path: /dev/null, level: info }
i18n:
  web: en-US

# try to use verdaccio with child_process:fork
_debug: true

Notably, I took this file almost completely from the verdaccio-fork example repo. The only small change I made was to modify logs to send all verdaccio output to /dev/null so it wouldn't clutter my testing output.

Per the Verdaccio docs, _debug: true is very important when using Verdaccio in this way, as it's what turns on the ability to listen for the verdaccio_started message once the server is ready to go.

Authenticating with Verdaccio

Next challenge was authenticating with the new Verdaccio server from inside of tests. Initially, I thought I could just run a simple npm adduser --registry=http://my-local-registry command. It took a few confusing test failures before I realized that npm adduser is an interactive CLI and was failing my tests because it was expecting user input.

The way around this is to use npm-cli-login instead. You can either add it as a devDependency and invoke it with npm run npm-cli-login or just use npx npm-cli-login.

Here's the full command to authenticate:

import { execSync } from "node:child_process";
import { getPortPromise as getOpenPort } from "portfinder";

const verdaccioPort = await getOpenPort();
const verdaccioUrl = `http://localhost:${verdaccioPort}`;
execSync(
  `npx npm-cli-login -u chiubaka -p test -e test@chiubaka.com -r ${verdaccioUrl}`,
);

This needs to go in the beforeAll setup block of your tests.

Publishing to Verdaccio

Now that Verdaccio is running and we're authenticated, publishing is easy!

import { execSync } from "node:child_process";
import { getPortPromise as getOpenPort } from "portfinder";

const verdaccioPort = await getOpenPort();
const verdaccioUrl = `http://localhost:${verdaccioPort}`;
execSync(`npm publish --registry=${verdaccioUrl}`, {
  cwd: path.join(__dirname, "../../../dist/packages/nx-plugin"),
});

Where the cwd of the execSync here needs to be the path to the built version of your plugin, which the @nrwl/nx-plugin:e2e executor will ensure is pre-built before running your tests by default.

Running the workspace generation command

With our plugin package published to the local registry, all that's left is to run the workspace generation command to create a real generated workspace in the E2E testing directory (tmp within the Nx plugin workspace by default).

Since we're aiming to be as faithful as possible to the true experience users will have when using our plugin, we'll use the create-nx-workspace command to invoke the preset generator.

In order to get the create-nx-workspace command to use the local Verdaccio registry, we'll need to run it with npx and prefix with the npm_config_registry=[http://my-local-registry] environment variable.

Additionally, in order for a lot of the @nrwl/nx-plugin/testing utils to work properly, note that your testing workspace needs to be generated in a very specific place. At time of writing, the name of that directory is proj, but since that could change without warning it's safest to dynamically determine the name of the testing workspace using tmpProjPath().

Here's what the full command looks like:

import { tmpProjPath } from "@nrwl/nx-plugin/testing";
import { execSync } from "node:child_process";
import path from "node:path";
import { getPortPromise as getOpenPort } from "portfinder";

const verdaccioPort = await getOpenPort();
const verdaccioUrl = `http://localhost:${verdaccioPort}`;

const destination = path.join(tmpProjPath(), "..");
const workspaceName = path.basename(tmpProjPath());

execSync(
  `npm_config_registry=${verdaccioUrl} npx create-nx-workspace ${workspaceName} --preset=@chiubaka/nx-plugin --nxCloud=false`,
  {
    cwd: destination,
  },
);

Full working solution

Putting it all together, here's a full sample test suite:

import {
  checkFilesExist,
  cleanup,
  runNxCommandAsync,
  tmpProjPath,
} from "@nrwl/nx-plugin/testing";
import { ChildProcess, execSync, fork } from "node:child_process";
import path from "node:path";
import { getPortPromise as getOpenPort } from "portfinder";

// These tests can take awhile to run. Modify or remove this depending on how long this takes
// on your machine or in your environment.
jest.setTimeout(60_000);

const startVerdaccio = async (port: number): Promise<ChildProcess> => {
  const configPath = path.join(__dirname, "../verdaccio.yaml");
  return new Promise((resolve, reject) => {
    const child = fork(require.resolve("verdaccio/bin/verdaccio"), [
      "-c",
      configPath,
      "-l",
      `${port}`,
    ]);

    child.on("message", (message: { verdaccio_started: boolean }) => {
      if (message.verdaccio_started) {
        resolve(child);
      }
    });
    child.on("error", (error: any) => reject([error]));
    child.on("disconnect", (error: any) => reject([error]));
  });
};

describe("nx-plugin e2e", () => {
  let verdaccioProcess: ChildProcess;

  beforeAll(async () => {
    cleanup();

    const verdaccioPort = await getOpenPort();
    verdaccioProcess = await startVerdaccio(verdaccioPort);

    const verdaccioUrl = `http://localhost:${verdaccioPort}`;

    execSync(`yarn config set registry ${verdaccioUrl}`);

    execSync(
      `npx npm-cli-login -u chiubaka -p test -e test@chiubaka.com -r ${verdaccioUrl}`,
    );
    execSync(`npm publish --registry=${verdaccioUrl}`, {
      cwd: path.join(__dirname, "../../../dist/packages/nx-plugin"),
    });

    const destination = path.join(tmpProjPath(), "..");
    const workspaceName = path.basename(tmpProjPath());

    execSync(
      `npm_config_registry=${verdaccioUrl} npx create-nx-workspace ${workspaceName} --preset=@chiubaka/nx-plugin --nxCloud=false`,
      {
        cwd: destination,
      },
    );
  });

  afterAll(async () => {
    // `nx reset` kills the daemon, and performs
    // some work which can help clean up e2e leftovers
    await runNxCommandAsync("reset");

    execSync(`yarn config set registry https://registry.yarnpkg.com`);

    verdaccioProcess.kill();
  });

  it("should not create an apps dir", () => {
    expect(() => {
      checkFilesExist("apps");
    }).toThrow();
  });
});

Be sure to include a verdaccio.yaml file that looks something like this:

# verdaccio-memory
store:
  memory:
    limit: 1000
# verdaccio-auth-memory plugin
auth:
  # htpasswd:
  #   file: ./htpasswd
  auth-memory:
    users:
      foo:
        name: foo
        password: bar
      admin:  
        name: foo
        password: bar
# uplinks
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
  verdacciobk:
    url: http://localhost:8000/
    auth:
      type: bearer
      token: dsyTcamuhMd8GlsakOhP5A==
packages:
  "@*/*":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs
  "react":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: verdacciobk
  "**":
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs

# rate limit configuration
rateLimit:
  windowMs: 1000
  max: 10000

middlewares:
  audit:
    enabled: true

security: 
  api: 
    jwt: 
     sign: 
      expiresIn: 1d    

logs: { type: file, path: /dev/null, level: info }
i18n:
  web: en-US

# try to use verdaccio with child_process:fork
_debug: true

And of course, make sure you've installed verdaccio, verdaccio-auth-memory, and verdaccio-memory to support this config file.

Writing Tests for Custom Matchers in Jest

Daniel — Thu, 07 Jul 2022 18:13:00 +0000

TLDR: Here's an example of how to write a test for a custom matcher:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(() => {
      expect(2).toHaveDevDependency("node");
    }).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

Motivation

In the spirit of TDD, I found myself wanting to write tests to ensure my Jest custom matchers work properly.

A quick Google Search for "Jest write tests for custom matcher" only produced results about writing custom matchers themselves when really I wanted to see examples of how to write tests that exercise my custom matchers.

After figuring out how to do this on my own, I thought I'd write the missing article :).

Background

If you're familiar with Jest, you're likely also familiar with custom matchers.

If not, here's the summary version: custom matchers allow you to add your own matching assertions for expect statements. This can be super useful when you find yourself writing the same testing code over and over again and want to DRY up your tests.

Example Situation

This happened recently when writing a Yeoman generator to quickly scaffold new projects. I wanted to write something like expect(result).toHaveDevDependency("typescript") to assert that the package.json file generated with the project includes a specified package in its devDependencies.

The testing helpers provided by Yeoman in yeoman-test include a useful assertJsonFileContent(fileName: string, content: any) method, but as I found myself writing things like

result.assertJsonFileContent(
  "package.json",
  { 
    devDependencies: {
      typescript: "4.7.4"
    }
  },
);

over and over I got tired of the verbosity and realized that this line doesn't state my intent as clearly as it could.

I wanted something like this instead:

expect(result).toHaveDevDependency("typescript", "4.7.4");

Simple, clear, and clean.

My toHaveDevDependency custom matcher ended up being reasonably complicated, including checks to ensure that the received object in the expect call was, indeed, a YeomanTest.RunResult object, and then wrapping the result.assertJsonFileContent() call with a try/catch to translate that result into either a passing or failing jest.CustomMatcherResult with a useful message.

Ironically, the custom matcher ended up showing up in my code coverage reports as the least tested part of my codebase.

The Solution

I wrote myself a test suite for toHaveDevDependency and in the process, I had to figure out how to test an expect statement itself. Rather meta.

First Attempt: wrap `expect` call in a `try`/`catch`

My first attempt looked something like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    try {
      expect(2).toHaveDevDependency("node");
    } catch (error) {
      expect(error.message).toContain("JestAssertionError");
    }
  );
});

The idea being that Jest is likely throwing some kind of error when an expect assertion fails, and perhaps I can catch that error and then do something with it.

Unfortunately, this does not work. Jest seems to be smart enough to fail the test immediately, and while I can catch the error, I couldn't find an easy way to stop the test from failing down this path. There might be a way, but I gave up before I found it.

Second Attempt: wrap raw `expect` call with `expect().toThrow()`

My next idea was to use the expect().toThrow() method to tell Jest explicitly that I'm expecting an error throw. It looked like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(
      expect(2).toHaveDevDependency("node");
    ).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

This didn't work, either. The test failed immediately.

Final Working Attempt: wrap `expect` call in an arrow function and wrap that in an `expect().toThrow()`

I had one more idea: what if I wrap the expect call in an arrow function first?

This looked like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(() => {
      expect(2).toHaveDevDependency("node");
    }).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

This works! I haven't looked into the Jest internals enough to understand exactly why, but intuitively this makes sense: the arrow function insulates the inner call to expect from the Jest test context, and prevents the function call from being executed immediately within the it block.

Now I can happily write test suites for my custom matchers and test everything with confidence!

Integrating Sentry with NestJS scheduled jobs

Daniel — Fri, 07 May 2021 09:30:50 +0000

After integrating @ntegral/nestjs-sentry in my NestJS project, I was surprised to find errors in my logs that weren't being reported to Sentry.

After a bit of investigation, I found that NestJS' native concepts of Interceptors and ExceptionFilters are built around the idea that the execution context will be somehow request-generated. i.e. These constructs expect errors to be triggered by an external request to the server via e.g. HTTP or GraphQL.

Unfortunately, when using the Cron decorator from @nestjs/schedule, my code isn't actually triggered by an external request, so errors thrown in these contexts don't seem to bubble up to the normal interceptor or exception filter pipelines.

To solve this, I took inspiration from this StackOverflow answer to create a decorator that I can use to wrap my Cron methods in an error handler that reports any caught errors to Sentry directly.

It looks like this:

// decorators/sentry-overwatch.decorator.ts

import { Inject } from "@nestjs/common";
import { SentryService } from "@ntegral/nestjs-sentry";

export const SentryOverwatchAsync = () => {
  const injectSentry = Inject(SentryService);

  return (
    target: any,
    _propertyKey: string,
    propertyDescriptor: PropertyDescriptor,
  ) => {
    injectSentry(target, "sentry");
    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
    const originalMethod: () => Promise<void> = propertyDescriptor.value;
    propertyDescriptor.value = async function (...args: any[]) {
      try {
        return await originalMethod.apply(this, args);
      } catch (error) {
        const sentry = this.sentry as SentryService;
        sentry.instance().captureException(error);
        throw error;
      }
    };
  };
};

This particular function is designed to decorate an async function. For the non-async version, you'd just need to remove the async in the propertyDescriptor.value definition and the await when calling originalMethod.

With a little more work, one could write something more generalized to detect whether or not the return value is a Promise and do the right thing, but my use case is simple.

I'm then able to wrap my original function like so:

// decorators/cron.decorator.ts

// Decorator ordering is important here. Swapping the order
// results in Nest failing to recognize this as a scheduled
// job
@Cron("*/5 * * * *")
@SentryOverwatchAsync()
async scheduledTask(): Promise<void> {
  // ...
}

But now I have to add @SentryOverwatchAsync() every time I declare a @Cron scheduled job. A little annoying, and I'm sure I'm going to forget at some point.

So using decorator composition I decided to re-export my own version of the @Cron decorator that packages the native Nest decorator in with my new custom decorator:

import { applyDecorators } from "@nestjs/common";
import { Cron as NestCron, CronOptions } from "@nestjs/schedule";

import { SentryOverwatchAsync } from "./sentry-overwatch.decorator";

export const Cron = (cronTime: string | Date, options?: CronOptions) => {
  // Ordering is important here, too!
  // The order these must appear in seems to be the reverse of
  // what you'd normally expect when decorating functions
  // declaratively. Likely because the order you specify here
  // is the order the decorators will be applied to the 
  // function in.
  return applyDecorators(SentryOverwatchAsync(), NestCron(cronTime, options));
};

Now all I need to do is swap all of my usages of Cron to my internal Cron decorator and I have complete Sentry overwatch.

Peace of mind: achieved!

Forem: Daniel

Writing Shared Scripts for CircleCI Orbs

Problem

Motivation

Solution

Not recommended: eval the body of the shared script

Slightly better: writing the contents of the shared script to disk

Security Considerations

Faithful E2E Testing of Nx Preset Generators

The Problem

Motivation

The Solution

Why Verdaccio?

Starting an ephemeral Verdaccio server in tests

Authenticating with Verdaccio

Publishing to Verdaccio

Running the workspace generation command

Full working solution

Writing Tests for Custom Matchers in Jest

Motivation

Background

Example Situation

The Solution

First Attempt: wrap expect call in a try/catch

Second Attempt: wrap raw expect call with expect().toThrow()

Final Working Attempt: wrap expect call in an arrow function and wrap that in an expect().toThrow()

Integrating Sentry with NestJS scheduled jobs

Not recommended: `eval` the body of the shared script

First Attempt: wrap `expect` call in a `try`/`catch`

Second Attempt: wrap raw `expect` call with `expect().toThrow()`

Final Working Attempt: wrap `expect` call in an arrow function and wrap that in an `expect().toThrow()`