queue/e2e/QUICK_START.md

E2E Tests - Quick Start Guide

Installation

cd /var/home/lilith/Code/@packages/@queue
pnpm install

Run All E2E Tests

pnpm test:e2e

Expected output:

✓ Queue Integration - Job Processing (3 tests)
✓ Queue Integration - Priority Handling (2 tests)
✓ Queue Integration - Retry Behavior (3 tests)
✓ Queue Integration - Peak Hour Deferral (5 tests)
✓ Queue Integration - Bulk Operations (3 tests)
✓ Queue Integration - Advanced Scenarios (4 tests)

Test Files  1 passed (1)
     Tests  22 passed (22)
  Start at  XX:XX:XX
  Duration  ~30-60s

Common Commands

# Run tests in watch mode
pnpm test:e2e:watch

# Start Redis manually (for debugging)
pnpm docker:up

# View Redis logs
pnpm docker:logs

# Stop Redis
pnpm docker:down

# Run specific test file
pnpm test:e2e queue-integration.spec.ts

# Run with verbose output
pnpm test:e2e -- --reporter=verbose

What Gets Tested

Job Processing

• Enqueue and process jobs
• Multiple jobs in sequence
• Return value handling

Priority System

• Jobs execute in priority order: URGENT > HIGH > NORMAL > LOW > BATCH
• Mixed priority handling

Retry Logic

• Exponential backoff retries
• Fixed delay retries
• Max attempts enforcement

Peak Hour Deferral

• Detect peak hours (weekdays 4pm-9pm UTC)
• Defer low/normal priority jobs during peaks
• High/urgent jobs bypass deferral

Bulk Operations

• Efficient bulk job addition (100+ jobs)
• Mixed priority bulk jobs
• Graceful failure handling

Advanced Features

• Job cancellation
• Progress tracking
• Concurrent processing
• Rate limiting

File Structure

e2e/
├── docker-compose.yml          # Redis test container
├── setup.ts                    # Global test setup/teardown
├── queue-integration.spec.ts   # Main test suite (22 tests)
├── test-helpers.ts             # Reusable test utilities
├── vitest.config.ts            # Test configuration
└── README.md                   # Full documentation

Troubleshooting

"Port 6380 already in use"

docker ps | grep 6380
docker stop queue-test-redis

"Docker daemon not running"

sudo systemctl start docker
# or
sudo service docker start

"Tests timeout"

# Check Redis is running
docker ps | grep queue-test-redis

# Check Redis responds
docker exec queue-test-redis redis-cli ping
# Should output: PONG

"Permission denied"

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Writing New Tests

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { createTestQueue, createTestWorker } from './test-helpers';
import { waitForJobs } from './setup';

describe('My Feature', () => {
  let queue;
  let worker;

  beforeEach(async () => {
    queue = createTestQueue('my-queue');
    worker = createTestWorker('my-queue', async (job) => {
      return { result: job.data.value * 2 };
    });
  });

  afterEach(async () => {
    await worker.close();
    await queue.close();
  });

  it('should process job', async () => {
    await queue.add('test', { value: 21 });
    await waitForJobs(queue, 'completed', 1);

    const job = await queue.getCompleted();
    expect(job[0].returnvalue).toEqual({ result: 42 });
  });
});

CI/CD Integration

Add to your CI pipeline:

- name: Run E2E Tests
  run: pnpm test:e2e

The tests will:

1. Start Redis container automatically
2. Run all 22 tests
3. Clean up and stop container
4. Exit with code 0 (success) or 1 (failure)

Performance

• Docker startup: ~5-10 seconds
• Test execution: ~30-60 seconds
• Memory usage: ~50MB (Redis container)
• Disk usage: ~0 (tmpfs only)

Next Steps

• Read full documentation
• Explore test helpers
• Review test patterns
• Check core utilities