@architect/sandbox
Architect local development environment: run full Architect projects locally & offline in an in-memory sandbox
Install
npm i @architect/sandbox
CLI
Start the sandbox
npx sandbox
Or if running Sandbox from within @architect/architect
:
npx arc sandbox
CLI options
-p
,--port
,port
- Manually specify HTTP port- Defaults to
3333
- Defaults to
-v
,--verbose
,verbose
- Enable verbose logging
Environment variables
ARC_API_TYPE
- Set the API Gateway API type- Can be one of
http
(aliased tohttpv2
),httpv1
,rest
- Defaults to
http
- Can be one of
ARC_QUIET
- If present, disable (most) loggingPORT
- Manually specify HTTP port- Defaults to
3333
- Defaults to
ARC_EVENTS_PORT
- Manually specify event bus port- Defaults to
3334
- Defaults to
ARC_TABLES_PORT
- Manually specify local DynamoDB port- Defaults to
3335
- Defaults to
ARC_LOCAL
- If present and used in conjunction withNODE_ENV=staging|production
, emulates livestaging
orproduction
environment- Uses your local
.arc-env
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
- Uses your local
API
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.)
All methods must be passed an options object that may containing the following parameters:
port
- String - Manually specify HTTP port- Defaults to
3333
- Defaults to
quiet
- Boolean - Disables (most) logging
Sandbox
Start and shut down the Sandbox; unless you have specific per-service needs, we generally advise most folks use this interface for testing
sandbox.start(options[, callback]) → [Promise]
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
, tables
and http
).
Invokes callback
once everything is ready, or returns a promise
if callback
is falsy.
sandbox.end([callback]) → [Promise]
Shuts down anything started by sandbox.start()
. Invokes callback
once shut down, or returns a promise
if callback
is falsy.
Individual Sandbox services
Useful for starting a subset of Sandbox's service functionality in your tests, either for increased isolation, or to enhance throughput
@events
, @queues
)
Events (sandbox.events.start(options[, callback]) → [Promise]
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.
sandbox.events.end([callback]) → [Promise]
Shuts down anything started by sandbox.events.start()
. Invokes callback
once shut down, or returns a promise
if callback
is falsy.
@http
, @static
, @ws
)
HTTP (sandbox.http.start(options[, callback]) → [Promise]
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.
sandbox.http.end([callback]) → [Promise]
Shuts down anything started by sandbox.http.start()
. Invokes callback
once shut down, or returns a promise
if callback
is falsy.
@tables
, @indexes
)
Tables (sandbox.tables.start(options[, callback]) → [Promise]
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.
sandbox.tables.end([callback]) → [Promise]
Shuts down anything started by sandbox.tables.start()
. Invokes callback
once shut down, or returns a promise
if callback
is falsy.
Example
Tape
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')
})
Jest
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...
})