@vida-global/core 1.4.6 → 2.0.1

package/test/jobQueue/abstractJobComponent.test.js

@@ -0,0 +1,110 @@
+const { AbstractJobComponent } = require('../../lib/jobQueue/abstractJobComponent');
+const   TestHelpers            = require('@vida-global/test-helpers');
+const { snapshotEnv }          = require('../helpers/env');
+
+
+let restoreEnv;
+
+beforeEach(() => {
+    restoreEnv = snapshotEnv([
+        'NODE_ENV',
+        'REDIS_BULL_HOST',
+        'REDIS_BULL_PORT',
+        'REDIS_BULL_PASSWORD',
+    ]);
+});
+
+
+afterEach(() => {
+    restoreEnv();
+});
+
+
+describe('AbstractJobComponent', () => {
+    describe('.fullQueueName', () => {
+        it ('builds a name suffixed with the current NODE_ENV', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env       = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            expect(AbstractJobComponent.fullQueueName(queueName)).toEqual(`${queueName}-${env}`);
+        });
+
+        it ('reflects changes to NODE_ENV between calls', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env1      = TestHelpers.Faker.Text.randomString();
+            const env2      = TestHelpers.Faker.Text.randomString();
+
+            process.env.NODE_ENV = env1;
+            const first  = AbstractJobComponent.fullQueueName(queueName);
+            process.env.NODE_ENV = env2;
+            const second = AbstractJobComponent.fullQueueName(queueName);
+
+            expect(first).toEqual(`${queueName}-${env1}`);
+            expect(second).toEqual(`${queueName}-${env2}`);
+        });
+    });
+
+
+    describe('.env', () => {
+        it ('returns the current NODE_ENV', () => {
+            const env = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            expect(AbstractJobComponent.env).toEqual(env);
+        });
+
+        it ('returns undefined when NODE_ENV is not set', () => {
+            delete process.env.NODE_ENV;
+
+            expect(AbstractJobComponent.env).toBeUndefined();
+        });
+    });
+
+
+    describe('#fullQueueName', () => {
+        it ('delegates to the static method using `this.queueName`', () => {
+            const queueName = TestHelpers.Faker.Text.randomString();
+            const env       = TestHelpers.Faker.Text.randomString();
+            process.env.NODE_ENV = env;
+
+            class Concrete extends AbstractJobComponent {
+                get queueName() { return queueName; }
+            }
+            const instance = new Concrete();
+
+            expect(instance.fullQueueName).toEqual(`${queueName}-${env}`);
+        });
+    });
+
+
+    describe('#redisConnectionDetails', () => {
+        it ('returns the connection details from REDIS_BULL_* environment variables', () => {
+            const host     = TestHelpers.Faker.Text.randomString();
+            const port     = String(TestHelpers.Faker.Math.randomNumber(65000));
+            const password = TestHelpers.Faker.Text.randomString();
+            process.env.REDIS_BULL_HOST     = host;
+            process.env.REDIS_BULL_PORT     = port;
+            process.env.REDIS_BULL_PASSWORD = password;
+
+            const instance = new AbstractJobComponent();
+
+            expect(instance.redisConnectionDetails).toEqual({ host, password, port });
+        });
+    });
+
+
+    describe('individual redis env getters', () => {
+        it.each([
+            ['host',     'REDIS_BULL_HOST'],
+            ['port',     'REDIS_BULL_PORT'],
+            ['password', 'REDIS_BULL_PASSWORD'],
+        ])('#%s returns process.env.%s', (getter, envVar) => {
+            const value           = TestHelpers.Faker.Text.randomString();
+            process.env[envVar]   = value;
+            const instance        = new AbstractJobComponent();
+
+            expect(instance[getter]).toEqual(value);
+        });
+    });
+});

package/test/jobQueue/helpers/abstractJob.js

@@ -0,0 +1,26 @@
+const TestHelpers = require('@vida-global/test-helpers');
+
+
+/***************************************************************************************************
+* SUBCLASS FACTORY
+***************************************************************************************************/
+function defineJobSubclass(AbstractJob, { queueName, queueNameFn, run, ...overrides } = {}) {
+    const resolvedName = queueName || TestHelpers.Faker.Text.randomString();
+    const nameFunction = queueNameFn || (() => resolvedName);
+    const Subclass = class extends AbstractJob {
+        static queueName(...jobArgs) { return nameFunction(...jobArgs); }
+        async run(...args) {
+            if (run) return await run(...args);
+        }
+    };
+    for (const [key, value] of Object.entries(overrides)) {
+        Object.defineProperty(Subclass, key, { value });
+    }
+    Subclass.expectedQueueName = resolvedName;
+    return Subclass;
+}
+
+
+module.exports = {
+    defineJobSubclass,
+}

