add playwright overview and audit documentation

GoogleChromeLabs · Jul 12, 2024 · 50aa46d · 50aa46d
1 parent 1eeccbf
commit 50aa46d
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 16 deletions.
diff --git a/src/tests/playwright/pages/realtime-sine.html b/src/tests/playwright/pages/realtime-sine.html
@@ -3,7 +3,7 @@
   <head>
     <script defer type="module">
       import {record} from './util/recorder/recorder-main.js';
-      import {beCloseTo, test, evaluateTestFunction} from './util/audit.js';
+      import {beCloseTo, test, evaluate} from './util/audit.js';
 
       test((async () => {
         const context = new AudioContext({sampleRate: 48000});
@@ -21,7 +21,7 @@
         return {buffer: float32Buffer};
       })());
 
-      evaluateTestFunction(async testResult => {
+      evaluate(async testResult => {
         const bufferData = (await testResult).buffer;
         const myRefData = await (await fetch('./reference/440@48k-sine-octx.json')).json();
 
@@ -40,6 +40,6 @@
   </head>
   <body>
     <h1>Realtime Sine Oscillator Test</h1>
-    <p>Play a sine wave at 440Hz for 1 second at 48KHz sample rate.</p>
+    <p>Play a sine wave at 440Hz for 1 second at 48kHz sample rate.</p>
   </body>
 </html>
diff --git a/src/tests/playwright/pages/util/audit.js b/src/tests/playwright/pages/util/audit.js
@@ -1,8 +1,10 @@
 /**
- * @fileoverview Provides utility functions for auditing and testing in the Web Audio Test Suite,
- * including assertions, test function evaluation, and global test state management. Designed for use in
- * scenarios requiring audio processing result validation, it supports both synchronous and asynchronous test execution.
- * Key functionalities include numeric comparison with tolerance, test scheduling, and collective assertion logging.
+ * @fileoverview Web Audio Test Suite management and utility functions.
+ * Specifies functions to define and evaluate Web Audio Tests and schedule 
+ * execution making Web Audio tests compatible with Playwright and the 
+ * Live Test Suite. Manages global test state for assertion handling. 
+ * 
+ * Additionally includes functions to validate audio processing.
  */
 
 /**
@@ -26,6 +28,7 @@ export function beCloseTo(actual, expected, threshold) {
 }
 
 /**
+ * Creates a Web Audio Test for Playwright and the Web Audio Test Suite.
  * Assigns a given test function to the global window._webAudioTest property.
  * This function is used to set up a test that can later be executed globally.
  *
@@ -38,22 +41,25 @@ export const test = (testPromise) => {
 };
 
 /**
- * Evaluates a given function by assigning it to window.webAudioEvaluate.
- * If window._webAudioSuite property is true, the function is assigned directly.
- * Otherwise, the function is invoked immediately.
+ * Evaluates a Web Audio Test and assigns the result to window.webAudioEvaluate.
+ * If window._webAudioTestSuite property is true, the function is assigned 
+ * directly. Otherwise, the function is invoked immediately.
  *
- * @param {Function} testFunction - The function to evaluate.
+ * @param {Function} testFunction - The test function to evaluate.
  * @return {any}
  */
-export const evaluateTestFunction =
-  (testFunction) =>  window.webAudioEvaluate = window._webAudioTestSuite
-    ? () => testFunction(window._webAudioTest)
-    : testFunction(window._webAudioTest);
+export const evaluate =
+    (testFunction) =>  window.webAudioEvaluate = window._webAudioTestSuite
+        ? () => testFunction(window._webAudioTest)
+        : testFunction(window._webAudioTest);
 
+// global state to accumulate assert() tests
 const tests = [];
 
 /**
  * Asserts a condition and logs a message if the condition is not met.
+ * If no arguments are specified, the function returns a boolean indicating 
+ * whether all previous assertions were true.
  *
  * @param {boolean} condition - The condition to be checked.
  * @param {string} message - The message to be logged if condition is not met.

diff --git a/src/tests/playwright/pages/util/recorder/recorder-main.js b/src/tests/playwright/pages/util/recorder/recorder-main.js
@@ -40,7 +40,7 @@ export const record = async (context, recordLength) => {
   let resolveWithRecording;
   recorder.port.onmessage = (event) => {
     if (event.data.message === 'RECORD_DONE') {
-      const {channelData} = event.data;
+      const channelData = event.data.channelData;
       const audioBuffer = new AudioBuffer({
         length: recorderBufferSize,
         sampleRate: context.sampleRate,

diff --git a/src/tests/playwright/runner.spec.ts b/src/tests/playwright/runner.spec.ts
@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Web Audio Test Suite using the Playwright Framework.
+ * Playwright will navigate and run each HTML page, capture logs,
+ * and finally check if the `evaluate` function which sets `webAudioEvaluate`
+ * returns true.
+ */
 import {test, expect} from '@playwright/test';
 
 // Capture test console logs

diff --git a/src/tests/playwright/version.spec.ts b/src/tests/playwright/version.spec.ts
@@ -1,3 +1,6 @@
+/**
+ * @fileoverview Playwright auxiliary test for checking browser version
+ */
 import {test, expect} from '@playwright/test';
 
 test('Browser version', async ({browser}) => {