Web Audio API Test Utilities

Common errors

• ReferenceError: AudioContext is not defined

  cause The side-effect import `import 'web-audio-test-api';` was not executed or not executed early enough to expose `AudioContext` globally.
  fix Ensure `import 'web-audio-test-api';` is the first statement in your test file or in a setup file that runs before any code attempts to instantiate `AudioContext`.

• TypeError: OscillatorNode#frequency is readonly

  cause Attempting to assign a value directly to a `AudioParam` property (like `frequency` or `detune`) instead of its `value` property.
  fix Always assign values to the `.value` property of `AudioParam` interfaces. Correct: `osc.frequency.value = 880;` Incorrect: `osc.frequency = 880;`

• TypeError: OscillatorNode#type should be an enum { sine, square, sawtooth, triangle }, but got: [some_value]

  cause Attempting to assign a numeric value or an invalid string to the `type` property of an `OscillatorNode` or similar enum-restricted property.
  fix Ensure that properties expecting an enum value (like `OscillatorNode.type`) are assigned one of the allowed string values. Correct: `osc.type = 'sawtooth';` Incorrect: `osc.type = 2;`

Warnings

• breaking This package globally replaces the native Web Audio API interfaces (e.g., AudioContext, OscillatorNode) upon import. This can cause conflicts or unexpected behavior if other libraries expect the native API or if you try to use both the mock and real API simultaneously. Ensure it's only imported in test environments where this behavior is desired.
  Fix: Isolate its usage to dedicated test files or environments. Ensure it's imported before any other code that might initialize or check for Web Audio API availability. Use `WebAudioTestAPI.unuse()` if you need to temporarily disable it and restore the original Web Audio API.
• gotcha web-audio-test-api enforces stricter type checking and validation rules than most browser implementations of the Web Audio API. While this is a feature designed to catch common errors, it means code that might run without error in a browser (due to type coercion or lenient checks) could throw TypeErrors when tested with this library.
  Fix: Adhere strictly to Web Audio API specifications regarding types (e.g., using enum strings for `type` properties like 'sine' instead of numeric values). Treat any `TypeError` thrown by web-audio-test-api as a potential bug in your audio graph construction.
• deprecated The `web-audio-test-api` package appears to be unmaintained. The last publish to npm and code commit activity occurred over eight years ago (as of 2024). This means it may not be compatible with newer Node.js versions, updated Web Audio API specifications, or modern JavaScript features. Security vulnerabilities are also unlikely to be patched.
  Fix: Evaluate alternative, actively maintained Web Audio API testing solutions if possible. If you must use this library, thoroughly test its compatibility with your target environment and consider forking or contributing fixes yourself. Be aware of potential security risks in unmaintained dependencies.

Install

• npm install web-audio-test-api npm
• yarn add web-audio-test-api yarn
• pnpm add web-audio-test-api pnpm

Imports

• Side Effect Global Install
  wrong:

  const WebAudioTestAPI = require('web-audio-test-api');

  correct:

  import 'web-audio-test-api';

  This import statement installs the Web Audio API interfaces (like AudioContext, OscillatorNode) onto the global scope. It does not export any specific symbols directly.
• WebAudioTestAPI

  import 'web-audio-test-api';
  // Then, WebAudioTestAPI is available globally
  WebAudioTestAPI.unuse();

  After the global import, the `WebAudioTestAPI` object becomes globally available, primarily used for methods like `unuse()` to revert the global replacement.
• AudioContext
  wrong:

  import { AudioContext } from 'web-audio-test-api';

  correct:

  import 'web-audio-test-api';
  const audioContext = new AudioContext();

  AudioContext and other Web Audio API interfaces are made globally available after the side-effect import; they are not named exports from the package.

Quickstart

This quickstart demonstrates how to set up an AudioContext, create and connect several audio nodes (OscillatorNode, GainNode), configure their properties, and then serialize the entire audio graph to a JSON object for testing or debugging purposes.

import 'web-audio-test-api';

// Create a test AudioContext instance
const audioContext = new AudioContext();

// Create some nodes and connect them
const osc = audioContext.createOscillator();
const lfo = audioContext.createOscillator();
const amp = audioContext.createGain();

// Assign an ID for easier debugging in the JSON output
lfo.$id = 'LFO';

// Configure node properties
osc.type = 'sawtooth';
osc.frequency.value = 880;
lfo.frequency.value = 2;

// Connect the audio graph
lfo.connect(amp.gain);
osc.connect(amp);
amp.connect(audioContext.destination);

// Output the audio graph as a JSON object for inspection
const graphJson = audioContext.toJSON();

// In a test environment, you would assert on this JSON structure
// For demonstration, we'll log it.
console.log(JSON.stringify(graphJson, null, 2));

/* Expected output (truncated):
{
  "name": "AudioDestinationNode",
  "inputs": [
    {
      "name": "GainNode",
      "gain": {
        "value": 1,
        "inputs": [
          {
            "name": "OscillatorNode#LFO",
            "type": "sine",
            "frequency": {
              "value": 2,
              "inputs": []
            },
            "detune": {
              "value": 0,
              "inputs": []
            },
            "inputs": []
          }
        ]
      },
      "inputs": [
        {
          "name": "OscillatorNode",
          "type": "sawtooth",
          "frequency": {
            "value": 880,
            "inputs": []
          },
          "detune": {
            "value": 0,
            "inputs": []
          },
          "inputs": []
        }
      ]
    }
  ]
}
*/