autotel-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Autotel Testing

Test your autotel instrumentation to verify spans, attributes, errors, and events are emitted correctly.

## Purpose

Guide for writing tests that verify autotel instrumentation. Covers test utilities, assertion patterns, and complete examples.

## When to Use

- Writing tests for instrumented functions
- Verifying span names and attributes
- Testing structured error recording
- Testing request logger output
- Testing product events via track()

## Test Utilities

### createTraceCollector() (recommended)

High-level test utility that collects completed spans for assertion.

```typescript
import { createTraceCollector } from 'autotel/testing';
```

**API:**

- `collector.getSpans()`: returns all completed spans
- `collector.getSpanByName(name)`: find a span by name
- `collector.getSpansByName(name)`: find all spans with a name
- `collector.reset()`: clear collected spans
- `collector.shutdown()`: clean up resources

### createMemoryExporter()

Collects finished spans as plain objects, with no OpenTelemetry SDK types to
satisfy. Use it when you want to assert on span shape directly rather than go
through the collector.

```typescript
import { createMemoryExporter } from 'autotel/testing';

const exporter = createMemoryExporter();
// pass exporter to init(), then:
exporter.findSpan('checkout'); // one span, or undefined
exporter.findSpans('db.query'); // all matching spans
exporter.reset();
```

Each recorded span has `name`, `traceId`, `parentSpanId`, `durationMs`,
`attributes` and `status`.

### InMemorySpanExporter (low-level)

For custom test setups when you need direct access to the exporter.

```typescript
import { InMemorySpanExporter } from 'autotel/exporters';
```

## Test Setup

### With createTraceCollector (vitest)

```typescript
import { describe, it, expect, beforeEach, afterAll } from 'vitest';
import { createTraceCollector } from 'autotel/testing';

const collector = createTraceCollector();

beforeEach(() => {
  collector.reset();
});

afterAll(async () => {
  await collector.shutdown();
});
```

### File Naming Convention

- **Unit tests:** `*.test.ts`: test individual instrumented functions
- **Integration tests:** `*.integration.test.ts`: test full request flows with OTel SDK

Unit tests and integration tests use separate vitest configs in the autotel monorepo.

## Assertion Patterns

### Assert a Span Was Created

```typescript
import { trace } from 'autotel';
import { createTraceCollector } from 'autotel/testing';

const collector = createTraceCollector();

const getUser = trace(async (id: string) => {
  return { id, name: 'Alice' };
});

it('creates a span for getUser', async () => {
  collector.reset();
  await getUser('123');

  const spans = collector.getSpans();
  expect(spans).toHaveLength(1);
  expect(spans[0].name).toBe('getUser');
});
```

### Assert Span Attributes

```typescript
const processOrder = trace((ctx) => async (orderId: string, total: number) => {
  ctx.setAttribute('order.id', orderId);
  ctx.setAttribute('order.total', total);
  return { success: true };
});

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel