Go SDK - Local Web Services

Quick Start

Install, create a session at the start of your test, and write assertions using standard Go testing. Local services start as a subprocess — your AWS SDK v2 clients are pre-configured to point at them.

1

Install

              go get github.com/local-web-services/local-web-services-go-sdk
# also requires local-web-services (Python) for ldk dev
pip install local-web-services
            

2

Write your test

              // order_processor_test.go
package main

import (
    "context"
    "testing"

    "github.com/aws/aws-sdk-go-v2/service/sfn"
    "github.com/local-web-services/local-web-services-go-sdk/lws"
)

func TestProcessOrder_runsStateMachineAndReturnsResult(t *testing.T) {
    // Start ldk dev and discover resources from terraform/
    session, err := lws.FromHcl("terraform")
    if err != nil {
        t.Fatalf("failed to start lws session: %v", err)
    }
    defer session.Close()

    sfnClient := session.SFNClient()

    // Resolve the state machine ARN
    result, err := sfnClient.ListStateMachines(context.Background(), &sfn.ListStateMachinesInput{})
    if err != nil || len(result.StateMachines) == 0 {
        t.Fatalf("could not list state machines: %v", err)
    }
    stateMachineArn := *result.StateMachines[0].StateMachineArn

    processor := NewOrderProcessor(sfnClient)
    output, err := processor.ProcessOrder(context.Background(), "order-001", stateMachineArn)

    if err != nil {
        t.Fatalf("ProcessOrder returned error: %v", err)
    }
    if output["orderId"] != "order-001" {
        t.Errorf("got orderId %q, want %q", output["orderId"], "order-001")
    }
}
            

3

Run your tests

go test ./...

The session starts ldk dev and waits for services to be ready before your test body runs. defer session.Close() stops the subprocess when the test finishes.

Resource Declaration

Use lws.FromHcl to auto-discover resources from Terraform, or declare them explicitly with lws.New.

Auto-discover from HCL

            // Reads .tf files in "terraform/", starts ldk dev,
// and pre-creates all declared resources
session, err := lws.FromHcl("terraform")
if err != nil {
    t.Fatal(err)
}
defer session.Close()

sfnClient := session.SFNClient()
// state machine already exists — run your test
          

Explicit declaration

            spec := lws.SessionSpec{
    Tables: []lws.TableSpec{
        {Name: "Orders", PartitionKey: "id"},
    },
    Queues: []string{"OrderQueue"},
    StateMachines: []lws.StateMachineSpec{
        {Name: "OrderProcessor", Definition: definitionJSON},
    },
}

session, err := lws.New(spec)
if err != nil {
    t.Fatal(err)
}
defer session.Close()
          

Session API

All factory functions block until ldk dev is ready and all resources have been created.

Factory functions

        import "github.com/local-web-services/local-web-services-go-sdk/lws"

// Auto-discover from HCL .tf files
session, err := lws.FromHcl("../my-terraform-project")

// Explicit resource declaration
session, err := lws.New(lws.SessionSpec{
    Tables: []lws.TableSpec{
        {Name: "Orders", PartitionKey: "id"},
        {Name: "Products", PartitionKey: "sku", SortKey: "version"},
    },
    Queues: []string{"OrderQueue", "DeadLetterQueue"},
    StateMachines: []lws.StateMachineSpec{
        {Name: "OrderProcessor", Definition: definitionJSON},
    },
})

// Always close after your tests
defer session.Close()
      

Client methods

        dynamo  := session.DynamoDBClient()       // *dynamodb.Client
sqs     := session.SQSClient()             // *sqs.Client
s3      := session.S3Client()              // *s3.Client
sns     := session.SNSClient()             // *sns.Client
sfn     := session.SFNClient()             // *sfn.Client
ssm     := session.SSMClient()             // *ssm.Client
secrets := session.SecretsManagerClient()  // *secretsmanager.Client

queueURL := session.QueueURL("OrderQueue")  // local SQS URL
port     := session.PortFor("dynamodb")     // port number
      

SessionSpec types

        type SessionSpec struct {
    Tables        []TableSpec
    Queues        []string
    StateMachines []StateMachineSpec
}

type TableSpec struct {
    Name         string
    PartitionKey string
    SortKey      string // optional
}

type StateMachineSpec struct {
    Name       string
    Definition string // JSON state machine definition
    RoleArn    string // optional, defaults to a local test ARN
}
      

Supported Services

Pre-configured clients for all major AWS services supported by Local Web Services.

DynamoDB

session.DynamoDBClient() — returns a *dynamodb.Client pointed at the local emulator. Supports all standard DynamoDB operations.

SQS

session.SQSClient() — returns a *sqs.Client. Use session.QueueURL(name) to resolve local queue URLs.

S3

session.S3Client() — returns a *s3.Client configured for path-style access against the local S3 emulator.

Step Functions

session.SFNClient() — returns a *sfn.Client. State machines declared in SessionSpec are created and ready before your test runs.

SNS

session.SNSClient() — returns a *sns.Client for publishing to topics and managing subscriptions locally.

SSM & Secrets Manager

session.SSMClient() and session.SecretsManagerClient() for parameter store and secrets testing.