Architect local development environment: run full Architect projects locally & offline in an in-memory sandbox

npm i @architect/sandbox

npx sandbox

Or if running Sandbox from within @architect/architect:

npx arc sandbox

• -p, --port, port - Manually specify HTTP port
  • Defaults to 3333
• -v, --verbose, verbose - Enable verbose logging
• -d, --debug, debug - Enable debose logging
• -q, --quiet, quiet - Disable (most) logging
• --disable-symlinks - Disable symlinking src/shared into all functions and use file copying instead

• ARC_API_TYPE - Set the API Gateway API type
  • Can be one of http (aliased to httpv2), httpv1, rest
  • Defaults to http
• ARC_QUIET - If present, disable (most) logging
• PORT - Manually specify HTTP port
  • Defaults to 3333
• ARC_EVENTS_PORT- Manually specify event bus port
  • Defaults to 3334
• ARC_TABLES_PORT- Manually specify local DynamoDB port
  • Defaults to 5000
• ARC_LOCAL- If present and used in conjunction with NODE_ENV=staging|production, emulates live staging or production environment
  • Uses your local preference file's @staging or @production environment variables
  • Connects Sandbox to live AWS events and DynamoDB infra
  • Requires valid AWS credentials with the same profile name as defined in your project manifest

Sandbox is designed to be integrated into your application's test suite. In most cases you'll only need to make use of sandbox.start() and sandbox.end(). However, individual Sandbox services can also be individually started and stopped. (See below.)

Methods may be passed an options object containing the following parameters:

• apigateway - String - Specify the API Gateway API type
  • Defaults to http
  • Can be one of http (aliased to httpv2), httpv1, rest
• cwd - String - Specify a working directory (handy for aiming Sandbox at test mocks)
• env - Object - Environment variables for Lambda invocations in automated testing
  • String values overwrite env vars of the same name set via .env or prefs.arc files
  • undefined values delete any env vars of the same name set via .env or prefs.arc files
• port - String or Number - Specify HTTP port
  • Defaults to 3333
• quiet - Boolean - Disables (most) logging
• runStartupCommands - Boolean - Disable @sandbox-startup commands
  • Defaults to true
• runtimeCheck - String - Check for runtime version mismatches
  • If set to warn Sandbox will warn of mismatches in stdout
  • If set to error (suggested for test environments) Sandbox will fail to start up
  • Does not run by default
• symlink - Boolean - Use symlinking to Architect shared code from within each Lambda's dependencies (e.g. src/http/get-index/node_modules/@architect/shared → src/shared)
  • Defaults to true
  • false copies shared code into each Lambda, which can result much slower startup and dependency rehydration speeds
• watcher - Boolean - Disable the Sandbox file watcher (and related Sandbox file watcher plugin API)
  • Defaults to true

Start and shut down the Sandbox; unless you have specific per-service needs, we generally advise most folks use this interface for testing

Starts the Sandbox; first checks that ports are available to consume, prints a banner, loads Architect and userland environment variables, hydrates application dependencies, and starts various Sandbox services (including @events, @queues, @tables, @indexes, @http, @static and @ws).

Invokes callback once everything is ready, or returns a promise if callback is falsy.

Shuts down anything started by sandbox.start(). Invokes callback once shut down, or returns a promise if callback is falsy.

Useful for starting a subset of Sandbox's service functionality in your tests, either for increased isolation, or to enhance throughput

Starts up a local event bus, enabling interprocess communication for @queues and @events functions (if defined in your Architect project manifest).

Invokes callback once everything is ready, or returns a promise if callback is falsy.

Shuts down anything started by sandbox.events.start(). Invokes callback once shut down, or returns a promise if callback is falsy.

Starts up a local HTTP and WebSocket servers, enabling @http or [@websocket][websocket] functions (if defined in your Architect project manifest).

Invokes callback once everything is ready, or returns a promise if callback is falsy.

Shuts down anything started by sandbox.http.start(). Invokes callback once shut down, or returns a promise if callback is falsy.

Starts up a local in-memory DynamoDB server, enabling @tables or [@indexes][indexes] functions (if defined in your Architect project manifest).

Invokes callback once everything is ready, or returns a promise if callback is falsy.

Shuts down anything started by sandbox.tables.start(). Invokes callback once shut down, or returns a promise if callback is falsy.

let sandbox = require('@architect/sandbox')
let test = require('tape)

test('Start the Sandbox', async t => {
  t.plan(1)
  let result = await sandbox.start()
  t.equal(result, 'Sandbox successfully started')
})

test('Tests go here', t => {
  // Make use of various Sandbox resources in your tests...
})

test('Shut down the Sandbox', async t => {
  t.plan(1)
  let result = await sandbox.end()
  t.equal(result, 'Sandbox successfully shut down')
})

let sandbox = require('@architect/sandbox')

beforeAll(async () => {
  let result = await sandbox.start()
  expect(result).toBe('Sandbox successfully started')
})

afterAll(async () => {
  let result = await sandbox.end()
  expect(result).toBe('Sandbox successfully shut down')
})

test('Tests go here', () => {
  // Make use of various Sandbox resources in your tests...
})

The tests in this repository require that you have the deno runtime installed on your local machine. Install deno by visiting https://deno.land/#installation.

To work on sandbox, first make sure you have installed the dependencies:

npm install

To run all tests, including the linter:

npm test

To run just the linter:

npm run lint

To run just the unit tests (which are located under test/unit):

npm run test:unit

To get a code coverage report based on unit test execution:

npm run coverage

To run just the integration tests (which are located under `test/integration'):

npm run test:integration

To make tests run extra noisy-like, add the NOISY_TESTS=true env var