Appium Test Support Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'expects')

  cause Attempting to call `.expects()` on a mock object that has not been correctly initialized or passed to `withMocks` or `withSandbox`.
  fix Ensure the object being mocked is explicitly included in the `mocks` configuration object passed to `withMocks` or `withSandbox` and accessed via the provided `mocks` or `S.mocks` parameter, e.g., `withMocks({ myApi }, (mocks) => { mocks.myApi.expects(...) });`.

• Error: Sandbox not found

  cause This error typically occurs when `fakeTime` or other sandbox-dependent utilities are used without an active Sinon sandbox instance, or if `sinon.createSandbox()` was not called prior to their use.
  fix Ensure `sinon.createSandbox()` is called in a `beforeEach` hook and the resulting sandbox instance is passed to `fakeTime`. Also, always call `sandbox.restore()` in an `afterEach` hook to clean up.

• Error: 'console.error' was replaced, but unable to restore.

  cause A common issue when stubbing global objects like `console` or `process.env` (which `stubEnv` might interact with implicitly) without proper restoration, especially if multiple testing libraries or stubs conflict.
  fix Verify that no other testing utilities or libraries are conflictingly stubbing `process.env` or `console` within the same test context. Ensure `stubEnv` is used within a clean context where its internal restoration mechanism can operate without interference.

Warnings

• breaking Upgrades to underlying testing libraries like Sinon.js (if they are direct dependencies of `appium-test-support` or peer dependencies of your project) can introduce breaking changes to how stubs, mocks, and fake timers behave. Always consult the release notes of `sinon` when upgrading your testing dependencies.
  Fix: Review `sinon.js` migration guides for specific API changes and update your test code accordingly. Pin `sinon.js` version in your `package.json` if conflicts arise to ensure consistent behavior.
• gotcha Failure to properly manage Sinon sandboxes (e.g., calling `sandbox.restore()` in `afterEach`) can lead to test pollution, where stubs and mocks from one test leak into subsequent tests, causing unpredictable and flaky failures. This applies to `withSandbox`, `withMocks`, and `fakeTime`.
  Fix: Always ensure `sandbox.restore()` is explicitly called in an `afterEach` hook or equivalent cleanup function provided by your test runner (e.g., `afterEach(() => sandbox.restore());`).
• gotcha `stubEnv` only affects `process.env` within the current test context and ensures it's restored after the test. Misunderstanding its scope can lead to confusion if expecting global or persistent changes, or if used in an environment where `process.env` might be mutated by other means outside the library's control.
  Fix: Always assume `stubEnv` provides local, test-scoped environment variable manipulation. For complex scenarios or interactions with external processes, consider explicit environment setup/teardown in hooks.
• gotcha The `stripColors` option in `stubLog` specifically targets common ANSI color codes. If your logging library uses non-standard color representations or custom formatting, `stripColors: true` might not produce the expected plain text output, potentially leaving unexpected characters in your log assertions.
  Fix: Verify the `stripColors` behavior with your specific logging library. If not working as expected, manually strip non-ANSI color codes or customize the `stubLog` output processing further before asserting.

Install

• npm install appium-test-support npm
• yarn add appium-test-support yarn
• pnpm add appium-test-support pnpm

Imports

• stubEnv
  wrong:

  const stubEnv = require('appium-test-support').stubEnv;

  correct:

  import { stubEnv } from 'appium-test-support';

  Primarily used in modern Node.js testing environments, assumes an ESM setup for direct imports.
• stubLog
  wrong:

  import stubLog from 'appium-test-support/stubLog';

  correct:

  import { stubLog } from 'appium-test-support';

  This is a named export; direct access via a submodule path or a default import is incorrect.
• withSandbox
  wrong:

  const { withSandbox } = require('appium-test-support');

  correct:

  import { withSandbox } from 'appium-test-support';

  Designed to integrate with Sinon.js for comprehensive mocking and stubbing within test suites. While CJS might work, ESM is the idiomatic usage shown.
• fakeTime
  wrong:

  import * as fakeTime from 'appium-test-support/fakeTime';

  correct:

  import { fakeTime } from 'appium-test-support';

  Requires a Sinon sandbox instance for proper time manipulation and is a named export.

Quickstart

Demonstrates how to use `fakeTime` with a Sinon.js sandbox to control and fast-forward time in asynchronous tests, verifying the outcome of time-dependent operations. This setup requires `sinon` and a test runner like `mocha` with `chai` for assertions.

import { fakeTime } from 'appium-test-support';
import sinon from 'sinon'; // Requires 'sinon' as a dev dependency
import { expect } from 'chai'; // Requires 'chai' for assertions

// Simplified Promise-like object for demonstration if Bluebird isn't available
class CustomPromise {
  constructor(executor) {
    this.resolve = null;
    this.reject = null;
    const promise = new Promise((res, rej) => {
      this.resolve = res;
      this.reject = rej;
    });
    executor(this.resolve, this.reject);
    return promise;
  }
}

function doSomethingThatTakesTime() {
  return new CustomPromise((resolve) => {
    let ret = '';
    function appendOneByOne () {
      if(ret.length >= 10) {
        return resolve(ret);
      }
      setTimeout(() => {
        ret = ret + ret.length;
        appendOneByOne();
      }, 1000);
    }
    appendOneByOne();
  });
}

describe('fakeTime demonstration', () => {
  let sandbox: sinon.SinonSandbox;

  beforeEach(() => {
    sandbox = sinon.createSandbox();
  });

  afterEach(() => {
    sandbox.restore();
  });

  it('should fast-forward time to test async operations', async () => {
    const timeLord = fakeTime(sandbox);
    const p = doSomethingThatTakesTime();
    // Simulate 60 intervals of 200ms each, effectively advancing 12000ms (12 seconds)
    // This allows the `doSomethingThatTakesTime` function to complete its 10 * 1000ms operations.
    timeLord.speedup(200, 60);
    expect(await p).to.equal('0123456789');
  });
});