|
| 1 | +# analytics-go e2e-cli |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Go 1.17+ |
| 8 | +- (For `run-e2e.sh`) Node.js 18+ and the `sdk-e2e-tests` repo checked out alongside this repo |
| 9 | + |
| 10 | +## Building |
| 11 | + |
| 12 | +```bash |
| 13 | +cd e2e-cli |
| 14 | +go build -o e2e-cli-bin ./... |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +```bash |
| 20 | +./e2e-cli-bin --input '<JSON>' |
| 21 | +``` |
| 22 | + |
| 23 | +The CLI writes debug/log information to **stderr** and the JSON result to **stdout**. |
| 24 | + |
| 25 | +Exit code is `0` on success and `1` on failure. |
| 26 | + |
| 27 | +## Input JSON format |
| 28 | + |
| 29 | +```json |
| 30 | +{ |
| 31 | + "writeKey": "YOUR_WRITE_KEY", |
| 32 | + "apiHost": "https://api.segment.io", |
| 33 | + "sequences": [ |
| 34 | + { |
| 35 | + "delayMs": 0, |
| 36 | + "events": [ |
| 37 | + { |
| 38 | + "type": "track", |
| 39 | + "event": "Button Clicked", |
| 40 | + "userId": "user-123", |
| 41 | + "properties": { "plan": "pro" } |
| 42 | + }, |
| 43 | + { |
| 44 | + "type": "identify", |
| 45 | + "userId": "user-123", |
| 46 | + "traits": { "email": "user@example.com" } |
| 47 | + }, |
| 48 | + { |
| 49 | + "type": "page", |
| 50 | + "userId": "user-123", |
| 51 | + "name": "Home" |
| 52 | + }, |
| 53 | + { |
| 54 | + "type": "screen", |
| 55 | + "userId": "user-123", |
| 56 | + "name": "Main Screen" |
| 57 | + }, |
| 58 | + { |
| 59 | + "type": "alias", |
| 60 | + "userId": "new-id", |
| 61 | + "previousId": "old-id" |
| 62 | + }, |
| 63 | + { |
| 64 | + "type": "group", |
| 65 | + "userId": "user-123", |
| 66 | + "groupId": "group-456", |
| 67 | + "traits": { "name": "Acme Corp" } |
| 68 | + } |
| 69 | + ] |
| 70 | + } |
| 71 | + ], |
| 72 | + "config": { |
| 73 | + "flushAt": 15, |
| 74 | + "flushInterval": 1000, |
| 75 | + "maxRetries": 3, |
| 76 | + "timeout": 10 |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +### Top-level fields |
| 82 | + |
| 83 | +| Field | Type | Description | |
| 84 | +|-------------|--------|--------------------------------------------------| |
| 85 | +| `writeKey` | string | Segment write key used to authenticate requests | |
| 86 | +| `apiHost` | string | Full API endpoint URL (e.g. `https://api.segment.io`) | |
| 87 | +| `sequences` | array | List of event sequences (run in order) | |
| 88 | +| `config` | object | SDK configuration overrides | |
| 89 | + |
| 90 | +### Sequence fields |
| 91 | + |
| 92 | +| Field | Type | Description | |
| 93 | +|-----------|-------|---------------------------------------------------------------------| |
| 94 | +| `delayMs` | int | Milliseconds to wait before sending this sequence's events | |
| 95 | +| `events` | array | List of events to enqueue | |
| 96 | + |
| 97 | +### Event fields |
| 98 | + |
| 99 | +| Field | Type | Description | |
| 100 | +|---------------|--------|---------------------------------------------------------------------| |
| 101 | +| `type` | string | Event type: `track`, `identify`, `page`, `screen`, `alias`, `group` | |
| 102 | +| `event` | string | Event name (required for `track`) | |
| 103 | +| `userId` | string | User ID | |
| 104 | +| `anonymousId` | string | Anonymous ID (used when `userId` is absent) | |
| 105 | +| `messageId` | string | Optional explicit message ID | |
| 106 | +| `previousId` | string | Previous user ID (required for `alias`) | |
| 107 | +| `groupId` | string | Group ID (required for `group`) | |
| 108 | +| `name` | string | Page or screen name | |
| 109 | +| `timestamp` | string | ISO 8601 timestamp (RFC3339), e.g. `2024-01-15T10:30:00Z` | |
| 110 | +| `properties` | object | Event properties (for `track`, `page`, `screen`) | |
| 111 | +| `traits` | object | User or group traits (for `identify`, `group`) | |
| 112 | +| `integrations`| object | Integration-specific settings | |
| 113 | + |
| 114 | +### Config fields |
| 115 | + |
| 116 | +| Field | Type | Description | |
| 117 | +|-----------------|------|------------------------------------------| |
| 118 | +| `flushAt` | int | Max events per batch (default: 250) | |
| 119 | +| `flushInterval` | int | Flush interval in milliseconds | |
| 120 | +| `maxRetries` | int | (informational, not directly used by SDK)| |
| 121 | +| `timeout` | int | Timeout in seconds (informational) | |
| 122 | + |
| 123 | +## Output JSON format |
| 124 | + |
| 125 | +On success: |
| 126 | + |
| 127 | +```json |
| 128 | +{"success": true, "sentBatches": 1} |
| 129 | +``` |
| 130 | + |
| 131 | +On failure: |
| 132 | + |
| 133 | +```json |
| 134 | +{"success": false, "sentBatches": 0, "error": "description of error"} |
| 135 | +``` |
| 136 | + |
| 137 | +## Running E2E tests |
| 138 | + |
| 139 | +Use the provided shell script to build the CLI and run the shared `sdk-e2e-tests` suite: |
| 140 | + |
| 141 | +```bash |
| 142 | +# From the e2e-cli directory, with sdk-e2e-tests checked out as a sibling of analytics-go: |
| 143 | +./run-e2e.sh |
| 144 | + |
| 145 | +# Override the e2e test directory: |
| 146 | +E2E_TESTS_DIR=/path/to/sdk-e2e-tests ./run-e2e.sh |
| 147 | + |
| 148 | +# Pass additional arguments to run-tests.sh: |
| 149 | +./run-e2e.sh --suite basic |
| 150 | +``` |
| 151 | + |
| 152 | +The script: |
| 153 | +1. Builds the `e2e-cli-bin` binary using `go build` |
| 154 | +2. Invokes `sdk-e2e-tests/scripts/run-tests.sh` with the appropriate `--sdk-dir` and `--cli` flags |
0 commit comments