package/test/jobQueue/helpers/apmMock.js

@@ -0,0 +1,20 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function buildApmMock() {
+    return {
+        addCustomAttribute:         jest.fn(),
+        recordCustomEvent:          jest.fn(),
+        recordMetric:               jest.fn(),
+        reportError:                jest.fn(),
+        setControllerName:          jest.fn(),
+        setUserId:                  jest.fn(),
+        startBackgroundTransaction: jest.fn((name, group, handler) => handler()),
+        startSegment:               jest.fn((name, record, handler) => handler()),
+    };
+}
+
+
+module.exports = {
+    buildApmMock,
+}

package/test/jobQueue/helpers/bullmqMock.js

@@ -0,0 +1,67 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+const instances = {
+    queues:  [],
+    workers: [],
+};
+
+
+class MockBullQueue {
+    constructor(name, options) {
+        this.name    = name;
+        this.options = options;
+
+        this.add            = jest.fn();
+        this.close          = jest.fn();
+        this.pause          = jest.fn();
+        this.resume         = jest.fn();
+        this.count          = jest.fn();
+        this.getJobs        = jest.fn();
+        this.getActiveCount = jest.fn();
+        this.getActive      = jest.fn();
+        this.getFailedCount = jest.fn();
+        this.getFailed      = jest.fn();
+        this.clean          = jest.fn();
+        this.drain          = jest.fn();
+        this.getWorkers     = jest.fn();
+        this.on             = jest.fn();
+
+        instances.queues.push(this);
+    }
+}
+
+
+class MockBullWorker {
+    constructor(name, processor, options) {
+        this.name      = name;
+        this.processor = processor;
+        this.options   = options;
+
+        this.run = jest.fn();
+        this.on  = jest.fn();
+
+        instances.workers.push(this);
+    }
+}
+
+
+function reset() {
+    instances.queues.length  = 0;
+    instances.workers.length = 0;
+}
+
+
+function listenerFor(emitter, event) {
+    const call = emitter.on.mock.calls.find(([name]) => name === event);
+    return call ? call[1] : undefined;
+}
+
+
+module.exports = {
+    Queue:  MockBullQueue,
+    Worker: MockBullWorker,
+    instances,
+    reset,
+    listenerFor,
+}

package/test/jobQueue/helpers/env.js

@@ -0,0 +1,29 @@
+const TestHelpers     = require('@vida-global/test-helpers');
+const { snapshotEnv } = require('../../helpers/env');
+
+
+/***************************************************************************************************
+* ENV SETUP
+***************************************************************************************************/
+function setupJobQueueEnv(extraKeysToClear = []) {
+    const restore = snapshotEnv([
+        'NODE_ENV',
+        'REDIS_BULL_HOST',
+        'REDIS_BULL_PORT',
+        'REDIS_BULL_PASSWORD',
+        ...extraKeysToClear,
+    ]);
+    process.env.NODE_ENV            = 'test';
+    process.env.REDIS_BULL_HOST     = TestHelpers.Faker.Text.randomString();
+    process.env.REDIS_BULL_PORT     = String(TestHelpers.Faker.Math.randomNumber(65000));
+    process.env.REDIS_BULL_PASSWORD = TestHelpers.Faker.Text.randomString();
+    for (const key of extraKeysToClear) {
+        delete process.env[key];
+    }
+    return restore;
+}
+
+
+module.exports = {
+    setupJobQueueEnv,
+}

package/test/jobQueue/helpers/fixtureJobs/notAJob.js

@@ -0,0 +1,8 @@
+class NotAJob {
+    run() {}
+}
+
+
+module.exports = {
+    NotAJob,
+}

package/test/jobQueue/helpers/fixtureJobs/testJobA.js

@@ -0,0 +1,14 @@
+const { AbstractJob } = require('../../../../lib/jobQueue/abstractJob');
+
+
+class TestJobA extends AbstractJob {
+    static queueName() { return 'fixture-queue-a'; }
+
+    async run() {
+    }
+}
+
+
+module.exports = {
+    TestJobA,
+}

package/test/jobQueue/helpers/fixtureJobs/testJobB.js

@@ -0,0 +1,14 @@
+const { AbstractJob } = require('../../../../lib/jobQueue/abstractJob');
+
+
+class TestJobB extends AbstractJob {
+    static queueName() { return 'fixture-queue-b'; }
+
+    async run() {
+    }
+}
+
+
+module.exports = {
+    TestJobB,
+}

