Track Web API Test Library

Common errors

• Error: Cannot find module 'chai'

  cause The `chai` peer dependency has not been installed in your project.
  fix Run `npm install chai` or `yarn add chai` in your project directory.

• ReferenceError: describe is not defined

  cause The test file is either not being run by the `track-web-api-test-library` runner, or `describe` is not being imported explicitly.
  fix Ensure your test file is executed by the library's designated runner (e.g., a CLI command) or import `describe` (and `it`) explicitly: `import { describe, it } from 'track-web-api-test-library';`.

• SyntaxError: Cannot use import statement outside a module

  cause Your project is configured for CommonJS (using `require()`), but you are using ESM `import` statements, or vice-versa, without proper configuration.
  fix If using ESM, ensure your `package.json` has `"type": "module"` or files end with `.mjs`. If using CommonJS, use `require()` statements: `const { runTests } = require('track-web-api-test-library');`.

Warnings

• gotcha This library is highly specialized for 'Track Web API challenges'. Its utility outside of this specific platform or ecosystem may be limited.
  Fix: Ensure you are developing for the intended 'Track' platform before integrating this library into your workflow.
• breaking The `chai` assertion library is listed as a peer dependency. This means it must be explicitly installed by the user (`npm install chai`) alongside this library; it is not bundled.
  Fix: Run `npm install chai` or `yarn add chai` in your project's root directory to ensure the peer dependency is met and tests can run correctly.
• gotcha Without explicit documentation on the test runner's execution model, it's possible that `describe` and `it` functions may not be globally available. Always prefer importing them explicitly.
  Fix: Import `describe` and `it` from `track-web-api-test-library` to avoid 'X is not defined' errors during test execution, e.g., `import { describe, it } from 'track-web-api-test-library';`.

Install

• npm install track-web-api-test-library npm
• yarn add track-web-api-test-library yarn
• pnpm add track-web-api-test-library pnpm

Imports

• runTests
  wrong:

  const { runTests } = require('track-web-api-test-library');

  correct:

  import { runTests } from 'track-web-api-test-library';

  Assumed primary function to execute test suites. For v1.0.0, it is likely ESM-first, but CommonJS might also be supported.
• describe
  wrong:

  declare const describe: any; // Relying on globals

  correct:

  import { describe } from 'track-web-api-test-library';

  Used to group related tests. While some test runners expose `describe` globally, explicit import is safer and recommended, especially in TypeScript.
• it
  wrong:

  declare const it: any; // Relying on globals

  correct:

  import { it } from 'track-web-api-test-library';

  Used to define individual test cases. Similar to `describe`, explicit import is preferred over relying on potential global declarations.

Quickstart

This example demonstrates how to write a simple test suite for a Web API endpoint using `describe`, `it`, and `expect` (from `chai`), then how the library's `runTests` might be used (conceptually) to execute it.

import { describe, it, runTests } from 'track-web-api-test-library';
import { expect } from 'chai';

// Assuming a simple API endpoint available at /api/data
async function fetchData() {
  const response = await fetch('http://localhost:3000/api/data');
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json();
}

describe('API Data Endpoint', () => {
  it('should return a JSON object with a 'message' property', async () => {
    const data = await fetchData();
    expect(data).to.be.an('object');
    expect(data).to.have.property('message');
    expect(data.message).to.be.a('string');
  });

  it('should return the message 'Hello, Track API!'', async () => {
    const data = await fetchData();
    expect(data.message).to.equal('Hello, Track API!');
  });

  // Example of a test that might interact with an environment variable for a key
  it('should include a specific header if an API key is provided', async () => {
    const apiKey = process.env.TRACK_API_KEY ?? '';
    if (!apiKey) {
      console.warn('TRACK_API_KEY is not set. Skipping API key test.');
      return;
    }
    const response = await fetch('http://localhost:3000/api/secure-data', {
      headers: { 'X-API-Key': apiKey }
    });
    expect(response.status).to.equal(200);
  });
});

// To run these tests, you would typically execute a command like:
// 'npx track-web-api-test-runner your-test-file.js'
// or programmatically via:
// runTests('./your-test-file.js').then(results => console.log(results));
// The actual execution method might depend on the specific challenge runner CLI.