@quave/agenda 1.0.0

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

@@ -0,0 +1,305 @@
+/**
+ * Shared test suite for JobLogger implementations.
+ *
+ * Tests the JobLogger interface contract: log(), getLogs(), clearLogs()
+ * with filtering, pagination, and sorting. Each backend package runs this
+ * suite with its own logger implementation (MongoJobLogger, PostgresJobLogger,
+ * RedisJobLogger).
+ *
+ * Usage:
+ * ```typescript
+ * import { jobLoggerTestSuite } from 'agenda/testing';
+ *
+ * jobLoggerTestSuite({
+ *   name: 'MongoJobLogger',
+ *   createLogger: async () => new MongoJobLogger({ db }),
+ *   cleanupLogger: async () => { await db.collection('agenda_logs').drop(); }
+ * });
+ * ```
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { JobLogger, JobLogEntry } from '../../src/index.js';
+
+export interface JobLoggerTestConfig {
+	/** Name for the test suite (e.g., 'MongoJobLogger') */
+	name: string;
+	/** Factory to create a fresh logger instance (already connected/initialized) */
+	createLogger: () => Promise<JobLogger>;
+	/** Cleanup between tests — clear all logs */
+	cleanupLogger: (logger: JobLogger) => Promise<void>;
+}
+
+function makeEntry(overrides: Partial<Omit<JobLogEntry, '_id'>> = {}): Omit<JobLogEntry, '_id'> {
+	return {
+		timestamp: new Date(),
+		level: 'info',
+		event: 'start',
+		jobName: 'test-job',
+		message: 'Job started',
+		...overrides
+	};
+}
+
+export function jobLoggerTestSuite(config: JobLoggerTestConfig): void {
+	describe(`JobLogger: ${config.name}`, () => {
+		let logger: JobLogger;
+
+		beforeEach(async () => {
+			logger = await config.createLogger();
+			await config.cleanupLogger(logger);
+		});
+
+		describe('log()', () => {
+			it('should store a log entry', async () => {
+				await logger.log(makeEntry());
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(1);
+				expect(result.entries).toHaveLength(1);
+				expect(result.entries[0].level).toBe('info');
+				expect(result.entries[0].event).toBe('start');
+				expect(result.entries[0].jobName).toBe('test-job');
+				expect(result.entries[0].message).toBe('Job started');
+			});
+
+			it('should store all optional fields', async () => {
+				await logger.log(makeEntry({
+					jobId: 'job-123',
+					duration: 1500,
+					error: 'Something went wrong',
+					failCount: 3,
+					retryDelay: 5000,
+					retryAttempt: 2,
+					agendaName: 'worker-1',
+					meta: { customKey: 'customValue' }
+				}));
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(1);
+				const entry = result.entries[0];
+				expect(entry.jobId).toBe('job-123');
+				expect(entry.duration).toBe(1500);
+				expect(entry.error).toBe('Something went wrong');
+				expect(entry.failCount).toBe(3);
+				expect(entry.retryDelay).toBe(5000);
+				expect(entry.retryAttempt).toBe(2);
+				expect(entry.agendaName).toBe('worker-1');
+				expect(entry.meta).toEqual({ customKey: 'customValue' });
+			});
+
+			it('should store multiple entries', async () => {
+				await logger.log(makeEntry({ event: 'start', message: 'Started' }));
+				await logger.log(makeEntry({ event: 'success', message: 'Succeeded' }));
+				await logger.log(makeEntry({ event: 'complete', message: 'Completed' }));
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(3);
+				expect(result.entries).toHaveLength(3);
+			});
+		});
+
+		describe('getLogs()', () => {
+			beforeEach(async () => {
+				// Seed with a variety of entries
+				const baseTime = new Date('2025-06-01T12:00:00Z');
+				await logger.log(makeEntry({
+					timestamp: new Date(baseTime.getTime()),
+					event: 'start',
+					level: 'info',
+					jobName: 'job-a',
+					jobId: 'id-1',
+					message: 'Job A started'
+				}));
+				await logger.log(makeEntry({
+					timestamp: new Date(baseTime.getTime() + 1000),
+					event: 'success',
+					level: 'info',
+					jobName: 'job-a',
+					jobId: 'id-1',
+					message: 'Job A succeeded',
+					duration: 1000
+				}));
+				await logger.log(makeEntry({
+					timestamp: new Date(baseTime.getTime() + 2000),
+					event: 'start',
+					level: 'info',
+					jobName: 'job-b',
+					jobId: 'id-2',
+					message: 'Job B started'
+				}));
+				await logger.log(makeEntry({
+					timestamp: new Date(baseTime.getTime() + 3000),
+					event: 'fail',
+					level: 'error',
+					jobName: 'job-b',
+					jobId: 'id-2',
+					message: 'Job B failed',
+					error: 'timeout'
+				}));
+				await logger.log(makeEntry({
+					timestamp: new Date(baseTime.getTime() + 4000),
+					event: 'retry',
+					level: 'warn',
+					jobName: 'job-b',
+					jobId: 'id-2',
+					message: 'Job B retrying',
+					retryAttempt: 1,
+					retryDelay: 5000
+				}));
+			});
+
+			it('should return all entries when no filter is provided', async () => {
+				const result = await logger.getLogs();
+				expect(result.total).toBe(5);
+				expect(result.entries).toHaveLength(5);
+			});
+
+			it('should filter by jobName', async () => {
+				const result = await logger.getLogs({ jobName: 'job-a' });
+				expect(result.total).toBe(2);
+				for (const entry of result.entries) {
+					expect(entry.jobName).toBe('job-a');
+				}
+			});
+
+			it('should filter by jobId', async () => {
+				const result = await logger.getLogs({ jobId: 'id-2' });
+				expect(result.total).toBe(3);
+				for (const entry of result.entries) {
+					expect(entry.jobId).toBe('id-2');
+				}
+			});
+
+			it('should filter by single level', async () => {
+				const result = await logger.getLogs({ level: 'error' });
+				expect(result.total).toBe(1);
+				expect(result.entries[0].event).toBe('fail');
+			});
+
+			it('should filter by level array', async () => {
+				const result = await logger.getLogs({ level: ['error', 'warn'] });
+				expect(result.total).toBe(2);
+				for (const entry of result.entries) {
+					expect(['error', 'warn']).toContain(entry.level);
+				}
+			});
+
+			it('should filter by single event', async () => {
+				const result = await logger.getLogs({ event: 'start' });
+				expect(result.total).toBe(2);
+				for (const entry of result.entries) {
+					expect(entry.event).toBe('start');
+				}
+			});
+
+			it('should filter by event array', async () => {
+				const result = await logger.getLogs({ event: ['fail', 'retry'] });
+				expect(result.total).toBe(2);
+				for (const entry of result.entries) {
+					expect(['fail', 'retry']).toContain(entry.event);
+				}
+			});
+
+			it('should filter by date range (from)', async () => {
+				const from = new Date('2025-06-01T12:00:03Z');
+				const result = await logger.getLogs({ from });
+				expect(result.total).toBe(2); // fail + retry
+				for (const entry of result.entries) {
+					expect(entry.timestamp.getTime()).toBeGreaterThanOrEqual(from.getTime());
+				}
+			});
+
+			it('should filter by date range (to)', async () => {
+				const to = new Date('2025-06-01T12:00:01Z');
+				const result = await logger.getLogs({ to });
+				expect(result.total).toBe(2); // start + success
+				for (const entry of result.entries) {
+					expect(entry.timestamp.getTime()).toBeLessThanOrEqual(to.getTime());
+				}
+			});
+
+			it('should filter by date range (from + to)', async () => {
+				const from = new Date('2025-06-01T12:00:01Z');
+				const to = new Date('2025-06-01T12:00:03Z');
+				const result = await logger.getLogs({ from, to });
+				expect(result.total).toBe(3); // success, start, fail
+				for (const entry of result.entries) {
+					expect(entry.timestamp.getTime()).toBeGreaterThanOrEqual(from.getTime());
+					expect(entry.timestamp.getTime()).toBeLessThanOrEqual(to.getTime());
+				}
+			});
+
+			it('should support limit', async () => {
+				const result = await logger.getLogs({ limit: 2 });
+				expect(result.entries).toHaveLength(2);
+				expect(result.total).toBe(5); // total should reflect all matching, not limited
+			});
+
+			it('should support offset for pagination', async () => {
+				const page1 = await logger.getLogs({ limit: 2, offset: 0, sort: 'asc' });
+				const page2 = await logger.getLogs({ limit: 2, offset: 2, sort: 'asc' });
+
+				expect(page1.entries).toHaveLength(2);
+				expect(page2.entries).toHaveLength(2);
+				// Different entries
+				expect(page1.entries[0].message).not.toBe(page2.entries[0].message);
+			});
+
+			it('should sort descending by default', async () => {
+				const result = await logger.getLogs();
+				for (let i = 1; i < result.entries.length; i++) {
+					expect(result.entries[i - 1].timestamp.getTime())
+						.toBeGreaterThanOrEqual(result.entries[i].timestamp.getTime());
+				}
+			});
+
+			it('should sort ascending when requested', async () => {
+				const result = await logger.getLogs({ sort: 'asc' });
+				for (let i = 1; i < result.entries.length; i++) {
+					expect(result.entries[i - 1].timestamp.getTime())
+						.toBeLessThanOrEqual(result.entries[i].timestamp.getTime());
+				}
+			});
+
+			it('should return empty result when no entries match', async () => {
+				const result = await logger.getLogs({ jobName: 'nonexistent' });
+				expect(result.total).toBe(0);
+				expect(result.entries).toHaveLength(0);
+			});
+		});
+
+		describe('clearLogs()', () => {
+			beforeEach(async () => {
+				await logger.log(makeEntry({ jobName: 'job-a', event: 'start', level: 'info' }));
+				await logger.log(makeEntry({ jobName: 'job-a', event: 'success', level: 'info' }));
+				await logger.log(makeEntry({ jobName: 'job-b', event: 'fail', level: 'error' }));
+			});
+
+			it('should clear all logs when no filter is provided', async () => {
+				const deleted = await logger.clearLogs();
+				expect(deleted).toBe(3);
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(0);
+			});
+
+			it('should clear logs filtered by jobName', async () => {
+				const deleted = await logger.clearLogs({ jobName: 'job-a' });
+				expect(deleted).toBe(2);
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(1);
+				expect(result.entries[0].jobName).toBe('job-b');
+			});
+
+			it('should return 0 when no logs match the filter', async () => {
+				const deleted = await logger.clearLogs({ jobName: 'nonexistent' });
+				expect(deleted).toBe(0);
+
+				const result = await logger.getLogs();
+				expect(result.total).toBe(3);
+			});
+		});
+	});
+}

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