package/test/jobQueue/helpers/loggerMock.js

@@ -0,0 +1,43 @@
+/***************************************************************************************************
+* MOCKS
+***************************************************************************************************/
+function createLeaf(name) {
+    const leaf = {
+        name,
+        debug:   jest.fn(),
+        info:    jest.fn(),
+        error:   jest.fn(),
+        warn:    jest.fn(),
+        verbose: jest.fn(),
+        silly:   jest.fn(),
+    };
+
+    const children = {};
+    leaf.child = jest.fn((id) => {
+        if (!children[id]) children[id] = createLeaf(`${name}:${id}`);
+        return children[id];
+    });
+
+    return leaf;
+}
+
+
+function buildLoggerMock() {
+    const scopes = {};
+    const root   = createLeaf('root');
+    root.addScope = jest.fn();
+
+    return new Proxy(root, {
+        get(target, prop) {
+            if (typeof prop !== 'string')      return target[prop];
+            if (Object.hasOwn(target, prop))   return target[prop];
+            if (!scopes[prop])                 scopes[prop] = createLeaf(prop);
+            return scopes[prop];
+        }
+    });
+}
+
+
+module.exports = {
+    buildLoggerMock,
+}

package/test/jobQueue/helpers/worker.js

@@ -0,0 +1,38 @@
+const TestHelpers = require('@vida-global/test-helpers');
+const path        = require('path');
+
+
+const FIXTURE_JOBS_DIR = path.join(__dirname, 'fixtureJobs');
+
+
+/***************************************************************************************************
+* WORKER FACTORY
+***************************************************************************************************/
+function buildWorker(Worker, queueName) {
+    class TestWorker extends Worker {
+        get jobDirectories() { return [FIXTURE_JOBS_DIR]; }
+    }
+    return new TestWorker(queueName || TestHelpers.Faker.Text.randomString());
+}
+
+
+/***************************************************************************************************
+* BULL JOB BUILDER
+***************************************************************************************************/
+function buildFakeBullJob(overrides = {}) {
+    return {
+        name:           'TestJobA',
+        data:           { id: TestHelpers.Faker.Text.randomString(), args: [] },
+        updateProgress: jest.fn(),
+        attemptsMade:   0,
+        opts:           { attempts: 3 },
+        ...overrides,
+    };
+}
+
+
+module.exports = {
+    FIXTURE_JOBS_DIR,
+    buildFakeBullJob,
+    buildWorker,
+}

package/test/jobQueue/queue.test.js

