Queues

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.

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.

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.