@ephesoft/aws.local v1.0.0

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:

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;
}

ServerlessOptions

interface ServerlessOptions {
    config?: string;

    httpPort?: number;

    lambdaPort?: number;

    parameters?: Record<string, string>;

    stage?: string;

    websocketPort?: number;

    prependStageInUrl?: boolean;

    environmentVariables?: NodeJS.ProcessEnv;
}

StartupOptions

interface StartupOptions {
    stdoutExpression?: RegExp | false;

    stderrExpression?: RegExp | false;

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

    checkInterval?: TimeSpan;

    timeout?: TimeSpan;
}

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;
}

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;
}

DefaultLoggerConfiguration

interface DefaultLoggerConfiguration {
    minimumLogLevel?: LogLevel;

    format?: string;

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

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

Log Format Strings

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

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

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