Testing blueprints

Generated snapshot tests across multiple configurations of your blueprint are supported.

Snapshot testing

Blueprints support snapshot testing on configurations provided by you as a blueprint author. The configurations are partial overrides that are merged on top of the defaults.json file at the root of a blueprint. When snapshot testing is enabled and configured, the build and test process synthesizes the given configurations and verifies that the synthesized outputs haven’t changed from the reference snapshot.

To enable snapshot testing:

1. In the .projenrc.ts file, updaet the input object to ProjenBlueprint with the files you want to snapshot. For example:

{
  ....
  blueprintSnapshotConfiguration: {
    snapshotGlobs: ['**', '!environments/**', '!aws-account-to-environment/**'],
  },
}

2. Resynthesize the blueprint to create TypeScript files in your blueprint project. Don’t edit the source files since they’re maintained and regenerated by Projen. Use the following command:

yarn projen

3. Navigate to the src/snapshot-configurations directory to view the default-config.json file with an empty object. Update or replace the file with one or more of your own test configurations. Each test configuration is then merged with the project’s defaults.json file, synthesized, and compared to snapshots when testing. Use the following command to test:

yarn test

The first time you use a test command, the following message is displayed: Snapshot Summary › NN snapshots written from 1 test suite. Subsequent test runs verify that the synthesized output hasn’t changed from the snapshots and display the following message: Snapshots: NN passed, NN total.

If you intentionally change your blueprint to produce a different output, then run the following command to update the reference snapshots:

yarn test: update

Snapshots expect synthesized outputs to be constant between each run. If your blueprint generates files that vary, you must exclude those files from the snapshot testing. Update the blueprintSnapshotConfiguration object of your ProjenBluerpint input object to add the snapshotGlobs property. The snapshotGlobs property is an array of globs that determines which files are included or excluded from snapshotting.

Note: There is a default list of globs. If you specify your own list, you may need to explicitly bring back the default entries.