appsync-testing/README.md

 

# 🍕 appsync-testing

![GitHub Actions Build (main)](https://img.shields.io/github/workflow/status/WealthWizardsEngineering/appsync-testing/Pipeline/main?logo=github) ![npm](https://img.shields.io/npm/v/appsync-testing?color=red&logo=npm)

> 🚧 Warning: this package is still v0.x, there are [limitations](#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](#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

```bash
yarn add --dev appsync-testing
```

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

```javascript
import { render } from 'appsync-testing'
```

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

```javascript
  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 ✅

```vtl
## 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 🛑

```javascript
  // 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 ✅

```vtl
## 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