Confusion around jest expect vs aws-cdk assert expect function in snapshot testing

Regarding this page here: https://docs.aws.amazon.com/cdk/latest/guide/testing.html

I spent a lot of time today trying to debug an error I had by changing the test that comes with a newly inited CDK stack which gives the following (plain JS, TS is similar I believe):

const { expect, matchTemplate, MatchStyle } = require('@aws-cdk/assert');
const cdk = require('@aws-cdk/core');
const Testjs = require('../lib/testjs-stack');

test('Empty Stack', () => {
    const app = new cdk.App();
    // WHEN
    const stack = new Testjs.TestjsStack(app, 'MyTestStack');
    // THEN
    expect(stack).to(matchTemplate({
      "Resources": {}
    }, MatchStyle.EXACT))
});

When altering this to the snapshot testing in the documentation above I made a (arguably) simple mistake of changing this to the following (this is wrong and does not work):

const { expect, SynthUtils } = require('@aws-cdk/assert');
const cdk = require('@aws-cdk/core');
const Testjs = require('../lib/testjs-stack');

test('Empty Stack', () => {
    const app = new cdk.App();
    // WHEN
    const stack = new Testjs.TestjsStack(app, 'MyTestStack');
    // THEN
    expect(SynthUtils.toCloudFormation(stack)).toMatchSnapshot()
});

The problem is that I’m picking up expect from the @aws-cdk/assert library and in this case it wants to use the expect function from jest so simply removing that import fixes this. Previously however I was getting the following error and could find no information on this (most of google threw up old Angular stuff):

> testjs@0.1.0 test /Users/strotter/work/aws/cdk/testjs
> jest

 FAIL  test/testjs.test.js
  ✕ Empty Stack (122ms)

  ● Empty Stack

    TypeError: Cannot read property 'root' of undefined

       8 |     const stack = new Testjs.TestjsStack(app, 'MyTestStack');
       9 |     // THEN
    > 10 |     expect(SynthUtils.toCloudFormation(stack)).toMatchSnapshot()
         |     ^
      11 | });
      12 |

      at Function._synthesizeWithNested (node_modules/@aws-cdk/assert/lib/synth-utils.ts:54:29)
      at expect (node_modules/@aws-cdk/assert/lib/expect.ts:8:90)
      at Object.<anonymous> (test/testjs.test.js:10:5)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.214s
Ran all test suites.

Whilst clearly this was my error it seems it would be helpful (even if this issue just gets closed immediately) for others hitting this to have some hint as to how to fix it. So I propose one of the following steps:

• Better documentation around this to ensure the differences between the two expect functions are explained
• Alter the CDK assert expect function to be compatible with this and the problem goes away (no idea how much effort that would be)
• Give a better error message saying that the expect function being used is most likely the wrong one.

Any of these might have saved me hours of debugging this afternoon so I offer them as suggestions to stop anyone else having that problem.

[johnschultz]

Wanted to chime in to say I ran into this same issue last night. Definitely confusing for new CDK users and double or triply so for developers new to Typescript and/or Jest. Speaking as one of those developers, I had no idea Jest’s expect is included in the namespace by default; it probably would have taken me quite a while to figure this out if I hadn’t found this issue. Thanks @strottos

[nija-at]

We have now built up the ‘assertions’ module that is a replacement to the ‘assert’ module. This confusion will not occur with this new module.

In the coming months, the ‘assert’ module will be deprecated.

Marking this as ‘closing-soon’. Let me know if I missed anything.