🍕 appsync-testing

🚧 Warning: this package is still v0.x, there are limitations and may be frequent breaking changes until v1.x 🚧

Unit test AWS AppSync GraphQL resolvers the same way as all your other code

• 🧪 Write TypeScript/JavaScript tests for your AppSync VTL resolvers
• ✅ Using the real Apache Velocity and Java under the hood, not emulations in JS
• 🎨 Full (*WIP limitations) coverage of AppSync $util utilities
• ⚡️ Compiled to binary for speed, and developer experience -- no need to install a JDK, or Velocity

Getting Started

Install the package as a development dependency

yarn add --dev appsync-testing

Import render, which takes a relative path to a .vtl file, and a context object.

import { render } from 'appsync-testing'

Write tests as you would for any other code, maybe even first if you're practicing TDD 💪

  it('should build DynamoDB request', async () => {
    const context = {
      arguments: {
        id: 'USER#b90be38e-70d1-4d85-a47b-d5e20376b67d'
      }
    };
  
    const { result, error } = await render('request.vtl', context);
    
    const expected = {
      version: '2017-02-28',
      operation: 'GetItem',
      key: {
          PK: 'USER#b90be38e-70d1-4d85-a47b-d5e20376b67d',
          SK: 'PROFILE'
      }
    };
    
    expect(result).toEqual(expected);
    expect(error).toBe(null);
  });

You can then make the test pass by implementing the resolver ✅

## request.vtl

#set($userId = $context.arguments.id)

{
  "version": "2017-02-28",
  "operation": "GetItem",
  "key": {
    "PK": $util.dynamodb.toDynamoDBJson($userId),
    "SK": $util.dynamodb.toDynamoDBJson("PROFILE")
  }
}

render also supports interrupting execution (e.g. with $util.validate) to allow you to test branches

You could start with a failing test like below to protect yourself 🛑

  // should someone want to be naughty, we're protected by our unit tests 😈
  it('should reject requests with invalid IDs', async () => {
    const context = {
      arguments: {
        id: 'ADVISER#b90be38e-70d1-4d85-a47b-d5e20376b67d'
      }
    };

    const { error, result } = await render('request.vtl', context);

    const expected = expect.objectContaining({
      data: {
        id: 'ADVISER#b90be38e-70d1-4d85-a47b-d5e20376b67d'
      },
      errorType: 'BadRequest',
      message: 'Was not supplied user id'
    });

    expect(error).toEqual(expected);
    expect(result).toBe(null);
  });

You can then make the error case test pass too by adding to the implementation ✅

## request.vtl

#set($userId = $context.arguments.id)

#set($isValid = $util.matches("USER#[a-f0-9\-]{36}", $userId))

$util.validate($isValid, "Was not supplied user id", "BadRequest", { "id": $userId })

{
  "version": "2017-02-28",
  "operation": "GetItem",
  "key": {
    "PK": $util.dynamodb.toDynamoDBJson($userId),
    "SK": $util.dynamodb.toDynamoDBJson("PROFILE")
  }
}

Why?

We love AppSync at Wealth Wizards, it powers some of our core APIs. VTL resolvers are a large part of why we love AppSync. They have powerful time saving utilities, authentication and authorization, validation and tight first class integration with AWS services like DynamoDB, RDS, OpenSearch.

While all this would be possible with Lambda resolvers we found the out of the box support, and managed nature of VTL accelerated development.

However, the return on investment of integration testing your deployed AppSync APIs while maintaining coverage in larger projects does not scale.

We trialled building unit testing powered by AppSync emulation using the npm velocity package and serverless-appsync-simulator. This worked really well for a while, but we had trouble with the emulation of Java, Velocity, and AppSync utilities in JS. We found that this did not give us enough confidence our code ran in the same way in tests and in production.

We started working on an alternative that meant, that did not emulate Java or Velocity, and also did not need developers/CI environments to have a JDK installed.

Limitations

These are WIP, but for transparency there are currently limitations;

• Missing $util.transform.toElasticSearchQueryDsl util
• Can't test cache evictions
• Only tested on latest node + macOS/Ubuntu
• May have frequent breaking changes until v1.x