@quave/agenda 1.0.0

package/test/shared/retry-test-suite.ts

@@ -0,0 +1,174 @@
+/**
+ * Retry test factory
+ *
+ * This file exports a test factory for job retry tests.
+ *
+ * Usage:
+ * ```typescript
+ * import { retryTestSuite } from 'agenda/test/retry.test';
+ *
+ * retryTestSuite({
+ *   name: 'Retry with MongoDB',
+ *   createBackend: async () => new MongoBackend({ mongo: db }),
+ *   cleanupBackend: async (backend) => await backend.disconnect(),
+ *   clearJobs: async (backend) => await db.collection('agendaJobs').deleteMany({})
+ * });
+ * ```
+ */
+
+import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
+import type { AgendaBackend } from '../../src/index.js';
+import { Agenda } from '../../src/index.js';
+
+export interface RetryTestConfig {
+	/** Name for the test suite */
+	name: string;
+	/** Factory to create a fresh backend instance */
+	createBackend: () => Promise<AgendaBackend>;
+	/** Cleanup function called after tests */
+	cleanupBackend: (backend: AgendaBackend) => Promise<void>;
+	/** Clear all jobs between tests */
+	clearJobs: (backend: AgendaBackend) => Promise<void>;
+}
+
+/**
+ * Retry tests
+ */
+export function retryTestSuite(config: RetryTestConfig): void {
+	describe(`${config.name} - Retry`, () => {
+		let backend: AgendaBackend;
+		let agenda: Agenda;
+
+		beforeAll(async () => {
+			backend = await config.createBackend();
+		});
+
+		afterAll(async () => {
+			await config.cleanupBackend(backend);
+		});
+
+		beforeEach(async () => {
+			await config.clearJobs(backend);
+			agenda = new Agenda({
+				backend,
+				processEvery: 100
+			});
+			await agenda.ready;
+		});
+
+		afterEach(async () => {
+			if (agenda) {
+				await agenda.stop();
+			}
+			await config.clearJobs(backend);
+		});
+
+		it('should retry a job - via attrs.nextRunAt', async () => {
+			let shouldFail = true;
+
+			agenda.define('a job', (_job, done) => {
+				if (shouldFail) {
+					shouldFail = false;
+					return done(new Error('test failure'));
+				}
+
+				done();
+				return undefined;
+			});
+
+			agenda.on('fail:a job', (_err, job) => {
+				// Do nothing as this is expected to fail.
+				job.attrs.nextRunAt = new Date();
+			});
+
+			const successPromise = new Promise(resolve => {
+				agenda.on('success:a job', resolve);
+			});
+
+			await agenda.now('a job');
+
+			await agenda.start();
+			await successPromise;
+		});
+
+		it('should retry a job - via schedule()', async () => {
+			let shouldFail = true;
+
+			agenda.define('a job', (_job, done) => {
+				if (shouldFail) {
+					shouldFail = false;
+					return done(new Error('test failure'));
+				}
+
+				done();
+				return undefined;
+			});
+
+			agenda.on('fail:a job', (_err, job) => {
+				// Do nothing as this is expected to fail.
+				job.schedule('now').save();
+			});
+
+			const successPromise = new Promise(resolve => {
+				agenda.on('success:a job', resolve);
+			});
+
+			await agenda.now('a job');
+
+			await agenda.start();
+			await successPromise;
+		});
+
+		it('should track failCount on retry - via attrs.nextRunAt', async () => {
+			let attempts = 0;
+
+			agenda.define('failing-job', async () => {
+				attempts++;
+				if (attempts < 3) {
+					throw new Error(`Attempt ${attempts} failed`);
+				}
+			});
+
+			agenda.on('fail:failing-job', (_err, job) => {
+				// Retry immediately
+				job.attrs.nextRunAt = new Date();
+			});
+
+			const successPromise = new Promise(resolve => {
+				agenda.on('success:failing-job', resolve);
+			});
+
+			await agenda.now('failing-job');
+			await agenda.start();
+			await successPromise;
+			expect(attempts).toBe(3);
+		});
+
+		it('should track failCount on retry - via schedule()', async () => {
+			let attempts = 0;
+
+			agenda.define('failing-job', async () => {
+				attempts++;
+				if (attempts < 3) {
+					throw new Error(`Attempt ${attempts} failed`);
+				}
+			});
+
+			agenda.on('fail:failing-job', (_err, job) => {
+				// Retry immediately
+				job.schedule('now').save();
+			});
+
+			const successPromise = new Promise(resolve => {
+				agenda.on('success:failing-job', resolve);
+			});
+
+			await agenda.now('failing-job');
+			await agenda.start();
+			await successPromise;
+
+			expect(attempts).toBe(3);
+		});
+	});
+}
+

package/test/shared/test-utils.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared test utilities for Agenda test suites
+ */
+
+import type { Agenda, AgendaEventName } from '../../src/index.js';
+
+/**
+ * Promise-based delay utility
+ */
+export const delay = (ms: number): Promise<void> =>
+	new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Poll a predicate until it returns true or the timeout elapses.
+ * Resolves true as soon as the predicate holds, false on timeout.
+ */
+export async function waitFor(
+	predicate: () => boolean | Promise<boolean>,
+	timeoutMs: number = 5000,
+	intervalMs: number = 25
+): Promise<boolean> {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (await predicate()) {
+			return true;
+		}
+		if (Date.now() >= deadline) {
+			return false;
+		}
+		await delay(intervalMs);
+	}
+}
+
+/**
+ * Wait for a single event with timeout
+ */
+export function waitForEvent(
+	agenda: Agenda,
+	eventName: AgendaEventName,
+	timeoutMs: number = 5000
+): Promise<unknown> {
+	return new Promise((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			reject(new Error(`Timeout waiting for event: ${eventName}`));
+		}, timeoutMs);
+
+		agenda.once(eventName, (...args: unknown[]) => {
+			clearTimeout(timeout);
+			resolve(args[0]);
+		});
+	});
+}
+
+/**
+ * Schedule a job with agenda.now() and wait for an event (race-condition safe).
+ * Sets up the event listener BEFORE scheduling the job to avoid missing fast events.
+ */
+export async function runJobAndWait(
+	agenda: Agenda,
+	jobName: string,
+	eventName: AgendaEventName,
+	data?: Record<string, unknown>,
+	timeoutMs: number = 5000
+): Promise<void> {
+	const eventPromise = waitForEvent(agenda, eventName, timeoutMs);
+	await agenda.now(jobName, data);
+
+	await eventPromise;
+	await new Promise(resolve => process.nextTick(resolve));
+}
+
+/**
+ * Wait for multiple occurrences of an event with timeout
+ */
+export function waitForEvents(
+	agenda: Agenda,
+	eventName: AgendaEventName,
+	count: number,
+	timeoutMs: number = 10000
+): Promise<unknown[]> {
+	return new Promise((resolve, reject) => {
+		const results: unknown[] = [];
+		const timeout = setTimeout(() => {
+			reject(new Error(`Timeout waiting for ${count} ${eventName} events, got ${results.length}`));
+		}, timeoutMs);
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const handler = (...args: any[]) => {
+			results.push(args[0]);
+			if (results.length >= count) {
+				clearTimeout(timeout);
+				agenda.off(eventName, handler);
+				resolve(results);
+			}
+		};
+
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		agenda.on(eventName as any, handler);
+	});
+}