Testing Serverless Like a Pro: AWS SAM, TypeScript, and Jest

Serverless computing eliminates server management, but it doesn't eliminate bugs. In fact, the geographically distributed event-driven nature of AWS Lambda often makes testing harder. If your development cycle involves saving a file, running sam deploy, waiting 180 seconds for CloudFormation to provision, and checking CloudWatch logs to see if a typo crashed your function, your development velocity is dead.

The solution is isolated local testing. By combining the AWS Serverless Application Model (SAM) with TypeScript and Jest, engineering teams can build robust test suites that execute in milliseconds before a single byte of code touches the AWS cloud.

Step 1: Initializing the SAM TypeScript Environment

Historically, setting up TypeScript with AWS SAM required tangled Webpack configurations. Today, SAM natively supports esbuild, handling transpilation automatically during the build process.

# Initialize a new project
sam init

# Select:
# 1 - AWS Quick Start Templates
# 2 - Hello World Example
# [y] - Use the most popular runtime and package type?
# TypeScript - Runtime selection
# Zip - Package type

Crucially, inspect your template.yaml. You will see SAM defining the esbuild configuration natively within the Metadata parameters of the Lambda resource, ensuring node_modules are excluded and code is minified for zero-cold-start performance.

Step 2: Configuring Jest for TypeScript and AWS

Once initialized, install the necessary testing dependencies. We need Jest, the TypeScript definitions, and the SDK mocking libraries for AWS SDK v3.

npm install -D jest @types/jest ts-jest
npm install -D aws-sdk-client-mock aws-sdk-client-mock-jest

# Initialize Jest configuration
npx ts-jest config:init

This generates a jest.config.js file that instructs Jest to pass .ts files through the ts-jest preset rather than choking on non-standard JavaScript syntax.

Step 3: Writing Testable Lambda Functions

A common anti-pattern in serverless development is writing thick handler functions that contain database logic, business logic, and API response formatting in a single block. This makes unit testing impossible.

export const handler = async (event) => {
  const db = new DynamoDBClient({});
  // API Gateway parsing
  const body = JSON.parse(event.body);
  
  // Database execution mixed with logic
  await db.send(new PutItemCommand({...}));
  
  // Hardcoded responses
  return { statusCode: 200, body: "Success" };
};

// dbService.ts (Isolated Logic)
export const saveUser = async (id, client) => {
  return client.send(new PutItemCommand({...}));
};

// app.ts (Thin Routing layer)
export const handler = async (event) => {
  // Only parses events and delegates
  await saveUser(event.pathParameters.id, db);
  return formatResponse(200, "Success");
};

Step 4: Mocking AWS SDK v3 with Jest

When you must test the integration layer that interacts with AWS services, never make live API calls. Use aws-sdk-client-mock to intercept the requests.

import { mockClient } from 'aws-sdk-client-mock';
import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';
import { handler } from '../../app';

// Mock the specific client
const ddbMock = mockClient(DynamoDBDocumentClient);

describe('Lambda API Handler', () => {
  beforeEach(() => {
    ddbMock.reset();
  });

  it('should return 200 and data when user exists', async () => {
    // Stage the mocked AWS response
    ddbMock.on(GetCommand).resolves({
      Item: { id: '123', name: 'Serverless Pro' }
    });

    // Construct a mock API Gateway Event
    const event = { pathParameters: { id: '123' } } as any;

    const response = await handler(event, {} as any);

    expect(response.statusCode).toEqual(200);
    expect(JSON.parse(response.body).name).toEqual('Serverless Pro');
  });
});

Step 5: Local Integration Testing with SAM

While unit tests are fast, they mock reality. To verify that your IAM permissions, environment variables, and API Gateway configurations are correct, use the SAM CLI to spin up a local Docker representation of the AWS cloud.

1. Build the artifacts: sam build runs esbuild, transpiling the TypeScript to minified JavaScript.
2. Start local API: sam local start-api mounts your built lambda code inside a Docker container mimicking the AWS runtime.
3. Integration Test: Use a tool like Supertest alongside Jest to fire real HTTP requests at localhost:3000 to verify the entire stack logic.

FAQ