Testee Client Adapters

Common errors

• Error: Cannot find module 'testee-client/dist/testee-client.js' (or similar file not found errors for dist/ files)

  cause This error most commonly occurs when attempting to use `testee-client@0.5.2`, which was released without the necessary distribution files in its `dist/` folder, making the package effectively unusable.
  fix Ensure you are using `testee-client@0.5.3` or a later version, as version 0.5.2 was a faulty release and is missing critical files.

• process.cwd() returns an empty string or an unexpected path in StealJS/steal-tools environments

  cause A specific conflict between the `steal-tools` process shim and `testee-client`'s internal shim in versions prior to 0.5.6 caused `process.cwd()` to return an incorrect or empty value, affecting tests relying on it.
  fix Upgrade `testee-client` to version 0.5.6 or higher. This version includes a fix that rebuilds the distribution without the conflicting `steal-tools` process shim.

• Uncaught ReferenceError: Testee is not defined

  cause The `testee-client.js` script was not loaded in the browser, or `window.Testee` was accessed before the script had fully executed and populated the global object.
  fix Ensure that the `<script src="path/to/testee-client.js"></script>` tag is correctly placed in your HTML and executed before any code that attempts to access `window.Testee` or call `window.Testee.init()`.

Warnings

• breaking Version 0.5.2 was a faulty release distributed without the required `dist/` folder, rendering the package unusable if installed. Users attempting to use this specific version will encounter file not found errors.
  Fix: Upgrade to `testee-client@0.5.3` or a later version to ensure all necessary distribution files are present.
• gotcha In version 0.5.6, a conflict was identified where `steal-tools`'s process shim could inadvertently override `testee-client`'s intended process shim. This led to incorrect `process.cwd()` results (e.g., returning an empty string instead of `/`) in certain build environments, specifically affecting projects using StealJS.
  Fix: Upgrade to `testee-client@0.5.6` which includes a rebuilt distribution specifically addressing and resolving this conflicting `steal-tools` process shim.
• gotcha When integrating `testee-client` with test frameworks that load test files asynchronously (e.g., using `define` with RequireJS or StealJS), it is critical to prevent the test framework from running automatically. `window.Testee.init()` must then be called manually *after* all test files are loaded and before the framework's `run` method is invoked.
  Fix: For QUnit, set `QUnit.config.autorun = false;`. For other frameworks, ensure the framework's `run` method is called only after your test files are ready and `window.Testee.init()` has been explicitly invoked. Refer to framework-specific asynchronous loading examples in the documentation.

Install

• npm install testee-client npm
• yarn add testee-client yarn
• pnpm add testee-client pnpm

Imports

• Testee
  wrong:

  import { Testee } from 'testee-client'

  correct:

  <!-- In HTML: -->
  <script type="text/javascript" src="testee-client.js"></script>
  <script type="text/javascript">
    window.Testee = { baseURL: 'http://testee-server.com/' };
  </script>

  The library is primarily consumed as a global `window.Testee` object after being loaded via a <script> tag in a browser environment. Direct ESM/CJS imports are not the intended usage for its client-side functionality.
• Testee.init
  wrong:

  Testee.init() // Called before testee-client.js is loaded or if Testee is not on window

  correct:

  <!-- After asynchronous test files are loaded and Testee is configured: -->
  <script type="text/javascript">
    if (window.Testee) {
      window.Testee.init();
    }
  </script>

  This method is called to initialize the client adapters, especially crucial when test files are loaded asynchronously to prevent test frameworks from running prematurely. Ensure `window.Testee` exists before calling.
• Testee.start
  wrong:

  const { start } = require('testee-client'); start(...)

  correct:

  Testee.start({
    id: 'some-unique-run-id',
    environment: navigator.userAgent,
    runner: 'Mocha',
    framework: 'mocha'
  });

  Direct API calls like `Testee.start`, `Testee.suite`, `Testee.pass`, and `Testee.fail` are exposed globally for manual test flow reporting. These are typically used internally by framework adapters or for implementing custom test runners, and require `testee-client.js` to be loaded.

Quickstart

This quickstart demonstrates how to include `testee-client.js` in an HTML page, configure `window.Testee` options, and manually initialize it within a Mocha test setup that simulates asynchronous test loading. It includes basic manual reporting via the `Testee` API.

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Testee Client Quickstart</title>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/mocha@10.0.0/mocha.min.css">
  <script src="//cdn.jsdelivr.net/npm/mocha@10.0.0/mocha.min.js"></script>
  <script type="text/javascript">
    // Configure Testee client options before loading the script
    window.Testee = {
      baseURL: 'http://localhost:3030/testee-runner', // Replace with your Testee server URL
      provider: { type: 'socket.io' } // Explicitly set for clarity, socket.io is often default
    };
    mocha.setup('bdd');
  </script>
  <!-- Load testee-client AFTER configuration -->
  <script type="text/javascript" src="node_modules/testee-client/dist/testee-client.js"></script>
</head>
<body>
  <div id="mocha"></div>
  <script>
    // Simulate asynchronous test loading and then run tests
    // In a real application, 'tests.js' would contain your actual Mocha tests.
    // Here, we're embedding a simple test.
    Promise.resolve().then(() => {
      describe('My application', () => {
        it('should perform addition correctly', () => {
          // Example of manual Testee API calls (normally handled by adapters)
          if (typeof Testee !== 'undefined' && Testee.start) {
              const runId = 'qs-run-id';
              const suiteId = 'qs-suite-id';
              const testId = 'qs-test-id';

              Testee.start({ id: runId, environment: navigator.userAgent, runner: 'Mocha', framework: 'mocha' });
              Testee.suite({ id: suiteId, title: 'Quickstart Arithmetic Suite', root: true, parent: runId });
              Testee.test({ id: testId, title: '1 + 1 equals 2', parent: suiteId });
              // Actual test assertion
              if (1 + 1 === 2) {
                Testee.pass({ id: testId, duration: 2 });
              } else {
                Testee.fail({ id: testId, err: { message: 'Unexpected result' } });
              }
              Testee.testEnd({ id: testId });
          }
          // Using a common assertion library (e.g., Chai) for actual test logic
          // For this example, we'll just check directly.
          if ((1 + 1) !== 2) {
              throw new Error('1 + 1 should equal 2');
          }
        });
      });

      // After all test files are 'loaded', initialize Testee and run the framework
      if (window.Testee) {
        window.Testee.init();
      }
      mocha.run();
    });
  </script>
</body>
</html>