DWVv0.37.0
tests/utils/thread.test.jsjavascript
import {describe, test, assert, vi, beforeEach} from 'vitest';
import {
  ThreadPool,
  WorkerTask,
  getDefaultPoolSize,
  clampPoolSize
} from '../../src/utils/thread.js';

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/**
 * Build a WorkerTask backed by a mock worker so no real Web Worker is spawned.
 * The mock worker exposes `postMessage`, `terminate`, `onmessage`, `onerror`
 * as plain spies. After `addWorkerTask` runs, the pool wires its own callbacks
 * onto `mockWorker.onmessage` / `.onerror`, so calling those in tests
 * simulates the worker responding.
 *
 * @param {object} [message] Start message for the task.
 * @param {object} [info] Info object attached to the task.
 * @returns {WorkerTask} The task with an extra `.mockWorker` property.
 */
function makeTask(message = {}, info = {}) {
  const mockWorker = {
    postMessage: vi.fn(),
    terminate: vi.fn(),
    onmessage: null,
    onerror: null
  };
  const task = new WorkerTask(message, info);
  task.getWorker = () => mockWorker;
  task.mockWorker = mockWorker;
  return task;
}

/**
 * Build a ThreadPool with spies on every event handler.
 *
 * @param {number} size Pool size.
 * @returns {{pool: ThreadPool, events: object}} Pool and a map of spy handlers.
 */
function makePool(size) {
  const pool = new ThreadPool(size);
  const events = {
    workstart: vi.fn(),
    workitem: vi.fn(),
    work: vi.fn(),
    workend: vi.fn(),
    error: vi.fn(),
    abort: vi.fn()
  };
  pool.onworkstart = events.workstart;
  pool.onworkitem = events.workitem;
  pool.onwork = events.work;
  pool.onworkend = events.workend;
  pool.onerror = events.error;
  pool.onabort = events.abort;
  return {pool, events};
}

