npm package: @schematize/serverless-function-test
Description: Schematize Serverless Function Tester Library for testing serverless functions locally
Author: Benjamin Bytheway
Latest version: 0.6.3

# @schematize/serverless-function-test

Local HTTP server for exercising Schematize serverless function handlers. It turns incoming requests into **API Gateway HTTP API v2–style events**, loads your handler (with `.env` and working directory scoped to the function), and writes the response back on the socket.

## Layout

| Piece | Role |
|--------|------|
| [`src/index.mjs`](./src/index.mjs) | **CLI entrypoint** — parses arguments, starts `http`/`https`, routes requests, calls `runFunction`. |
| [`src/runHandler.mjs`](./src/runHandler.mjs) | **Shared runtime** — `initAwslambda`, `buildEvent`, `loadHandler`, `invokeHandler`, `runFunction` (used by this CLI and other tools such as schambda). |

The npm `bin` field points the executable at `src/index.mjs` (with a `#!/usr/bin/env` shebang).

## Installing the binary

From a project that lists this package as a dependency:

```bash
npm install @schematize/serverless-function-test
```

Then either:

```bash
npx schematize-serverless-function-test --handler ./path/to/function
```

or, from that project’s root:

```bash
./node_modules/.bin/schematize-serverless-function-test …
```

Run the command from the directory whose **relative paths** (`--handler`, bundle folders) should resolve — paths are joined with `process.cwd()`.

## CLI usage

You must supply **either** `--bundles` **or** `--handler`.

### `--handler <dir>`

Serve a **single** function directory (relative to the current working directory). Every path is dispatched to that handler (internal route match is `/.+/`).

Example:

```bash
schematize-serverless-function-test --handler ./workspaces/my-bundle/serverlessFunction/utils
```

The loader resolves the handler via that directory’s `package.json` `functionSettings.handler` (`file.exportName`), or defaults to `index` + `default` export.

### `--bundles <path>[,<path>…]`

Comma-separated list of **bundle root** directories. For each bundle, the tool reads `bundle/package.json`, expects `bundle.serverlessFunctionList`, and for each entry uses `dir` + `regex` (path regex) to decide which function handles a request.

Example:

```bash
schematize-serverless-function-test --bundles ./workspaces/bundle-auth
```

### `--port <number>`

Listen port. Default: **3000**.

### `--key` and `--cert` (HTTPS)

Optional paths (relative to `process.cwd()`) to a TLS key and certificate. If **both** are set, the server uses HTTPS; if only one is set, it warns and falls back to HTTP.

### Programmatic use (without the CLI)

Import helpers from the package export map:

```js
import {
  initAwslambda,
  buildEvent,
  runFunction,
} from '@schematize/serverless-function-test/runHandler';
```

`runFunction` loads the function’s `.env`, temporarily `chdir`s into `functionDir`, invokes the handler, then restores `process.cwd()` and environment.

## Notes

- Intended for **local testing only**. The CLI sets `NODE_TLS_REJECT_UNAUTHORIZED=0` for developer convenience.
- Request bodies are surfaced in the synthetic event as **base64** (`isBase64Encoded: true`), matching common Lambda patterns.

## License

MIT