# Queues

How jobs and external workers produce, claim, complete, and fail units of work.

Queues let jobs and workers coordinate units of work inside a project. They are useful when browser automation needs to produce or consume tasks rather than just pass or fail a single test.

## Queue shape

A queue item has a reference, status, priority, optional tags, and arbitrary JSON `data`. Common statuses are new, in progress, completed, failed, abandoned, or retryable depending on the endpoint used.

Queue items are intentionally generic. You decide whether `data` represents an invoice, test account, URL crawl target, import row, or another domain object.

## Producer job

A Playwright script can produce items by calling the queue API. The slow happy-path producer is a good pattern: resolve the backend URL, read the project queue variables, then post items with structured `data`.

```ts
const PROJECT_ID = requiredEnv('HAPPY_PATH_QUEUE_PROJECT_ID');
const QUEUE_ID = requiredEnv('HAPPY_PATH_QUEUE_ID');
const API_KEY = requiredEnv('HAPPY_PATH_QUEUE_API_KEY');

await api(backendUrl, API_KEY, 'POST', `/api/queues/${QUEUE_ID}/items`, {
  reference: `slow-demo-${Date.now()}`,
  priority: 10,
  tags: ['slow-demo'],
  data: { kind: 'slow-demo-item' },
});
```

## Consumer job or worker

Consumers claim work with the next-item endpoint, process the returned item, then complete or fail it.

```ts
const claimed = await api<QueueItem[] | undefined>(
  backendUrl,
  API_KEY,
  'POST',
  `/api/queues/${QUEUE_ID}/next`,
  { worker_id: 'slow-queue-consumer' },
  true
);
```

If no item is available, consumers should exit cleanly rather than fail the entire run.

## API key scopes

Queue workers usually need:

- `queues:read` to inspect queue state.
- `queues:write` to create queue items.
- `queues:execute` to claim, complete, fail, abandon, or retry work.
- `variables:use` if the worker script reads project variables.

## Operational advice

Use stable references when duplicate detection matters. Use priority to control order. Put domain-specific payload in `data`, not in tags. Keep tags short and useful for filtering or debugging.

For long-running queue demos, set explicit Playwright timeouts and log each item reference as it is produced or consumed.