serverless-test-stack-pauser

Serverless Framework plugin for pausing deployed test stacks between CI runs.

The repo also contains the Serverless stack that creates the DynamoDB table used for locks and reversible trigger state.

Deploy the lock table

yarn install
yarn deploy --stage test

The stack outputs:

• LockTableName

Publish the plugin

This repo publishes @uptime.app/serverless-test-stack-pauser from the deploy-npm CircleCI job on master. The job authenticates with NPM_TOKEN and runs yarn publish --patch.

Use in another Serverless service

Install the published plugin:

yarn add --dev @uptime.app/serverless-test-stack-pauser

plugins:
  - '@uptime.app/serverless-test-stack-pauser'

custom:
  testStackPauser:
    exclude:
      refs:
        - SomeLogicalResourceId

If no resources need excluding, no custom.testStackPauser config is needed. The plugin uses the test-serverless-test-stack-pauser-locks table in eu-west-1 and fails if it has not been deployed.

wake and sleep only run when the resolved stage is test. The lock owner is resolved from TEST_STACK_PAUSER_OWNER, CI workflow metadata such as CIRCLE_WORKFLOW_ID, or a local machine fallback.

Commands

sls test-stack-pauser ensure-awake --stage test
sls test-stack-pauser wake --stage test
sls deploy --stage test
sls test-stack-pauser sleep --stage test
sls test-stack-pauser status --stage test
sls test-stack-pauser unlock --stage test
sls test-stack-pauser unlock --stage test --force

ensure-awake is an explicit, idempotent CI-friendly variant of wake: it restores saved trigger state when the stack is sleeping, or just ensures the current owner still holds an awake lock when the stack is already awake.

ensure-awake force-enables paused Lambda event source mappings, restores the saved reversible state, and fails if the stack still looks paused after restoration.

sleep requires the current owner to already hold the active lock. If there is no active lock, it exits without changing the stack. If another owner holds the active lock, it fails.

CircleCI shape for consuming services:

- run:
    name: Ensure test stack is awake
    command: yarn sls test-stack-pauser ensure-awake --stage test

- run:
    name: Deploy to test
    command: yarn deploy --stage test

- run:
    name: Run tests
    command: yarn test:ci

- run:
    name: Sleep test stack if this workflow owns the lock
    command: yarn sls test-stack-pauser sleep --stage test

What Sleep Does

• Acquires a lock in DynamoDB so another CI run cannot wake/deploy/sleep the same stack at the same time.
• Discovers deployed CloudFormation resources for the service stack.
• Disables Lambda event source mappings, including SQS, DynamoDB Streams, and Kinesis.
• Removes EventBridge Lambda targets, applies an impossible SNS filter policy to Lambda and SQS SNS subscriptions, and removes S3 Lambda notification configs.
• Pauses scheduled Glue crawlers and deactivates scheduled or conditional Glue triggers.
• Destructively empties discovered DynamoDB tables, using eu-west-1 for Global Tables and the stack region otherwise.
• Destructively empties discovered S3 buckets, including object versions and delete markers.

sleep attempts to stop new SNS deliveries to paused subscriptions before they reach Lambda or SQS. wake still purges queued SQS messages before re-enabling Lambda event source mappings, then restores trigger state. DynamoDB and S3 data is not restored.

SNS subscription filter policy changes are eventually consistent, so pausing SNS subscriptions reduces new deliveries but does not guarantee that no messages reach SQS immediately after sleep.

Glue support in v1 is limited to crawler schedules and trigger activation state. Glue jobs and workflows are not directly paused; scheduled job activity is controlled indirectly through Glue triggers.