@architect/sandbox
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/architect__sandbox package

    4.5.2 • Public • Published

    @architect/sandbox

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

    GitHub CI status

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

    Environment variables

    • 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

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

    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/sharedsrc/shared)
      • Defaults to true
      • false copies shared code into each Lambda, which can result much slower startup and dependency rehydration speeds

    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, @queues, @tables, @indexes, @http, @static and @ws).

    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 (@events, @queues)

    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 (@http, @static, @ws)

    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 (@tables, @indexes)

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

    Development

    Requirements

    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.

    Running Tests

    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

    Keywords

    none

    Install

    npm i @architect/sandbox

    DownloadsWeekly Downloads

    4,688

    Version

    4.5.2

    License

    Apache-2.0

    Unpacked Size

    218 kB

    Total Files

    86

    Last publish

    Collaborators

    • brianleroux
    • dam
    • kborchers
    • ryanblock
    • architectci
    • filmaj