LocalStack lets you run integration tests against emulated AWS APIs on a developer machine or in a CI job. A reliable loop is: start LocalStack, point AWS tooling at its endpoint, create the resources your tests need, run the tests, and retain logs and reports. This checks how your application interacts with the emulated services; it does not prove that every service, account setting, or production condition will behave identically in real AWS.
What LocalStack tests—and what it does not
LocalStack is a containerized AWS service emulator intended for local development and CI. LocalStack’s Getting Started Overview names Lambda, DynamoDB, S3, and SQS among the services it supports. Its overview reports support for more than 80 services, but that is not a guarantee of complete behavioral parity. Check that the exact APIs and behaviors your application uses are covered.
As an Amazon Associate I earn from qualifying purchases.
Use LocalStack to exercise integration paths such as creating a queue, writing an object, or invoking a function without directing that test run to an AWS account. Keep a separate validation step against AWS when behavior depends on real AWS, a particular account configuration, or production conditions.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Prerequisites and setup choices
What you need
- A working Docker installation and a Docker daemon that the LocalStack process can reach.
- A LocalStack account and Auth Token for the documented quickstart.
- The AWS CLI, Terraform, or the application’s own SDK and test setup, depending on how you provision resources.
For services that start additional containers, including Lambda and ECS scenarios, Docker socket access and container networking matter. Check the runner’s Docker permissions and network configuration if those services fail to launch.
#1 Best Overall
Choose how to start LocalStack
LocalStack recommends its lstk CLI for an integrated install, authentication, and startup workflow. Docker Compose is useful when a team wants the container configuration checked into its project and reused declaratively. Pin the LocalStack image version in repeatable team or CI environments rather than silently following a changing image tag. See the installation guide for current options.
Run an integration test locally
- Start Docker. Confirm the daemon is available to your user before starting LocalStack.
- Install and authenticate the CLI. Follow LocalStack’s installation instructions, then provide the Auth Token when prompted or as documented for your environment. Do not commit credentials to source control.
- Start LocalStack. Run
lstk start. The local development quickstart uses the endpointlocalhost.localstack.cloud:4566. - Provision only what the test needs. Use
lstk awsorlstk terraform, your infrastructure-as-code setup, or test setup code. Thelstkwrappers route commands to the local service. Alternatively, configure the SDK endpoint explicitly, as described below. - Run the application integration tests. Make the test target explicit so that a misconfigured run cannot accidentally exercise a real AWS account.
- Inspect output and reset state. Review LocalStack logs and test reports. Recreate a clean environment or reset test data between runs when practical, so one test run does not rely on state left by another.
Point an AWS SDK at the local endpoint
AWS clients can target LocalStack with an explicit endpoint such as http://localhost.localstack.cloud:4566 or http://localhost:4566. The exact SDK option differs by language and client; see LocalStack’s AWS SDK guide for the relevant integration.
Explicit endpoint configuration makes the test target visible in application or test setup, but requires that setup to accept a local endpoint. Transparent endpoint injection can avoid changing application code, according to LocalStack’s guide, but makes the destination less visible in the code itself. Choose one approach deliberately and ensure the test environment cannot route unintended traffic to AWS.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallContainerized tests
If the application tests themselves run in containers, hostnames and port reachability differ from a process running directly on the host. Configure the LocalStack endpoint for the test container’s network rather than assuming that localhost refers to the host machine. LocalStack documents language integrations through Testcontainers.
Rank #3
Run LocalStack in CI
Treat LocalStack as a job dependency: authenticate, start it, provision fresh test infrastructure, run tests, and save diagnostics before the runner is torn down. LocalStack’s CI Pipelines Overview and CI Best Practices discuss this workflow.
- Store the Auth Token as a protected secret. Put it in your CI provider’s secret manager and expose it to the job as
LOCALSTACK_AUTH_TOKEN. Never place the token in a checked-in workflow file or print it in logs. - Provide Docker access. Confirm the job can reach a working Docker daemon and socket. Install
lstkand test tools if the runner image does not already include them. - Start LocalStack. Run
lstk start. LocalStack’s GitHub Actions guide says this command waits until the environment is ready. - Provision test infrastructure. Create resources from IaC or test setup code, or intentionally load a snapshot if the job requires one.
- Run tests against the local endpoint. Configure the SDK or test harness explicitly, or use the documented endpoint-injection approach.
- Export diagnostics even on failure. Preserve LocalStack logs, test reports, and relevant artifacts before the runner shuts down. Configure the CI provider’s always-run or equivalent artifact step so a failed test does not discard the evidence needed to diagnose it.
GitHub Actions notes
For GitHub Actions, LocalStack’s current guide advises installing and driving lstk directly and supplying LOCALSTACK_AUTH_TOKEN from GitHub Secrets. The guide says Windows runners cannot run LocalStack natively. For arm64 Lambda emulation, QEMU may be needed and can slow builds; check the guide and workload requirements before selecting a runner architecture.
Keep test state and runs repeatable
Prefer a clean environment per job
Most CI jobs should start from clean state and provision the resources they need. This prevents hidden dependencies on another run’s queues, tables, buckets, or test data. Make setup and cleanup part of the test workflow where feasible.
Use persistence or snapshots intentionally
Persistence and snapshots are options when state must cross job boundaries or when a deliberate preloaded environment is useful. They add a state-management concern: make the snapshot’s contents and version explicit, and avoid letting a test silently depend on stale data. LocalStack’s CI documentation covers state options.
Best Value
Pin the pieces that affect reproducibility
- Pin the LocalStack image version where repeatability matters.
- Keep startup configuration and infrastructure definitions in the project or pipeline configuration.
- Record the selected endpoint strategy and required services in the test setup.
- Save logs and reports for failed as well as successful runs.
Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
lstk start cannot start or connect |
Docker is stopped, unavailable to the current user, or blocked by runner permissions. | Verify the daemon and socket are reachable from the process running lstk; review job-level Docker access. |
| SDK requests fail to reach LocalStack | The client is using the AWS default endpoint, an incorrect local hostname, or a hostname unsuitable for its network. | Check the endpoint configured for the specific SDK and whether the test runs on the host or in a container. Consult the SDK guide. |
| A service such as Lambda or ECS does not launch | The service needs to start additional containers, but Docker socket access or networking is unavailable. | Check Docker permissions, socket mounting, and container-to-container networking on the machine or runner. |
| Tests pass alone but fail in a suite or later CI run | Tests may depend on leftover or shared state, or may collide when run concurrently. | Use isolated resource names and clean setup; reset state between runs unless persistence is an explicit test requirement. |
| GitHub Actions fails on Windows | LocalStack’s GitHub Actions guide says Windows runners cannot run LocalStack natively. | Use a supported runner configuration and recheck the provider guide for current constraints. |
| arm64 Lambda tests are unexpectedly slow | QEMU may be required for arm64 Lambda emulation and can slow builds. | Check the architecture and emulation requirements in LocalStack’s GitHub Actions guide. |
| A feature or service is unavailable for the workload | Service coverage and plan entitlements may not match the test’s needs. | Confirm the required API and feature against the current service coverage and plan documentation. |
Check service and plan availability
LocalStack’s licensing documentation, as of March 23, 2026, describes Base, Ultimate, and Enterprise as commercial subscriptions and Hobby as intended for non-commercial use. Plan requirements and feature access can change. Before adopting a workflow, verify that the current plan and Auth Token status cover the specific services and features the tests require. See LocalStack Plans.
Or skip the browser setup
If a test or workflow needs a website screenshot rather than an AWS service emulator, ScreenshotNeo provides a screenshot API and MCP server. For example, one GET request returns an image or PDF; see the API documentation for request options:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month, with no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