@@ -0,0 +1,266 @@
+/**
+ * JobProcessor test factory
+ *
+ * This file exports a test factory for JobProcessor-specific tests.
+ *
+ * Usage:
+ * ```typescript
+ * import { jobProcessorTestSuite } from 'agenda/test/jobprocessor.test';
+ *
+ * jobProcessorTestSuite({
+ *   name: 'JobProcessor 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';
+import { delay } from './test-utils.js';
+
+export interface JobProcessorTestConfig {
+	/** 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>;
+}
+
+/**
+ * JobProcessor tests
+ */
+export function jobProcessorTestSuite(config: JobProcessorTestConfig): void {
+	describe(`${config.name} - JobProcessor`, () => {
+		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,
+				maxConcurrency: 4,
+				defaultConcurrency: 1,
+				lockLimit: 15,
+				defaultLockLimit: 6,
+				processEvery: 100,
+				name: 'agendaTest'
+			});
+			await agenda.ready;
+		});
+
+		afterEach(async () => {
+			if (agenda) {
+				await agenda.stop();
+			}
+			await config.clearJobs(backend);
+		});
+
+		describe('getRunningStats', () => {
+			it('throws an error when agenda is not running', async () => {
+				await expect(agenda.getRunningStats()).rejects.toThrow('agenda not running!');
+			});
+
+			it('contains the agendaVersion', async () => {
+				await agenda.start();
+
+				const status = await agenda.getRunningStats();
+				expect(status).toHaveProperty('version');
+				expect(status.version).toMatch(/\d+\.\d+\.\d+/);
+			});
+
+			it('shows the correct job status', async () => {
+				agenda.define('test', async () => {
+					await delay(30000);
+				});
+
+				agenda.now('test');
+				await agenda.start();
+
+				await new Promise(resolve => {
+					agenda.on('start:test', resolve);
+				});
+
+				const status = await agenda.getRunningStats();
+				expect(status).toHaveProperty('jobStatus');
+				if (status.jobStatus) {
+					expect(status.jobStatus).toHaveProperty('test');
+					expect(status.jobStatus.test.locked).toBe(1);
+					expect(status.jobStatus.test.running).toBe(1);
+					expect(status.jobStatus.test.config.fn).toBeTypeOf('function');
+					expect(status.jobStatus.test.config.concurrency).toBe(1);
+					expect(status.jobStatus.test.config.lockLifetime).toBe(600000);
+					expect(status.jobStatus.test.config.priority).toBe(0);
+					expect(status.jobStatus.test.config.lockLimit).toBe(6);
+				}
+			});
+
+			it('shows queueName', async () => {
+				await agenda.start();
+
+				const status = await agenda.getRunningStats();
+				expect(status).toHaveProperty('queueName');
+				expect(status.queueName).toBeTypeOf('string');
+				expect(status.queueName).toBe('agendaTest');
+			});
+
+			it('shows totalQueueSizeDB', async () => {
+				await agenda.start();
+
+				const status = await agenda.getRunningStats();
+				expect(status).toHaveProperty('totalQueueSizeDB');
+				expect(status.totalQueueSizeDB).toBeTypeOf('number');
+				expect(status.totalQueueSizeDB).toBe(0);
+			});
+		});
+
+		it('ensure new jobs are always filling up running queue', async () => {
+			let shortOneFinished = false;
+
+			agenda.define('test long', async () => {
+				await delay(1000);
+			});
+			agenda.define('test short', async () => {
+				shortOneFinished = true;
+				await delay(5);
+			});
+
+			await agenda.start();
+
+			// queue up long ones
+			for (let i = 0; i < 100; i += 1) {
+				agenda.now('test long');
+			}
+
+			await delay(1500);
+
+			// queue more short ones (they will be picked up on next process interval)
+			for (let j = 0; j < 100; j += 1) {
+				agenda.now('test short');
+			}
+
+			// Wait for the next process interval to pick up and run the short jobs
+			await delay(2000);
+
+			expect(shortOneFinished).toBe(true);
+		});
+
+		it('ensure slow jobs time out', async () => {
+			let jobStarted = false;
+			agenda.define(
+				'test long',
+				async () => {
+					jobStarted = true;
+					await delay(2500);
+				},
+				{ lockLifetime: 500 }
+			);
+
+			agenda.now('test long');
+
+			await agenda.start();
+
+			const promiseResult = await new Promise<Error | void>(resolve => {
+				agenda.on('error', err => {
+					resolve(err);
+				});
+
+				agenda.on('success', () => {
+					resolve();
+				});
+			});
+
+			expect(jobStarted).toBe(true);
+			expect(promiseResult).toBeInstanceOf(Error);
+		});
+
+		it('ensure slow jobs do not time out when calling touch', async () => {
+			agenda.define(
+				'test long',
+				async job => {
+					for (let i = 0; i < 10; i += 1) {
+						await delay(100);
+						await job.touch();
+					}
+				},
+				{ lockLifetime: 500 }
+			);
+
+			await agenda.start();
+
+			agenda.now('test long');
+
+			const promiseResult = await new Promise<Error | void>(resolve => {
+				agenda.on('error', err => {
+					resolve(err);
+				});
+
+				agenda.on('success', () => {
+					resolve();
+				});
+			});
+
+			expect(promiseResult).toBeUndefined();
+		});
+
+		it('ensure concurrency is filled up', async () => {
+			agenda.maxConcurrency(300);
+			agenda.lockLimit(150);
+			agenda.defaultLockLimit(20);
+			agenda.defaultConcurrency(10);
+
+			for (let jobI = 0; jobI < 10; jobI += 1) {
+				agenda.define(
+					`test job ${jobI}`,
+					async () => {
+						await delay(5000);
+					},
+					{ lockLifetime: 10000 }
+				);
+			}
+
+			for (let jobI = 0; jobI < 10; jobI += 1) {
+				for (let jobJ = 0; jobJ < 25; jobJ += 1) {
+					agenda.now(`test job ${jobI}`);
+				}
+			}
+
+			await agenda.start();
+
+			let runningJobs = 0;
+			const allJobsStarted = (async () => {
+				do {
+					runningJobs = (await agenda.getRunningStats()).runningJobs as number;
+					await delay(50);
+				} while (runningJobs < 90);
+				return 'all started';
+			})();
+
+			const result = await Promise.race([
+				allJobsStarted,
+				new Promise(resolve => {
+					setTimeout(
+						() => resolve(`not all jobs started, currently running: ${runningJobs}`),
+						2500
+					);
+				})
+			]);
+
+			expect(result).toBe('all started');
+		});
+	});
+}
+