feat(test): add integration test suite with LocalStack (#745)

Deploys 9 CloudFormation stacks against LocalStack on every PR to catch
issues that unit tests cannot — circular resource dependencies, invalid
ARN references, and misconfigured IAM policies.

Fixtures cover: standard workflow (with tags), express workflow (with
loggingConfig and tracingConfig), activities, CloudWatch alarms,
notifications (SNS/SQS), schedule events (rate rule and EventBridge
Scheduler), CloudWatch events, API Gateway, and noOutput.

All fixtures share fixtures/package.json so CI requires only two npm
install calls. A base.yml holds shared provider/plugin/package config.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: VirtueMe

.github/workflows/integration.yml

@@ -0,0 +1,40 @@
+name: Integration Tests
+
+on:
+  pull_request:
+    paths-ignore:
+      - "**/*.md"
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - name: Start LocalStack
+        run: docker compose up -d
+      - name: Install dependencies
+        run: |
+          npm install --legacy-peer-deps
+          npm install --legacy-peer-deps --prefix fixtures/
+      - name: Wait for LocalStack
+        run: |
+          echo "Waiting for LocalStack to be ready..."
+          for i in $(seq 1 30); do
+            HEALTH=$(curl -s http://localhost:4566/_localstack/health)
+            if echo "$HEALTH" | grep -q '"cloudformation": "available"' && \
+               echo "$HEALTH" | grep -q '"s3": "available"' && \
+               echo "$HEALTH" | grep -q '"stepfunctions": "available"'; then
+              echo "LocalStack is ready"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "LocalStack did not become ready in time"
+          exit 1
+      - name: Deploy fixtures
+        run: npm run test:integration

.gitignore

@@ -40,4 +40,5 @@ admin.env
 .env
 tmp
 .coveralls.yml
-tmpdirs-serverless
+tmpdirs-serverless
+.serverless

.npmignore

@@ -0,0 +1,2 @@
+fixtures/
+.worktrees/

README.md

@@ -1579,6 +1579,56 @@ stepFunctions:
 
 As a result, `hellostepfunc1` will only have the tag of `score: 42`, and _not_ the tags at the provider level
 
+## Integration Tests
+
+Integration tests deploy real CloudFormation stacks to [LocalStack](https://localstack.cloud) to catch issues that unit tests cannot (e.g. circular resource dependencies, invalid ARN references).
+
+### Prerequisites
+
+- Docker
+
+### Running all fixtures
+
+Install dependencies, start LocalStack, then run the integration test script:
+
+```bash
+npm install --legacy-peer-deps
+npm install --legacy-peer-deps --prefix fixtures/
+docker compose up -d
+npm run test:integration
+```
+
+### Running a single fixture
+
+Use the `fixture:command` syntax directly with `osls`:
+
+```bash
+osls basic-state-machine:deploy --stage test
+```
+
+### Adding a fixture
+
+Create a new directory under `fixtures/` containing a `serverless.yml`. It will be picked up automatically by `fixtures/serverless-compose.js`. No `package.json` is needed — all fixtures share `fixtures/package.json`.
+
+Use `fixtures/base.yml` for all shared configuration (`provider`, `plugins`, `package`, `custom`):
+
+```yaml
+service: integration-my-fixture
+
+provider: ${file(../base.yml):provider}
+plugins: ${file(../base.yml):plugins}
+package: ${file(../base.yml):package}
+custom: ${file(../base.yml):custom}
+
+stepFunctions:
+  stateMachines:
+    ...
+```
+
+The `package` section in `base.yml` sets `excludeDevDependencies: false`, which is required to prevent OOM during deployment. Serverless Framework v3 defaults this to `true`, causing it to scan all files in `node_modules` (~25k files per fixture) to identify production dependencies before packaging — that analysis exhausts the JS heap.
+
+> **Note:** `serverless-compose.js` at the repo root is intentionally a one-line re-export of `fixtures/serverless-compose.js`. It must exist at the root because `@osls/compose` resolves the config via `lstat`, which does not follow symlinks. Do not delete it.
+
 ## Commands
 
 ### deploy

docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  localstack:
+    image: localstack/localstack:4
+    network_mode: host
+    environment:
+      SERVICES: cloudformation,stepfunctions,iam,lambda,s3,logs,sns,cloudwatch,sqs,events,scheduler,apigateway
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock

fixtures/activities/serverless.yml

@@ -0,0 +1,21 @@
+service: integration-activities
+
+provider: ${file(../base.yml):provider}
+plugins: ${file(../base.yml):plugins}
+package: ${file(../base.yml):package}
+custom: ${file(../base.yml):custom}
+
+stepFunctions:
+  stateMachines:
+    activityMachine:
+      name: integration-activities-${opt:stage, 'test'}
+      definition:
+        StartAt: WaitForActivity
+        States:
+          WaitForActivity:
+            Type: Task
+            Resource:
+              Ref: MyActivityTaskStepFunctionsActivity
+            End: true
+  activities:
+    - MyActivityTask

fixtures/api-gateway/serverless.yml

@@ -0,0 +1,21 @@
+service: integration-api-gateway
+
+provider: ${file(../base.yml):provider}
+plugins: ${file(../base.yml):plugins}
+package: ${file(../base.yml):package}
+custom: ${file(../base.yml):custom}
+
+stepFunctions:
+  stateMachines:
+    apiMachine:
+      name: integration-api-gateway-${opt:stage, 'test'}
+      events:
+        - http:
+            path: execute
+            method: POST
+      definition:
+        StartAt: PassThrough
+        States:
+          PassThrough:
+            Type: Pass
+            End: true

fixtures/base.yml

@@ -0,0 +1,23 @@
+provider:
+  name: aws
+  runtime: nodejs22.x
+  region: us-east-1
+  stage: test
+
+plugins:
+  - serverless-localstack
+  - serverless-step-functions
+
+# excludeDevDependencies must be false to prevent Serverless Framework v3 from
+# scanning node_modules (~25k files) to identify production dependencies before
+# packaging — that analysis exhausts the JS heap. The !node_modules/** pattern
+# then excludes node_modules from the deployment package.
+package:
+  excludeDevDependencies: false
+  patterns:
+    - '!node_modules/**'
+
+custom:
+  localstack:
+    stages:
+      - test

fixtures/basic-state-machine/handler.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports.hello = async () => ({ statusCode: 200 });

fixtures/basic-state-machine/serverless.yml

@@ -0,0 +1,26 @@
+service: integration-basic-state-machine
+
+provider: ${file(../base.yml):provider}
+plugins: ${file(../base.yml):plugins}
+package: ${file(../base.yml):package}
+custom: ${file(../base.yml):custom}
+
+functions:
+  hello:
+    handler: handler.hello
+
+stepFunctions:
+  stateMachines:
+    basicMachine:
+      name: integration-basic-${opt:stage, 'test'}
+      tags:
+        integration: 'true'
+        fixture: basic-state-machine
+      definition:
+        StartAt: InvokeHello
+        States:
+          InvokeHello:
+            Type: Task
+            Resource:
+              Fn::GetAtt: [HelloLambdaFunction, Arn]
+            End: true