# @ephesoft/aws.local

> Utilities for managing AWS services for local integration testing

Latest version **1.0.0** (published 2022-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ephesoft/aws.local
pnpm add @ephesoft/aws.local
yarn add @ephesoft/aws.local
bun add @ephesoft/aws.local
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2022-11-04 |
| First published | 2022-11-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 189.8 KB |
| Known vulnerabilities | 0 (+7 in 2 direct dependencies) |
| Install scripts | no |
| Author | Ephesoft |
| Maintainers | donnie.wicker.ephesoft, ephesoft-stitus, ephesoft.automation, mark.studer.ephesoft |

## Links

- npm: https://www.npmjs.com/package/@ephesoft/aws.local
- Repository: https://bitbucket.org/ephesoft/aws.local.sdk
- Homepage: https://bitbucket.org/ephesoft/aws.local.sdk#readme
- Issues: https://bitbucket.org/ephesoft/aws.local.sdk/issues
- npm.io page: https://npm.io/package/@ephesoft/aws.local

## Dependencies (5)

- [yaml](https://npm.io/package/yaml.md) 2.1.3
- [colors](https://npm.io/package/colors.md) 1.4.0
- [js-yaml](https://npm.io/package/js-yaml.md) 4.1.0
- [tree-kill](https://npm.io/package/tree-kill.md) 1.2.2
- [@aws-sdk/client-dynamodb](https://npm.io/package/@aws-sdk/client-dynamodb.md) 3.201.0

## Recent versions

- 1.0.0 (latest) — 2022-11-04

## README

# README #

# @ephesoft/aws.local.sdk
This library contains helper classes for managing AWS services for local integration testing.

## Use

### ServerlessOffline

The `ServerlessOffline` class simplifies the management of spinning up a serverless instance for integration testing.

#### Installation

Make sure you have the following packages installed as dev dependencies:

* serverless
* serverless-offline
* @ephesoft/core.sdk
* @ephesoft/aws.local.sdk

#### Use

The default configuration should work for most testing.  Modify your serverless configuration file to suit your needs ([Serverless Documentation](https://www.serverless.com/framework/docs), [Serverless Offline Documentation](https://www.serverless.com/plugins/serverless-offline)).

If no configuration is provided, the default ports are:

| Port | Description             |
|:-----|:------------------------|
| 3000 | HTTP listen port        |
| 3001 | WebSocket listen port   |
| 3002 | Lambda HTTP listen port |

Example Usage:
```typescript
const serverlessOffline = new ServerlessOffline();

await serverlessOffline.start();

// TODO: Add your testing logic here

await serverlessOffline.stop();
```

Since it takes awhile for serverless to start and stop, it is recommended to reuse the `ServerlessOffline` instance in as many tests as you can.

#### Configuration

__NOTE:__ _Full API documentation may be generated using `npm run docs` or `npm run docs:bitbucket`._

The `ServerlessOffline` constructor accepts a parameter with the following signature.

```typescript
interface ServerlessOfflineConfiguration {
    serverless?: ServerlessOptions;

    startup?: StartupOptions;

    outputRecorder?: OutputRecorder | OutputRecorderConfiguration;

    logger?: Logger | DefaultLoggerConfiguration;
}
```

| Property       | Description |
|:---------------|:------------|
| serverless     | [Options for how serverless is started.](#markdown-header-serverlessoptions) |
| startup        | [Options for detecting when serverless is ready to receive requests.](#markdown-header-startupoptions) |
| outputRecorder | A custom `OutputRecorder` instance or options for the [default](#markdown-header-defaultoutputrecorderconfiguration) or [Ephesoft](#markdown-header-ephesoftoutputrecorderconfiguration) output recorder. |
| logger         | A custom `Logger` instance or [options for the default logger](#markdown-header-defaultloggerconfiguration). |

##### ServerlessOptions

```typescript
interface ServerlessOptions {
    config?: string;

    httpPort?: number;

    lambdaPort?: number;

    parameters?: Record<string, string>;

    stage?: string;

    websocketPort?: number;

    prependStageInUrl?: boolean;

    environmentVariables?: NodeJS.ProcessEnv;
}
```

| Property             | Description |
|:---------------------|:------------|
| config               | Name of the serverless configuration file (defaults to serverless.yml\|.yaml\|.js\|.json). |
| httpPort             | The port where serverless-offline will listen for HTTP calls (defaults to 3000). |
| lambdaPort           | The port where serverless-offline will listen for lambda HTTP calls (defaults to 3002). |
| parameters           | Additional parameters to be passed to serverless in the format `--param="key=value"` (defaults to no parameters). |
| stage                | The stage your service is deployed to (defaults to 'offline'). |
| websocketPort        | The port where serverless-offline will listen for websocket calls (defaults to 3001). |
| prependStageInUrl    | `true` to prepend HTTP listen routes with the stage (defaults to `false`). |
| environmentVariables | Environment variables to be passed to the serverless prcess. |

##### StartupOptions

```typescript
interface StartupOptions {
    stdoutExpression?: RegExp | false;

    stderrExpression?: RegExp | false;

    checkDelegate?: () => Promise<boolean>;

    checkInterval?: TimeSpan;

    timeout?: TimeSpan;
}
```

| Property         | Description |
|:-----------------|:------------|
| stdoutExpression | A regular expression to look for in stdout channel output to tell if serverless is fully online or `false` to disable this check (default to `false`). |
| stderrExpression | A regular expression to look for in stderr channel output to tell if serverless is fully online or `false` to disable this check (defaults to `/Server ready: http/` ONLY if no other startup checks are specified). |
| checkDelegate    | A function to be called to check if serverless is online (defaults to not having a check delegate). |
| checkInterval    | The interval to wait between checks for a state change in serverless (defaults to `TimeSpan.fromMilliseconds(500)`). |
| timeout          | The timeout to be applied to serverless start and stop operations (defaults to `TimeSpan.fromMinutes(1)`). |

__NOTE:__ _If multiple mechanisms are declared for checking if serverless is online, only the first one to report a match is honored._

##### DefaultOutputRecorderConfiguration

`OutputRecorder` instances process output from the serverless process on the stdout and stderr channels.

```typescript
export interface DefaultOutputRecorderConfiguration {
    type: OutputRecorderType.Default;

    jsonIndentationSpaces?: number;

    logEachLineIndividually?: boolean;

    logBlankLines?: boolean;

    stdoutLogLevel?: LogLevel;

    stderrLogLevel?: LogLevel;
}
```

| Property                | Description |
|:------------------------|:------------|
| type                    | Must be `OutputRecorderType.Default`. |
| jsonIndentationSpaces   | The number of spaces to use when formatting JSON text (defaults to no formatting). |
| logEachLineIndividually | `true` to split output on line breaks and send each line to the logger individually (defaults to `false`) |
| logBlankLines           | `true` to output lines containing no text (defaults to `false`). |
| stdoutLogLevel          | The level at which text received on the stdout channel will be logged (defaults to `Debug`). |
| stderrLogLevel          | The level at which text received on the stderr channel will be logged (defaults to `Debug`). |

##### EphesoftOutputRecorderConfiguration

`OutputRecorder` instances process output from the serverless process on the stdout and stderr channels.

```typescript
interface EphesoftOutputRecorderConfiguration {
    type: OutputRecorderType.Ephesoft;

    defaultStdoutLogLevel?: LogLevel;

    defaultStderrLogLevel?: LogLevel;

    jsonIndentationSpaces?: number;
}
```

| Property              | Description |
|:----------------------|:------------|
| type                  | Must be `OutputRecorderType.Ephesoft`. |
| defaultStdoutLogLevel | The level at which text received on the stdout channel (which is not in Ephesoft log format) will be logged (defaults to `Debug`). |
| jsonIndentationSpaces | The level at which text received on the stderr channel (which is not in Ephesoft log format) will be logged (defaults to `Debug`). |

##### DefaultLoggerConfiguration

```typescript
interface DefaultLoggerConfiguration {
    minimumLogLevel?: LogLevel;

    format?: string;

    stdout?: {
        minimumLogLevel?: LogLevel;
        format?: string;
    };

    stderr?: {
        minimumLogLevel?: LogLevel;
        format?: string;
    }
}
```

| Property        | Description |
|:----------------|:------------|
| minimumLogLevel | The minimum level a log message must be to be logged (defaults to `Info`). |
| format          | The format to output log messages - see [Log Format Strings](#markdown-header-log-format-strings) section. |
| stdout          | Logging options for text received on the stdout channel. |
| stderr          | Logging options for text received on the stderr channel. |

###### Log Format Strings

The format string may contain one or more of the placeholders below:

| Placeholder                                     | Description |
|:------------------------------------------------|:------------|
| \{\|level\|\}                                   | Replaced with the log level (ex: 'debug', 'warning', etc.). |
| \{\|channel\|\}                                 | Replaced with the output channel - this will be 'stdout', 'stderr', or an empty string. |
| \{\|message\|\}                                 | Replaced with the log message. |
| \{\|color:color-value\[text-to-be-colored\]\|\} | `color-value` should be one of the values from the list below.<br/>`text-to-be-colored` can be any text and may include the placeholders above.<br/>__NOTE:__ _Nested color placeholders are not supported._ |

The following colors are supported:

* `level` _(color is based on log level - see table below)_
* `black`
* `black-bold`
* `black-italic`
* `cyan`
* `cyan-bold`
* `cyan-italic`
* `blue`
* `blue-bold`
* `blue-italic`
* `gray`
* `gray-bold`
* `gray-italic`
* `green`
* `green-bold`
* `green-italic`
* `magenta`
* `magenta-bold`
* `magenta-italic`
* `red`
* `red-bold`
* `red-italic`
* `white`
* `white-bold`
* `white-italic`
* `yellow`
* `yellow-bold`
* `yellow-italic`

| Level      | Color |
|:-----------|:------|
| `Trace`    | `gray-italic`      |
| `Debug`    | `blue-italic`      |
| `Info`     | _no color applied_ |
| `Warning`  | `yellow`           |
| `Error`    | `red`              |
| `Critical` | `red-bold`         |
| `Status`   | `green`            |

Example:

For the format string:

`[{|color:level[{|level|}]|} - {|channel|}] {|message|}`

If the logger receives the entry:
```typescript
{
    message: 'This is a test.',
    level: LogLevel.Debug,
    source: LogSource.ProcessStdout
}
```
The output will be:

![Example](images/example.jpg)

## NPM run targets
Run NPM commands as
```bash
npm run command
```
### Available Commands
|Command|Description|
|:-|:-|
| audit | Executes a dependency audit using the default NPM registry |
| audit:fix | Attempts an automatic fix of any audit failures. |
| build | Cleans the dist folder and transpiles/webpacks the code |
| clean | Deletes the working folders like dist and docs |
| clean:docs | Deletes the docs folder |
| create:beta | Auto versions the package to the next available beta version. |
| docs | Create API documentation for the package in a "docs" folder |
| docs:bitbucket | Creates API documentation in Bitbucket markdown format in a "docs" folder |
| lint | Performs static analysis on the TypeScript files. |
| lint:fix | Performs static analysis on the TypeScript files and attempts to automatically fix errors. |
| lint:report | Performs static analysis on the TypeScript files using the default validation rules and logs results to a JSON file. |
| pack | Creates a local tarball package |
| postbuild| Automatically ran during build. |
| postprepare  | Automatically ran during package install to setup tooling. |
| prebuild | Automatically ran during build. |
| start | Instructs the TypeScript compiler to compile the ts files every time a change is detected. |
| test | Executes all tests and generates coverage. |
| test:coverage | Generates code coverage reports from test data. |
| test:integration | Runs the integration tests. |
| test:unit | Runs the unit tests. |
| validate:ga | Validates the package version is valid for GA release. |
| validate:beta | Validates the package version is valid for a Beta release. |

---
_Source: https://npm.io/package/@ephesoft/aws.local · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._