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:

Example

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.