describe('utils', () => {

  beforeEach(() => {
    vi.clearAllMocks();
  });

  // -------------------------------------------------------------------------
  // WorkerTask
  // -------------------------------------------------------------------------

  /**
   * Tests for {@link WorkerTask} constructor.
   *
   * @function module:tests/utils~WorkerTask
   */
  test('WorkerTask constructor stores startMessage and info', () => {
    const msg = {buffer: new Uint8Array([1, 2])};
    const info = {frameIndex: 3};
    const task = new WorkerTask(msg, info);
    assert.equal(task.startMessage, msg);
    assert.equal(task.info, info);
  });

  /**
   * Tests that {@link WorkerTask#getStartMessage} returns the start message
   * with no transferred objects by default.
   *
   * @function module:tests/utils~WorkerTaskGetStartMessage
   */
  test('WorkerTask getStartMessage default', () => {
    const msg = {buffer: new Uint8Array([1, 2])};
    const task = new WorkerTask(msg, {});
    const res = task.getStartMessage();
    assert.equal(res.message, msg, 'start message');
    assert.deepEqual(res.transfer, [], 'no transfer');
  });

  /**
   * Tests that {@link WorkerTask#getWorker} returns undefined by default.
   *
   * @function module:tests/utils~WorkerTaskGetWorker
   */
  test('WorkerTask getWorker returns undefined by default', () => {
    const task = new WorkerTask({}, {});
    assert.isUndefined(task.getWorker());
  });

  /**
   * Tests for {@link getDefaultPoolSize}.
   *
   * @function module:tests/utils~getDefaultPoolSize
   */
  test('getDefaultPoolSize', () => {
    // half the hardware concurrency
    vi.stubGlobal('navigator', {hardwareConcurrency: 8});
    assert.equal(getDefaultPoolSize(), 4, 'half hardware concurrency');
    vi.stubGlobal('navigator', {hardwareConcurrency: 5});
    assert.equal(getDefaultPoolSize(), 2, 'rounded down');
    // single processor: at least one
    vi.stubGlobal('navigator', {hardwareConcurrency: 1});
    assert.equal(getDefaultPoolSize(), 1, 'at least one');
    // not available
    vi.stubGlobal('navigator', {});
    assert.equal(getDefaultPoolSize(), 4, 'fallback without concurrency');
    vi.stubGlobal('navigator', undefined);
    assert.equal(getDefaultPoolSize(), 4, 'fallback without navigator');
    vi.unstubAllGlobals();
  });

  /**
   * Tests for {@link ThreadPool} constructor input validation.
   *
   * @function module:tests/utils~ThreadPoolConstructor
   */
  test('ThreadPool constructor validates the pool size', () => {
    assert.doesNotThrow(() => new ThreadPool(), 'undefined (default)');
    assert.doesNotThrow(() => new ThreadPool(1), 'one');
    assert.doesNotThrow(() => new ThreadPool(8), 'eight');
    const badSizes = [0, -1, 1.5, Number.NaN, Infinity, null, '2'];
    for (const size of badSizes) {
      assert.throws(() => new ThreadPool(size), /positive integer/,
        undefined, `throws for ${String(size)}`);
    }
  });

  /**
   * Tests for {@link clampPoolSize}.
   *
   * @function module:tests/utils~clampPoolSize
   */
  test('clampPoolSize', () => {
    vi.stubGlobal('navigator', {hardwareConcurrency: 4});
    assert.equal(clampPoolSize(2), 2, 'below: unchanged');
    assert.equal(clampPoolSize(4), 4, 'at limit: unchanged');
    assert.equal(clampPoolSize(10), 4, 'above: clamped');
    vi.stubGlobal('navigator', {});
    assert.equal(clampPoolSize(10), 10, 'no concurrency: unchanged');
    vi.stubGlobal('navigator', undefined);
    assert.equal(clampPoolSize(10), 10, 'no navigator: unchanged');
    vi.unstubAllGlobals();
  });

  /**
   * Tests that default event handlers are no-ops.
   *
   * @function module:tests/utils~ThreadPoolHandlers
   */
  test('ThreadPool default event handlers exist and do not throw', () => {
    const pool = new ThreadPool(1);
    assert.doesNotThrow(() => pool.onworkstart({}));
    assert.doesNotThrow(() => pool.onworkitem({}));
    assert.doesNotThrow(() => pool.onwork({}));
    assert.doesNotThrow(() => pool.onworkend({}));
    assert.doesNotThrow(() => pool.onerror({}));
    assert.doesNotThrow(() => pool.onabort({}));
  });

  // -------------------------------------------------------------------------
  // ThreadPool — addWorkerTask
  // -------------------------------------------------------------------------

  /**
   * Tests that addWorkerTask fires onworkstart on the first task only.
   *
   * @function module:tests/utils~ThreadPoolWorkStart
   */
  test('ThreadPool addWorkerTask fires onworkstart only for the first task',
    () => {
      const {pool, events} = makePool(2);
      const t1 = makeTask();
      const t2 = makeTask();

      pool.addWorkerTask(t1);
      assert.equal(events.workstart.mock.calls.length, 1,
        'onworkstart fired after first task');

      pool.addWorkerTask(t2);
      assert.equal(events.workstart.mock.calls.length, 1,
        'onworkstart not fired again for second task');
    }
  );

  /**
   * Tests that addWorkerTask dispatches the task immediately when a thread
   * is free (postMessage called, thread moved to runningThreads).
   *
   * @function module:tests/utils~threadPoolImmediateDispatch
   */
  test('ThreadPool addWorkerTask dispatches task immediately when thread free',
    () => {
      const {pool} = makePool(1);
      const msg = {buffer: new Uint8Array([7])};
      const task = makeTask(msg, {});

      pool.addWorkerTask(task);

      assert.equal(task.mockWorker.postMessage.mock.calls.length, 1,
        'worker.postMessage called once');
      assert.equal(
        task.mockWorker.postMessage.mock.calls[0][0],
        msg,
        'correct message forwarded'
      );
      assert.deepEqual(
        task.mockWorker.postMessage.mock.calls[0][1],
        [],
        'empty transfer list forwarded'
      );
    }
  );

  /**
   * Tests that the worker thread posts the message and transfer list
   * returned by {@link WorkerTask#getStartMessage}.
   *
   * @function module:tests/utils~threadPoolTransfer
   */
  test('ThreadPool posts the task start message with its transfer list',
    () => {
      const {pool} = makePool(1);
      const task = makeTask({buffer: new Uint8Array([7])}, {});
      const sent = {buffer: new Uint8Array([8])};
      task.getStartMessage = () => ({
        message: sent,
        transfer: [sent.buffer.buffer]
      });

      pool.addWorkerTask(task);

      const call = task.mockWorker.postMessage.mock.calls[0];
      assert.equal(call[0], sent, 'getStartMessage message posted');
      assert.equal(call[1].length, 1, 'one transferred object');
      assert.equal(call[1][0], sent.buffer.buffer, 'transfer list posted');
    }
  );

  /**
   * Tests that addWorkerTask queues a task when no thread is free.
   *
   * @function module:tests/utils~threadPoolQueue
   */
  test('ThreadPool addWorkerTask queues task when all threads are busy', () => {
    const {pool} = makePool(1);
    const t1 = makeTask();
    const t2 = makeTask();

    pool.addWorkerTask(t1); // occupies the only thread
    pool.addWorkerTask(t2); // should be queued

    assert.equal(t2.mockWorker.postMessage.mock.calls.length, 0,
      'second task not yet dispatched');
  });

  // -------------------------------------------------------------------------
  // ThreadPool — task completion (onmessage)
  // -------------------------------------------------------------------------

  /**
   * Tests that when a worker replies, onworkitem is called with the event
   * augmented by task info.
   *
   * @function module:tests/utils~threadPoolWorkitem
   */
  test('ThreadPool fires onworkitem with augmented event on worker reply',
    () => {
      const {pool, events} = makePool(1);
      const info = {
        itemNumber: 2,
        numberOfItems: 5,
        index: 7,
        indexOrigin: 0
      };
      const task = makeTask({}, info);
      pool.addWorkerTask(task);

      // Simulate worker posting a result
      task.mockWorker.onmessage({data: 'result'});

      assert.equal(events.workitem.mock.calls.length, 1);
      const evt = events.workitem.mock.calls[0][0];
      assert.equal(evt.itemNumber, 2);
      assert.equal(evt.numberOfItems, 5);
      assert.equal(evt.index, 7);
      assert.equal(evt.indexOrigin, 0);
      assert.equal(evt.data, 'result');
    }
  );

  /**
   * Tests that when the last task completes, onwork and onworkend are fired
   * and the thread is returned to freeThreads.
   *
   * @function module:tests/utils~threadPoolWorkDone
   */
  test('ThreadPool fires onwork and onworkend when all tasks complete', () => {
    const {pool, events} = makePool(1);
    const task = makeTask();
    pool.addWorkerTask(task);

    task.mockWorker.onmessage({});

    assert.equal(events.work.mock.calls.length, 1, 'onwork fired');
    assert.equal(events.workend.mock.calls.length, 1, 'onworkend fired');
  });

  /**
   * Tests that a queued task is dispatched when a running task finishes.
   *
   * @function module:tests/utils~threadPoolQueueDrain
   */
  test('ThreadPool runs next queued task when a thread is freed', () => {
    const {pool, events} = makePool(1);
    const t1 = makeTask({id: 1}, {});
    const t2 = makeTask({id: 2}, {});

    pool.addWorkerTask(t1);
    pool.addWorkerTask(t2); // queued

    // t1 finishes — t2 should now start on the same worker
    t1.mockWorker.onmessage({});

    assert.equal(
      t1.mockWorker.postMessage.mock.calls.length, 2,
      'same worker reused for queued task'
    );
    assert.deepEqual(
      t1.mockWorker.postMessage.mock.calls[1][0],
      {id: 2},
      'queued task message dispatched'
    );
    // pool not done yet — one task still running
    assert.equal(events.workend.mock.calls.length, 0,
      'onworkend not yet fired');

    // t2 finishes
    t1.mockWorker.onmessage({});
    assert.equal(events.work.mock.calls.length, 1, 'onwork fired at the end');
    assert.equal(events.workend.mock.calls.length, 1,
      'onworkend fired at the end');
  });

  /**
   * Tests that multiple tasks across multiple threads all complete correctly.
   *
   * @function module:tests/utils~threadPoolMultiThread
   */
  test('ThreadPool handles concurrent tasks on multiple threads', () => {
    const {pool, events} = makePool(2);
    const t1 = makeTask({}, {itemNumber: 0, numberOfItems: 2});
    const t2 = makeTask({}, {itemNumber: 1, numberOfItems: 2});

    pool.addWorkerTask(t1);
    pool.addWorkerTask(t2);

    assert.equal(t1.mockWorker.postMessage.mock.calls.length, 1,
      't1 dispatched');
    assert.equal(t2.mockWorker.postMessage.mock.calls.length, 1,
      't2 dispatched');

    // t1 finishes
    t1.mockWorker.onmessage({});
    assert.equal(events.workend.mock.calls.length, 0,
      'not done yet after t1');

    // t2 finishes
    t2.mockWorker.onmessage({});
    assert.equal(events.work.mock.calls.length, 1, 'onwork after both done');
    assert.equal(events.workend.mock.calls.length, 1,
      'onworkend after both done');
  });

  // -------------------------------------------------------------------------
  // ThreadPool — abort
  // -------------------------------------------------------------------------

  /**
   * Tests that abort() stops running workers, clears the queue, and
   * fires onabort + onworkend.
   *
   * @function module:tests/utils~threadPoolAbort
   */
  test('ThreadPool abort stops workers, clears queue, fires onabort', () => {
    const {pool, events} = makePool(1);
    const t1 = makeTask();
    const t2 = makeTask();
    pool.addWorkerTask(t1); // running
    pool.addWorkerTask(t2); // queued

    pool.abort();

    assert.equal(t1.mockWorker.terminate.mock.calls.length, 1,
      'running worker terminated');
    assert.equal(events.abort.mock.calls.length, 1, 'onabort fired');
    assert.equal(events.workend.mock.calls.length, 1, 'onworkend fired');
  });

  /**
   * Tests that the pool is fully operational after an abort.
   *
   * @function module:tests/utils~threadPoolReuseAfterAbort
   */
  test('ThreadPool is reusable after abort', () => {
    const {pool, events} = makePool(1);
    pool.addWorkerTask(makeTask());
    pool.abort();

    // reset spies so counts start from zero
    vi.clearAllMocks();
    // re-attach handlers (cleared by vi.clearAllMocks)
    pool.onworkstart = events.workstart;
    pool.onworkitem = events.workitem;
    pool.onwork = events.work;
    pool.onworkend = events.workend;
    pool.onerror = events.error;
    pool.onabort = events.abort;

    const t2 = makeTask({}, {itemNumber: 0, numberOfItems: 1});
    pool.addWorkerTask(t2);

    assert.equal(events.workstart.mock.calls.length, 1,
      'onworkstart fired after reuse');
    assert.equal(t2.mockWorker.postMessage.mock.calls.length, 1,
      'task dispatched after reuse');

    t2.mockWorker.onmessage({});
    assert.equal(events.work.mock.calls.length, 1, 'onwork fired');
    assert.equal(events.workend.mock.calls.length, 1, 'onworkend fired');
  });

  // -------------------------------------------------------------------------
  // ThreadPool — worker error
  // -------------------------------------------------------------------------

  /**
   * Tests that a worker error stops all threads and fires onerror + onworkend.
   *
   * @function module:tests/utils~threadPoolError
   */
  test('ThreadPool handles worker error: stops pool and fires onerror', () => {
    const {pool, events} = makePool(2);
    const t1 = makeTask({}, {itemNumber: 0, numberOfItems: 2});
    const t2 = makeTask({}, {itemNumber: 1, numberOfItems: 2});
    pool.addWorkerTask(t1);
    pool.addWorkerTask(t2);

    // Simulate t1's worker throwing an error
    t1.mockWorker.onerror({type: 'error'});

    assert.equal(events.error.mock.calls.length, 1, 'onerror fired');
    assert.equal(events.workend.mock.calls.length, 1, 'onworkend fired');
    // Both workers must be stopped
    assert.equal(t1.mockWorker.terminate.mock.calls.length, 1,
      't1 worker terminated');
    assert.equal(t2.mockWorker.terminate.mock.calls.length, 1,
      't2 worker terminated');
  });

});