basictap/lib/index.d.ts

Light tap adherent test runner

interface TestAssertions {
  /**
   * Set the number of assertions that must run until the test can finish.
   *
   * @param assertions the number of tests
   * @example
   * // Wait for 5 assertions to run.
   * t.plan(1);
   */
  plan: (assertions: number) => void;

  /**
   * Set the maximum number of milliseconds this test is allowed to run for until failing.
   *
   * @param seconds the number of milliseconds
   * @example
   * // Wait for 5000 milliseconds to run.
   * t.timeout(5000);
   */
  timeout: (timeout: number) => void;

  /**
   * Increment the passed assertions and log out an ok message
   *
   * @param message a message to show beside the logged ok
   * @example
   * t.pass('got half way through the test');
   */
  pass: (message?: string) => void;

  /**
   * Increment the failed assertions and log out a notOk message
   *
   * @param message a message to show beside the logged notOk
   * @example
   * t.fail('should not have got this far');
   */
  fail: (message?: string) => void;

  /**
   * Assert two values are exactly equal
   *
   * @param a the first value to test
   * @param a the second value to test
   * @example
   * // assert that 1+1 is 2
   * t.equal(1 + 1, 2, 'should equal 2');
   */
  equal: (a: any, b: any, message?: string) => void;

  /**
   * Assert two values are exactly unequal
   *
   * @param a the first value to test
   * @param a the second value to test
   * @example
   * // assert that 1+1 is 2
   * t.equal(1 + 1, 3, 'should not equal 3');
   */
  notEqual: (a: any, b: any, message?: string) => void;

  /**
   * Assert two values are loosely equal
   *
   * @param a the first value to test
   * @param a the second value to test
   * @example
   * // assert that 1 is '1'
   * t.looseEqual(1, '1', 'should equal 1');
   */
  looseEqual: (a: any, b: any, message?: string) => void;

  /**
   * Assert two values are loosely unequal
   *
   * @param a the first value to test
   * @param a the second value to test
   * @example
   * // assert that 1 is not '2'
   * t.notLooseEqual(1, '2', 'should not equal 2');
   */
  notLooseEqual: (a: any, b: any, message?: string) => void;

  /**
   * Assert two objects are equal when stringified
   *
   * @param a the first object to test
   * @param b the second object to test
   * @example
   * // assert that two objects have the same values
   * t.deepEqual({ a: 1 }, { a: 1 }, 'should be the same');
   */
  deepEqual: (a: any, b: any, message?: string) => void;

  /**
   * Assert two objects are not equal when stringified
   *
   * @param a the first object to test
   * @param b the second object to test
   * @example
   * // assert that two objects have the same values
   * t.deepEqual({ a: 1 }, { a: 2 }, 'should be different');
   */
  notDeepEqual: (a: any, b: any, message?: string) => void;

  /**
   * Assert a value is truthy
   *
   * @param a the value to test
   * @example
   * t.ok(true, 'should be true');
   */
  ok: (result: any, message?: string) => void;

  /**
   * Assert a value is falsy
   *
   * @param a the value to test
   * @example
   * t.notOk(false, 'should be falsy');
   */
  notOk: (result: any, message?: string) => void;

  /**
   * Continuously try running a function, until all it's assertions passes or it times out
   *
   * @param fn the fn to run
   * @param options
   * @param options.timeout the maximum number of milliseconds to keep retrying
   * @example
   * // Wait up to 100ms for i to be 5
   * let i = 0;
   * t.waitFor(() => {
   *   i = i + 1;
   *   t.equal(i, 5)
   * }, 100)
   */
  waitFor: (fn: Function, options: { timeout?: number }) => any
}

interface JobHandler {
  (testAssertions: TestAssertions): void;
}

/**
 * Add a new test to the execution queue
 *
 * @param name - Describes what the test is for
 * @param job - A function that will be run when this test is executed
 *
 * @example
 * test('test one plus one', t => {
 *   t.equal(1 + 1, 2);
 * });
 */

declare function createTest (name: string, job: JobHandler): void;

declare namespace createTest {
  /**
   * Add an event listener
   *
   * @param event - What event to listen for
   * @param fn - A function that will be run when event is emitted
   *
   * @example
   * test.on('finish', () => {
   *   console.log('all tests finished');
   * });
   */
  const on: (event: 'finish', fn: () => void) => void;

  /**
  * Add a new test, but skip the test when running the suite
  *
  * @param event - What event to listen for
  * @param fn - A function that will be run when event is emitted
  *
  * @example
  * test.skip('do not run this test', t => {
  *   t.equal(1 + 1, 2);
  * });
  */
  const skip: (name: string, job: JobHandler) => void;

  /**
  * Add a new test, and only run this (and other only tests) when the suite triggers
  *
  * @param event - What event to listen for
  * @param fn - A function that will be run when event is emitted
  *
  * @example
  * test.only('run this test', t => {
  *   t.equal(1 + 1, 2);
  * });
  */
  const only: (name: string, job: JobHandler) => void;

  /**
  * Add a test without providing a handler
  *
  * @param event - What event to listen for
  * @param fn - A function that will be run when event is emitted
  *
  * @example
  * test.todo('create this test at a later date');
  */
  const todo: (name: string) => void;

  /**
   * Trigger the test suite to run
   *
   * @example
   * test.trigger();
   */
  const trigger: () => void;
}

export default createTest;