lambda-handler-tester

Test AWS Lambda handler built with javascript on the command line. This tool loads the javascript and call the handler function with the provided event data. Handler which can handler streaming are supported when using the flag -s.

Usage

Usage: pnpm dlx lambda-handler-tester [options]

Options:
  -V, --version         output the version number
  --handler [PATH]      path to request handler
  -s, --streaming       streaming handler (default: false)
  -e, --event [PATH]    path to an json file with a valid event
  -c, --context [PATH]  path to an json file with a valid context
  -p, --path [PATH]     path to request (default: "/")
  --decode-base64       decode base64 body (default: false)
  --header              only show header without body (default: false)
  -v, --verbose         enables verbose logging (default: false)
  --response-time       measure the response time (default: false)
  --repeat <number>     repeat request [n] times (default: 1)
  --profile-cpu         profile JavaScript CPU usage to "aws-lambda-handler.cpuprofile" (default: false)
  --silent              no output (default: false)
  -d, --debug           enables verbose logging (default: false)
  -w, --watch <port>    start HTTP server on port and watch for requests
  --fetch <url>         fetch URL and convert to API Gateway V2 GET event
  -h, --help            display help for command

Examples:

  $ pnpm dlx lambda-handler-tester
  0.0.xx-development

  $ pnpm dlx lambda-handler-tester --watch 3000
  🚀 Lambda handler server listening on http://localhost:3000

  $ pnpm dlx lambda-handler-tester --fetch "https://example.com/api/users?id=123"
  # Converts the URL to an API Gateway V2 GET event and passes it to your handler

Framework detection

These frameworks are detected:

• @lazarv/react-server
• Waku
• Vike

If your network is not detected you will need to provide the path to the file with the AWS Lambda Handler: $ pnpm dlx lambda-handler-tester --handler ./aws-lambda-output/handler.mjs

Options

Measure Response Time

The option --response-time together with the option --repeat <number> allows to measure response time for first and repeated calls.

Report:

First run:
Name  size  min   max   median  sum
----  ----  ----  ----  ------  ----
         1  2.24  2.24    2.24  2.24

Repeat 100 times:  100%
Name  size  min   max   median  sum
----  ----  ----  ----  ------  ----
       100  0.02  0.75    0.02  4.78
Total running time: 5ms

JavaScript CPU Profile

The option --profile-cpu allows to profile the CPU usage of the handler to the file aws-lambda-handler.cpuprofile. The handler needs to be called from NodeJS with the --inspect flag to generate the file or at least run in a VS Code JavaScript Debug Terminal.

Streaming handlers are not supported!

Fetch URL Mode

The --fetch <url> option converts any URL into an AWS API Gateway V2 GET event. This is useful for testing how your handler would process requests to specific URLs.

Features:

• Converts URL to proper API Gateway V2 event format
• Extracts path, query parameters, and host information
• Sets appropriate headers including protocol (http/https)
• Supports custom ports
• Perfect for testing web scraping or proxy handlers

Usage:

# Fetch a simple URL
$ pnpm dlx lambda-handler-tester --fetch "https://example.com/api/data"

# Fetch with query parameters
$ pnpm dlx lambda-handler-tester --fetch "https://api.github.com/users/octocat?tab=repos"

# Fetch with custom port
$ pnpm dlx lambda-handler-tester --fetch "http://localhost:8080/test"

# With verbose logging to see the generated event
$ pnpm dlx lambda-handler-tester --fetch "https://example.com" --verbose

The generated event includes:

• rawPath: The URL pathname
• rawQueryString: URL-encoded query string
• queryStringParameters: Parsed query parameters
• headers: Standard HTTP headers including host, user-agent, accept, etc.
• requestContext.http.method: Always "GET"
• x-forwarded-proto: Protocol (http or https)
• x-forwarded-port: Port number

See examples/fetch_handler.mjs for an example handler that processes fetch events.

Watch Server Mode

The --watch <port> option starts a local HTTP server that converts all incoming HTTP requests to AWS API Gateway V2 events and forwards them to your Lambda handler. This is useful for local development and testing.

Features:

• Converts HTTP requests to API Gateway V2 event format
• Handles all HTTP methods (GET, POST, PUT, DELETE, etc.)
• Properly processes headers, cookies, query parameters, and request body
• Supports base64 encoding for binary content
• Supports streaming handlers with --streaming flag
• Real-time request/response logging
• Graceful shutdown with Ctrl+C

Usage:

# Start server on port 3000
$ pnpm dlx lambda-handler-tester --watch 3000

# With verbose logging
$ pnpm dlx lambda-handler-tester --watch 3000 --verbose

# With a specific handler
$ pnpm dlx lambda-handler-tester --handler ./my-handler.mjs --watch 8080

# With streaming support
$ pnpm dlx lambda-handler-tester --handler ./streaming-handler.mjs --streaming --watch 3000

Example output:

🚀 Lambda handler server listening on http://localhost:3000
   Press Ctrl+C to stop

→ GET /
← 200 GET / (23ms)
→ POST /api/data
← 200 POST /api/data (15ms)

See examples/watch_server_handler.mjs for a complete example handler. See examples/watch_server_streaming_handler.mjs for a streaming handler example.

API Gateway V2 Event Format:

The watch server converts HTTP requests to the AWS API Gateway HTTP API payload format version 2.0, which includes:

• version: Always "2.0"
• routeKey: Route identifier (default: "$default")
• rawPath: The request path
• rawQueryString: URL-encoded query string
• cookies: Array of cookie strings
• headers: All request headers (lowercase keys)
• queryStringParameters: Parsed query parameters
• requestContext: Metadata about the request (method, sourceIp, userAgent, etc.)
• body: Request body (base64 encoded for binary content)
• isBase64Encoded: Boolean indicating if body is base64 encoded

Reference: AWS API Gateway HTTP API payload format