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, Serverless Offline Documentation).

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:

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.

interface ServerlessOfflineConfiguration {
    serverless?: ServerlessOptions;

    startup?: StartupOptions;

    outputRecorder?: OutputRecorder | OutputRecorderConfiguration;

    logger?: Logger | DefaultLoggerConfiguration;
}

| Property | Description | |:---------------|:------------| | serverless | Options for how serverless is started. | | startup | Options for detecting when serverless is ready to receive requests. | | outputRecorder | A custom OutputRecorder instance or options for the default or Ephesoft output recorder. | | logger | A custom Logger instance or options for the default logger. |

ServerlessOptions

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

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.

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.

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

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 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.text-to-be-colored can be any text and may include the placeholders above.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:

{
    message: 'This is a test.',
    level: LogLevel.Debug,
    source: LogSource.ProcessStdout
}

The output will be:

NPM run targets

Run NPM commands as

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. |