segmentio · MichaelGHSeg · May 11, 2026 · May 7, 2026 · May 8, 2026 · May 8, 2026
diff --git a/.circleci/config.yml b/.circleci/config.yml
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [v3.0]
+  pull_request:
+    branches: [v3.0]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version: ['1.21', '1.22', '1.23']
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Download dependencies
+        run: go get -v -t ./...
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race -coverprofile=cover.out .
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-go${{ matrix.go-version }}
+          path: cover.out
+          retention-days: 7
diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml
@@ -0,0 +1,61 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [v3.0]
+  pull_request:
+    branches: [v3.0]
+  workflow_dispatch:
+    inputs:
+      e2e_tests_ref:
+        description: 'Branch or ref of sdk-e2e-tests to use'
+        required: false
+        default: 'main'
+
+jobs:
+  e2e-tests:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout SDK
+        uses: actions/checkout@v4
+        with:
+          path: sdk
+
+      - name: Checkout sdk-e2e-tests
+        uses: actions/checkout@v4
+        with:
+          repository: segmentio/sdk-e2e-tests
+          ref: ${{ inputs.e2e_tests_ref || 'main' }}
+          token: ${{ secrets.E2E_TESTS_TOKEN }}
+          path: sdk-e2e-tests
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: sdk/go.mod
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Build e2e-cli
+        working-directory: sdk/e2e-cli
+        run: go build -o e2e-cli-bin ./...
+
+      - name: Run E2E tests
+        working-directory: sdk-e2e-tests
+        run: |
+          ./scripts/run-tests.sh \
+            --sdk-dir "${{ github.workspace }}/sdk/e2e-cli" \
+            --cli "${{ github.workspace }}/sdk/e2e-cli/e2e-cli-bin"
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-results
+          path: sdk-e2e-tests/test-results/
+          if-no-files-found: ignore
diff --git a/.github/workflows/publish-e2e-cli.yml b/.github/workflows/publish-e2e-cli.yml
@@ -0,0 +1,36 @@
+name: Publish E2E CLI
+
+on:
+  push:
+    branches: [v3.0]
+    paths:
+      - 'e2e-cli/**'
+      - '*.go'
+      - 'go.mod'
+      - 'go.sum'
+  schedule:
+    - cron: '0 0 1 * *'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout SDK
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Build e2e-cli
+        working-directory: e2e-cli
+        run: go build -o e2e-cli-bin ./...
+
+      - name: Upload CLI artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-cli-go
+          path: e2e-cli/e2e-cli-bin
+          retention-days: 90
diff --git a/e2e-cli/.gitignore b/e2e-cli/.gitignore
@@ -0,0 +1 @@
+e2e-cli-bin
diff --git a/e2e-cli/README.md b/e2e-cli/README.md
@@ -0,0 +1,154 @@
+# analytics-go e2e-cli
+
+A small CLI tool used for end-to-end testing of the `analytics-go` SDK. It accepts a JSON description of event sequences, sends those events through the real SDK, and reports the result.
+
+## Prerequisites
+
+- Go 1.17+
+- (For `run-e2e.sh`) Node.js 18+ and the `sdk-e2e-tests` repo checked out alongside this repo
+
+## Building
+
+```bash
+cd e2e-cli
+go build -o e2e-cli-bin ./...
+```
+
+## Usage
+
+```bash
+./e2e-cli-bin --input '<JSON>'
+```
+
+The CLI writes debug/log information to **stderr** and the JSON result to **stdout**.
+
+Exit code is `0` on success and `1` on failure.
+
+## Input JSON format
+
+```json
+{
+  "writeKey": "YOUR_WRITE_KEY",
+  "apiHost": "https://api.segment.io",
+  "sequences": [
+    {
+      "delayMs": 0,
+      "events": [
+        {
+          "type": "track",
+          "event": "Button Clicked",
+          "userId": "user-123",
+          "properties": { "plan": "pro" }
+        },
+        {
+          "type": "identify",
+          "userId": "user-123",
+          "traits": { "email": "user@example.com" }
+        },
+        {
+          "type": "page",
+          "userId": "user-123",
+          "name": "Home"
+        },
+        {
+          "type": "screen",
+          "userId": "user-123",
+          "name": "Main Screen"
+        },
+        {
+          "type": "alias",
+          "userId": "new-id",
+          "previousId": "old-id"
+        },
+        {
+          "type": "group",
+          "userId": "user-123",
+          "groupId": "group-456",
+          "traits": { "name": "Acme Corp" }
+        }
+      ]
+    }
+  ],
+  "config": {
+    "flushAt": 15,
+    "flushInterval": 1000,
+    "maxRetries": 3,
+    "timeout": 10
+  }
+}
+```
+
+### Top-level fields
+
+| Field       | Type   | Description                                      |
+|-------------|--------|--------------------------------------------------|
+| `writeKey`  | string | Segment write key used to authenticate requests  |
+| `apiHost`   | string | Full API endpoint URL (e.g. `https://api.segment.io`) |
+| `sequences` | array  | List of event sequences (run in order)           |
+| `config`    | object | SDK configuration overrides                      |
+
+### Sequence fields
+
+| Field     | Type  | Description                                                         |
+|-----------|-------|---------------------------------------------------------------------|
+| `delayMs` | int   | Milliseconds to wait before sending this sequence's events          |
+| `events`  | array | List of events to enqueue                                           |
+
+### Event fields
+
+| Field         | Type   | Description                                                         |
+|---------------|--------|---------------------------------------------------------------------|
+| `type`        | string | Event type: `track`, `identify`, `page`, `screen`, `alias`, `group` |
+| `event`       | string | Event name (required for `track`)                                   |
+| `userId`      | string | User ID                                                             |
+| `anonymousId` | string | Anonymous ID (used when `userId` is absent)                         |
+| `messageId`   | string | Optional explicit message ID                                        |
+| `previousId`  | string | Previous user ID (required for `alias`)                             |
+| `groupId`     | string | Group ID (required for `group`)                                     |
+| `name`        | string | Page or screen name                                                 |
+| `timestamp`   | string | ISO 8601 timestamp (RFC3339), e.g. `2024-01-15T10:30:00Z`          |
+| `properties`  | object | Event properties (for `track`, `page`, `screen`)                    |
+| `traits`      | object | User or group traits (for `identify`, `group`)                      |
+| `integrations`| object | Integration-specific settings                                       |
+
+### Config fields
+
+| Field           | Type | Description                              |
+|-----------------|------|------------------------------------------|
+| `flushAt`       | int  | Max events per batch (default: 250)      |
+| `flushInterval` | int  | Flush interval in milliseconds           |
+| `maxRetries`    | int  | (informational, not directly used by SDK)|
+| `timeout`       | int  | Timeout in seconds (informational)       |
+
+## Output JSON format
+
+On success:
+
+```json
+{"success": true, "sentBatches": 1}
+```
+
+On failure:
+
+```json
+{"success": false, "sentBatches": 0, "error": "description of error"}
+```
+
+## Running E2E tests
+
+Use the provided shell script to build the CLI and run the shared `sdk-e2e-tests` suite:
+
+```bash
+# From the e2e-cli directory, with sdk-e2e-tests checked out as a sibling of analytics-go:
+./run-e2e.sh
+
+# Override the e2e test directory:
+E2E_TESTS_DIR=/path/to/sdk-e2e-tests ./run-e2e.sh
+
+# Pass additional arguments to run-tests.sh:
+./run-e2e.sh --suite basic
+```
+
+The script:
+1. Builds the `e2e-cli-bin` binary using `go build`
+2. Invokes `sdk-e2e-tests/scripts/run-tests.sh` with the appropriate `--sdk-dir` and `--cli` flags
diff --git a/e2e-cli/e2e-config.json b/e2e-cli/e2e-config.json
@@ -0,0 +1,7 @@
+{
+  "sdk": "go",
+  "test_suites": "basic",
+  "auto_settings": false,
+  "patch": null,
+  "env": {}
+}
diff --git a/e2e-cli/go.mod b/e2e-cli/go.mod
@@ -0,0 +1,14 @@
+module github.com/segmentio/analytics-go/v3/e2e-cli
+
+go 1.17
+
+require github.com/segmentio/analytics-go/v3 v3.0.0
+
+require (
+	github.com/bmizerany/assert v0.0.0-20160611221934-b7ed37b82869 // indirect
+	github.com/google/uuid v1.3.0 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/segmentio/backo-go v1.0.0 // indirect
+)
+
+replace github.com/segmentio/analytics-go/v3 => ../
diff --git a/e2e-cli/go.sum b/e2e-cli/go.sum
@@ -0,0 +1,21 @@
+github.com/bmizerany/assert v0.0.0-20160611221934-b7ed37b82869 h1:DDGfHa7BWjL4YnC6+E63dPcxHo2sUxDIu8g3QgEJdRY=
+github.com/bmizerany/assert v0.0.0-20160611221934-b7ed37b82869/go.mod h1:Ekp36dRnpXw/yCqJaO+ZrUyxD+3VXMFFr56k5XYrpB4=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
+github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/segmentio/backo-go v1.0.0 h1:kbOAtGJY2DqOR0jfRkYEorx/b18RgtepGtY3+Cpe6qA=
+github.com/segmentio/backo-go v1.0.0/go.mod h1:kJ9mm9YmoWSkk+oQ+5Cj8DEoRCX2JT6As4kEtIIOp1M=
+github.com/segmentio/conf v1.2.0/go.mod h1:Y3B9O/PqqWqjyxyWWseyj/quPEtMu1zDp/kVbSWWaB0=
+github.com/segmentio/go-snakecase v1.1.0/go.mod h1:jk1miR5MS7Na32PZUykG89Arm+1BUSYhuGR6b7+hJto=
+github.com/segmentio/objconv v1.0.1/go.mod h1:auayaH5k3137Cl4SoXTgrzQcuQDmvuVtZgS0fb1Ahys=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/go-playground/mold.v2 v2.2.0/go.mod h1:XMyyRsGtakkDPbxXbrA5VODo6bUXyvoDjLd5l3T0XoA=
+gopkg.in/validator.v2 v2.0.0-20180514200540-135c24b11c19/go.mod h1:o4V0GXN9/CAmCsvJ0oXYZvrZOe7syiDZSN1GWGZTGzc=
+gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=