@@ -0,0 +1,320 @@
+const TestHelpers           = require('@vida-global/test-helpers');
+const { setupJobQueueEnv } = require('./helpers/env');
+
+
+jest.mock('bullmq', () => {
+    const mock = require('./helpers/bullmqMock');
+    return { Queue: mock.Queue, Worker: mock.Worker };
+});
+
+jest.mock('../../lib/logger', () => {
+    const { buildLoggerMock } = require('./helpers/loggerMock');
+    return { logger: buildLoggerMock() };
+});
+
+jest.mock('crypto', () => {
+    const actual = jest.requireActual('crypto');
+    return { ...actual, randomUUID: jest.fn() };
+});
+
+
+let bullmqMock;
+let getQueue;
+let logger;
+let randomUUID;
+let restoreEnv;
+
+beforeEach(() => {
+    jest.resetModules();
+    restoreEnv = setupJobQueueEnv();
+
+    bullmqMock      = require('./helpers/bullmqMock');
+    ({ getQueue }   = require('../../lib/jobQueue/queue'));
+    ({ logger }     = require('../../lib/logger'));
+    ({ randomUUID } = require('crypto'));
+});
+
+
+afterEach(() => {
+    restoreEnv();
+    jest.clearAllMocks();
+});
+
+
+function expectedConnection() {
+    return {
+        host:     process.env.REDIS_BULL_HOST,
+        password: process.env.REDIS_BULL_PASSWORD,
+        port:     process.env.REDIS_BULL_PORT,
+    };
+}
+
+
+describe('getQueue', () => {
+    it ('returns a Queue with the given queueName', () => {
+        const name = TestHelpers.Faker.Text.randomString();
+
+        const queue = getQueue(name);
+
+        expect(queue.queueName).toEqual(name);
+    });
+
+    it ('memoizes by full queue name', () => {
+        const name = TestHelpers.Faker.Text.randomString();
+
+        const first  = getQueue(name);
+        const second = getQueue(name);
+
+        expect(second).toBe(first);
+    });
+
+    it ('returns different instances for different names', () => {
+        const queueA = getQueue(TestHelpers.Faker.Text.randomString());
+        const queueB = getQueue(TestHelpers.Faker.Text.randomString());
+
+        expect(queueB).not.toBe(queueA);
+    });
+
+    it ('treats the same raw name under different NODE_ENVs as different queues', () => {
+        const name = TestHelpers.Faker.Text.randomString();
+
+        process.env.NODE_ENV = 'test';
+        const inTest = getQueue(name);
+
+        process.env.NODE_ENV = 'staging';
+        const inStaging = getQueue(name);
+
+        expect(inStaging).not.toBe(inTest);
+    });
+});
+
+
+describe('Queue', () => {
+    let queueName;
+    let queue;
+
+    beforeEach(() => {
+        queueName = TestHelpers.Faker.Text.randomString();
+        queue     = getQueue(queueName);
+    });
+
+
+    describe('#queueName', () => {
+        it ('returns the raw queue name', () => {
+            expect(queue.queueName).toEqual(queueName);
+        });
+    });
+
+
+    describe('#fullQueueName', () => {
+        it ('appends the current NODE_ENV', () => {
+            expect(queue.fullQueueName).toEqual(`${queueName}-test`);
+        });
+    });
+
+
+    describe('#logger', () => {
+        it ('uses the queue scope keyed by fullQueueName', () => {
+            const child = queue.logger;
+
+            expect(logger.queue.child).toHaveBeenCalledWith(`${queueName}-test`);
+            expect(child).toBe(logger.queue.child.mock.results[0].value);
+        });
+    });
+
+
+    describe('lazy BullMQ.Queue construction', () => {
+        it ('does not construct the BullMQ queue until a method needs it', () => {
+            expect(bullmqMock.instances.queues).toHaveLength(0);
+        });
+
+        it ('constructs the BullMQ queue with fullQueueName and connection options on first use', async () => {
+            await queue.numQueuedJobs();
+
+            expect(bullmqMock.instances.queues).toHaveLength(1);
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.name).toEqual(`${queueName}-test`);
+            expect(instance.options).toEqual({ connection: expectedConnection() });
+        });
+
+        it ('reuses the same BullMQ queue across multiple method calls', async () => {
+            await queue.numQueuedJobs();
+            await queue.numActiveJobs();
+            await queue.close();
+
+            expect(bullmqMock.instances.queues).toHaveLength(1);
+        });
+
+        it ('registers an error handler on the BullMQ queue', async () => {
+            await queue.numQueuedJobs();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.on).toHaveBeenCalledWith('error', expect.any(Function));
+        });
+    });
+
+
+    describe('#queueJob', () => {
+        it ('adds the job to the BullMQ queue with a generated UUID, args, and settings', async () => {
+            const id       = TestHelpers.Faker.Text.randomString();
+            randomUUID.mockReturnValue(id);
+            const args     = [TestHelpers.Faker.Text.randomString(), TestHelpers.Faker.Math.randomNumber()];
+            const settings = { attempts: TestHelpers.Faker.Math.randomNumber(10) };
+            const jobClass = { name: TestHelpers.Faker.Text.randomString() };
+
+            await queue.queueJob(jobClass, args, settings);
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.add).toHaveBeenCalledTimes(1);
+            expect(instance.add).toHaveBeenCalledWith(jobClass.name, { id, args }, settings);
+        });
+    });
+
+
+    describe.each([
+        ['close',  'close',  []],
+        ['pause',  'pause',  []],
+        ['resume', 'resume', []],
+    ])('#%s', (method, bullMethod, expectedArgs) => {
+        it (`calls bullmq queue.${bullMethod}`, async () => {
+            await queue[method]();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance[bullMethod]).toHaveBeenCalledWith(...expectedArgs);
+        });
+    });
+
+
+    describe('count-style queries', () => {
+        it.each([
+            ['numQueuedJobs', 'count'],
+            ['numActiveJobs', 'getActiveCount'],
+            ['numFailedJobs', 'getFailedCount'],
+        ])('#%s delegates to bullmq queue.%s and returns its value', async (method, bullMethod) => {
+            const expectedCount = TestHelpers.Faker.Math.randomNumber();
+            const queueInstance = (() => { queue[method](); return bullmqMock.instances.queues[0]; })();
+            queueInstance[bullMethod].mockResolvedValue(expectedCount);
+
+            const result = await queue[method]();
+
+            expect(result).toEqual(expectedCount);
+        });
+    });
+
+
+    describe('#numWorkers', () => {
+        it ('returns the length of bullmq queue.getWorkers()', async () => {
+            await queue.numQueuedJobs();
+            const instance = bullmqMock.instances.queues[0];
+            const workers  = Array.from({ length: TestHelpers.Faker.Math.randomNumber(10) }, () => ({}));
+            instance.getWorkers.mockResolvedValue(workers);
+
+            await expect(queue.numWorkers()).resolves.toEqual(workers.length);
+        });
+    });
+
+
+    describe('clear methods', () => {
+        it ('#clearFailedJobs calls bullmq clean(0, null, "failed")', async () => {
+            await queue.clearFailedJobs();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.clean).toHaveBeenCalledWith(0, null, 'failed');
+        });
+
+        it ('#clearCompletedJobs calls bullmq clean(0, null, "completed")', async () => {
+            await queue.clearCompletedJobs();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.clean).toHaveBeenCalledWith(0, null, 'completed');
+        });
+
+        it ('#clearQueuedJobs calls bullmq drain()', async () => {
+            await queue.clearQueuedJobs();
+
+            const instance = bullmqMock.instances.queues[0];
+            expect(instance.drain).toHaveBeenCalled();
+        });
+    });
+
+
+    describe('job-list queries', () => {
+        function buildBullJob(overrides = {}) {
+            return {
+                queue:           { name: TestHelpers.Faker.Text.randomString() },
+                name:            TestHelpers.Faker.Text.randomString(),
+                data:            { args: [TestHelpers.Faker.Text.randomString()] },
+                id:              TestHelpers.Faker.Text.randomString(),
+                attemptsMade:    TestHelpers.Faker.Math.randomNumber(10),
+                attemptsStarted: TestHelpers.Faker.Math.randomNumber(10),
+                progress:        TestHelpers.Faker.Math.randomNumber(100),
+                failedReason:    TestHelpers.Faker.Text.randomString(),
+                ...overrides,
+            };
+        }
+
+        function expectedShape(bullJob) {
+            return {
+                queueName:       bullJob.queue.name,
+                name:            bullJob.name,
+                args:            bullJob.data,
+                id:              bullJob.id,
+                attemptsMade:    bullJob.attemptsMade,
+                attemptsStarted: bullJob.attemptsStarted,
+                progress:        bullJob.progress,
+                failedReason:    bullJob.failedReason,
+            };
+        }
+
+
+        it ('#getQueuedJobs maps getJobs(["paused","wait","prioritized","delayed"]) to formatted shape', async () => {
+            const bullJob1 = buildBullJob();
+            const bullJob2 = buildBullJob();
+            await queue.numQueuedJobs();
+            const instance = bullmqMock.instances.queues[0];
+            instance.getJobs.mockResolvedValue([bullJob1, bullJob2]);
+
+            const result = await queue.getQueuedJobs();
+
+            expect(instance.getJobs).toHaveBeenCalledWith(['paused', 'wait', 'prioritized', 'delayed']);
+            expect(result).toEqual([expectedShape(bullJob1), expectedShape(bullJob2)]);
+        });
+
+        it ('#getActiveJobs maps getActive() to formatted shape', async () => {
+            const bullJob = buildBullJob();
+            await queue.numQueuedJobs();
+            const instance = bullmqMock.instances.queues[0];
+            instance.getActive.mockResolvedValue([bullJob]);
+
+            const result = await queue.getActiveJobs();
+
+            expect(result).toEqual([expectedShape(bullJob)]);
+        });
+
+        it ('#getFailedJobs maps getFailed() to formatted shape', async () => {
+            const bullJob = buildBullJob();
+            await queue.numQueuedJobs();
+            const instance = bullmqMock.instances.queues[0];
+            instance.getFailed.mockResolvedValue([bullJob]);
+
+            const result = await queue.getFailedJobs();
+
+            expect(result).toEqual([expectedShape(bullJob)]);
+        });
+    });
+
+
+    describe('error handler', () => {
+        it ('forwards arguments from the bullmq error event to logger.error', async () => {
+            await queue.numQueuedJobs();
+            const instance      = bullmqMock.instances.queues[0];
+            const errorListener = bullmqMock.listenerFor(instance, 'error');
+            const err           = new Error(TestHelpers.Faker.Text.randomString());
+
+            errorListener(err);
+
+            const child = logger.queue.child.mock.results[0].value;
+            expect(child.error).toHaveBeenCalledWith(err);
+        });
+    });
+});