Segment analytics-go

To build the CLI tool, navigate to the e2e-cli directory and use the Go build command. This produces a binary named e2e-cli-bin.

cd e2e-cli
go build -o e2e-cli-bin ./...

You can install the Segment analytics client for Go using go get. It is recommended to use a package version management system (like Go vendor directories) to protect against breaking changes between major versions.

go get https://github.com/segmentio/analytics-go

If you have the sdk-e2e-tests repository checked out as a sibling to the analytics-go repository, you can use run-e2e.sh to build the CLI and run the full test suite.

Prerequisites:

• Go 1.17+
• Node.js 18+ (for run-e2e.sh)
• sdk-e2e-tests repo checked out alongside this repo.

# 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

You can override SDK configuration using the config object in your input JSON.

The Integrations type is a map used to enable or disable specific integrations (like Salesforce or Marketo) within analytics messages. It is a free-form map where values are typically booleans.

To use it, initialize an Integrations instance using NewIntegrations() and then chain methods to configure your requirements. Any value other than false is interpreted as enabling the integration.

analytics.Track{
	UserId:       "0123456789",
	Integrations: analytics.NewIntegrations()
		.EnableAll()
		.Disable("Salesforce")
		.Disable("Marketo"),
}

If you need to include metadata that is not covered by the standard Segment Spec fields, use the Extra field in the Context struct.

Because Context implements the json.Marshaler interface, any key-value pairs added to the Extra map will be flattened into the top-level JSON object during serialization. If a key in Extra conflicts with a standard field name, the standard field's value will take precedence.

ctx := analytics.Context{
    // Standard field
    Locale: "en-US",
    // Extension field
    Extra: map[string]interface{}{
        "internal_id": 12345,
    },
}
// Serialized JSON will look like:
// {
//   "locale": "en-US",
//   "internal_id": 12345
// }

The CLI accepts a JSON description of event sequences via the --input flag. It sends these events through the real SDK and reports the result.

• stdout: Contains the JSON result.
• stderr: Contains debug and log information.
• Exit Code 0: Success.
• Exit Code 1: Failure.

./e2e-cli-bin --input '<JSON>'

To use the library, instantiate a client using analytics.New() with your Segment Write Key. You can then send events asynchronously using client.Enqueue(). Finally, call client.Close() to flush any remaining queued messages and shut down the client gracefully.

package main

import (
    "os"

    "github.com/segmentio/analytics-go"
)

func main() {
    // Instantiates a client to use send messages to the segment API.
    client := analytics.New(os.Getenv("SEGMENT_WRITE_KEY"))

    // Enqueues a track event that will be sent asynchronously.
    client.Enqueue(analytics.Track{
        UserId: "test-user",
        Event:  "test-snippet",
    })

    // Flushes any queued messages and closes the client.
    client.Close()
}

The CLI returns a JSON object indicating the result of the event sequence execution.

On success:

{"success": true, "sentBatches": 1}

On failure:

{"success": false, "sentBatches": 0, "error": "description of error"}

The input JSON defines the authentication, the sequence of events to simulate, and SDK configuration overrides.

Top-level fields

• writeKey (string): Segment write key for authentication.
• apiHost (string): Full API endpoint URL (e.g., https://api.segment.io).
• sequences (array): List of event sequences to run in order.
• config (object): SDK configuration overrides.

{
  "writeKey": "YOUR_WRITE_KEY",
  "apiHost": "https://api.segment.io",
  "sequences": [
    {
      "delayMs": 0,
      "events": [
        {
          "type": "track",
          "event": "Button Clicked",
          "userId": "user-123",
          "properties": { "plan": "pro" }
        }
      ]
    }
  ],
  "config": {
    "flushAt": 15,
    "flushInterval": 1000,
    "maxRetries": 3,
    "timeout": 10
  }
}