Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/architect/sandbox

Architect dev server: run full Architect projects locally & offline in a sandbox
https://github.com/architect/sandbox

Last synced: 20 days ago
JSON representation

Architect dev server: run full Architect projects locally & offline in a sandbox

Lists

README 

        
[](https://www.npmjs.com/package/@architect/sandbox)



## [`@architect/sandbox`](https://www.npmjs.com/package/@architect/sandbox)



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



[![GitHub CI status](https://github.com/architect/sandbox/workflows/Node%20CI/badge.svg)](https://github.com/architect/sandbox/actions?query=workflow%3A%22Node+CI%22)



## 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` - Manually specify HTTP port

  - Defaults to `3333`

- `-h`, `--host` - Specify the host interface for Sandbox to listen on

  - Defaults to `0.0.0.0` (all available interfaces on your machine)

  - To accept local connections only, specify `localhost`

- `-v`, `--verbose` - Enable verbose logging

- `-d`, `--debug` - Enable debug logging

- `-q`, `--quiet` - Disable (most) logging

- `--disable-delete-vendor` - Disable deleting Lambda vendor dirs upon startup

- `--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_ENV` - `testing|staging|production`

  - Defaults to `testing`

- `ARC_HOST` - Specify the host interface for Sandbox to listen on

  - Defaults to `0.0.0.0` (all available interfaces on your machine)

  - To accept local connections only, specify `localhost`

- `ARC_LOCAL`- If present and used in conjunction with `ARC_ENV=staging|production`, emulates live `staging` or `production` environment

  - Uses your [local preferences `@env`](../configuration/local-preferences#%40env) environment variables for the appropriate stage

  - Connects Sandbox to live AWS events and DynamoDB infrastructure

  - Requires valid AWS credentials with the same profile name as defined in your [project manifest](../project-manifest/aws#profile)

- Specify ports:

  - `ARC_PORT` - Manually specify HTTP port

    - Defaults to `3333`

  - `ARC_EVENTS_PORT`- Manually specify event bus port

    - Defaults to `4444`

  - `ARC_TABLES_PORT`- Manually specify local DynamoDB port

    - Defaults to `5555`

  - `ARC_INTERNAL_PORT`- Manually specify internal Sandbox + AWS services port

    - Defaults to `2222`

- `ARC_DB_EXTERNAL` - (Boolean) Use an external DynamoDB tool (such as [AWS NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html))

- `ARC_QUIET` - If present, disable (most) logging



---



## 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](#individual-sandbox-services).)



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)

- `deleteVendor` - **Boolean** - Delete Lambda vendor dirs upon startup

  - Defaults to `true`

- `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-start` 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`



---



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



---



## Example



### Tape



```javascript

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



```javascript

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



[events]: https://arc.codes/reference/arc/events

[http]: https://arc.codes/reference/arc/http

[queues]: https://arc.codes/reference/arc/queues

[tables]: https://arc.codes/reference/arc/tables

[ws]: https://arc.codes/reference/arc/ws