Add tests to sound bundle

Author: leeyi45

src/bundles/sound/package.json

@@ -9,9 +9,7 @@
   "devDependencies": {
     "@sourceacademy/modules-buildtools": "workspace:^",
     "@sourceacademy/modules-lib": "workspace:^",
-    "playwright": "^1.54.1",
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.3"
+    "typescript": "^5.8.2"
   },
   "type": "module",
   "exports": {

src/bundles/sound/src/__tests__/recording.test.ts

@@ -1,4 +1,3 @@
-// @vitest-environment jsdom
 import { stringify } from 'js-slang/dist/utils/stringify';
 import {
   afterEach,
@@ -25,13 +24,26 @@ vi.spyOn(global, 'navigator', 'get').mockReturnValue({
 } as any);
 
 Object.defineProperty(global, 'AudioContext', {
-  value: () => mockAudioContext
+  value: () => {},
+  writable: true
 });
 
 Object.defineProperty(global, 'MediaRecorder', {
-  value: () => mockMediaRecorder
+  value: () => {},
+  writable: true
 });
 
+Object.defineProperty(global, 'URL', {
+  value: class {
+    static createObjectURL() {
+      return '';
+    }
+  }
+});
+
+vi.spyOn(global, 'AudioContext').mockReturnValue(mockAudioContext as any);
+vi.spyOn(global, 'MediaRecorder').mockReturnValue(mockMediaRecorder as any);
+
 beforeEach(() => {
   funcs.globalVars.recordedSound = null;
   funcs.globalVars.stream = null;

src/bundles/sound/src/__tests__/sound.test.ts

@@ -1,12 +1,15 @@
-import { afterEach, beforeEach, describe, expect, it, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, test, vi } from 'vitest';
 import * as funcs from '../functions';
 import type { Sound, Wave } from '../types';
 import { mockAudioContext } from './utils';
 
 Object.defineProperty(global, 'AudioContext', {
-  value: () => mockAudioContext
+  value: () => {},
+  writable: true,
 });
 
+vi.spyOn(global, 'AudioContext').mockReturnValue(mockAudioContext as any);
+
 describe(funcs.make_sound, () => {
   it('Should error gracefully when duration is negative', () => {
     expect(() => funcs.make_sound(() => 0, -1))
@@ -48,8 +51,7 @@ describe('Concurrent playback functions', () => {
       expect(() => funcs.play(0 as any)).toThrow('play is expecting sound, but encountered 0');
     });
 
-    test.only('Concurrently playing two sounds should error', () => {
-      console.log(AudioContext);
+    test('Concurrently playing two sounds should error', () => {
       const sound = funcs.silence_sound(10);
       expect(() => funcs.play(sound)).not.toThrow();
       expect(() => funcs.play(sound)).toThrowError('play: Previous sound still playing');

src/bundles/sound/src/functions.ts

@@ -24,11 +24,17 @@ import type {
 // Global Constants and Variables
 const FS: number = 44100; // Output sample rate
 const fourier_expansion_level: number = 5; // fourier expansion level
+/**
+ * duration of recording signal in milliseconds
+ */ 
+const recording_signal_ms = 100;
+/**
+ * duration of pause after "record" before recording signal is played
+ */
+const pre_recording_signal_pause_ms = 200;
 
 const audioPlayed: AudioPlayed[] = [];
-context.moduleContexts.sound.state = {
-  audioPlayed
-};
+context.moduleContexts.sound.state = { audioPlayed };
 
 interface BundleGlobalVars {
   /**
@@ -58,7 +64,10 @@ export const globalVars: BundleGlobalVars = {
   audioplayer: null
 };
 
-// Instantiates new audio context
+/**
+ * Returns the current AudioContext in use for the bundle. If
+ * none, initializes a new context and returns it.
+ */
 function getAudioContext() {
   if (!globalVars.audioplayer) {
     globalVars.audioplayer = new AudioContext();
@@ -79,8 +88,10 @@ function linear_decay(decay_period: number): (t: number) => number {
 // ---------------------------------------------
 // Microphone Functionality
 // ---------------------------------------------
-// check_permission is called whenever we try
-// to record a sound
+/**
+ * Determine if the user has already provided permission to use the
+ * microphone and return the provided MediaStream if they have.
+ */
 function check_permission() {
   if (globalVars.stream === null) {
     throw new Error('Call init_record(); to obtain permission to use microphone');
@@ -93,39 +104,41 @@ function check_permission() {
   return globalVars.stream;
 }
 
+/**
+ * Set up the provided MediaRecorder and begin the recording
+ * process.
+ */
 function start_recording(mediaRecorder: MediaRecorder) {
   const data: Blob[] = [];
   mediaRecorder.ondataavailable = (e) => e.data.size && data.push(e.data);
   mediaRecorder.start();
   mediaRecorder.onstop = () => process(data);
 }
 
-// duration of recording signal in milliseconds
-const recording_signal_ms = 100;
-
-// duration of pause after "run" before recording signal is played
-const pre_recording_signal_pause_ms = 200;
-
 function play_recording_signal() {
   play(sine_sound(1200, recording_signal_ms / 1000));
 }
 
+/**
+ * Converts the data received from the MediaRecorder into an AudioBuffer.
+ */
 function process(data: Blob[]) {
   const audioContext = new AudioContext();
   const blob = new Blob(data);
-
-  convertToArrayBuffer(blob)
-    .then(arrayBuffer => audioContext.decodeAudioData(arrayBuffer))
-    .then(save);
-}
-
-// Converts input microphone sound (blob) into array format.
-async function convertToArrayBuffer(blob: Blob): Promise<ArrayBuffer> {
   const url = URL.createObjectURL(blob);
-  const response = await fetch(url);
-  return response.arrayBuffer();
+  fetch(url)
+    .then(async response => {
+      const arrayBuffer = await response.arrayBuffer();
+      const decodedBuffer = await audioContext.decodeAudioData(arrayBuffer);
+      save(decodedBuffer);
+    });
 }
 
+/**
+ * Converts the data stored in the provided AudioBuffer, converts it
+ * into a Sound and then stores it into the `globalVars.recordedSound`
+ * variable.
+ */
 function save(audioBuffer: AudioBuffer) {
   const array = audioBuffer.getChannelData(0);
   const duration = array.length / FS;
@@ -140,29 +153,6 @@ function save(audioBuffer: AudioBuffer) {
   }, duration);
 }
 
-/**
- * Throws an exception if duration is not a number or if
- * number is negative
- */
-function validateDuration(func_name: string, duration: unknown): asserts duration is number {
-  if (typeof duration !== 'number') {
-    throw new Error(`${func_name} expects a number for duration, got ${duration}`);
-  }
-
-  if (duration < 0) {
-    throw new Error(`${func_name}: Sound duration must be greater than or equal to 0`);
-  }
-}
-
-/**
- * Throws an exception if wave is not a function
- */
-function validateWave(func_name: string, wave: unknown): asserts wave is Wave {
-  if (typeof wave !== 'function') {
-    throw new Error(`${func_name} expects a wave, got ${wave}`);
-  }
-}
-
 /**
  * Initialize recording by obtaining permission
  * to use the default device microphone
@@ -183,8 +173,15 @@ export function init_record(): string {
 /**
  * Records a sound until the returned stop function is called.
  * Takes a buffer duration (in seconds) as argument, and
- * returns a nullary stop. A call to the stop function returns
- * a Sound promise:
+ * returns a nullary stop. A call to the stop function returns a Sound promise.
+ * 
+ * How the function behaves in detail:
+ * 1. `record` is called.
+ * 2. The function waits for the given buffer duration.
+ * 3. The recording signal is played.
+ * 4. Recording begins when the recording signal finishes.
+ * 5. Recording stops when the returned stop function is called.
+ *
  * @example
  * ```ts
  * init_record();
@@ -196,6 +193,10 @@ export function init_record(): string {
  * @param buffer - pause before recording, in seconds
  */
 export function record(buffer: number): () => SoundPromise {
+  if (typeof buffer !== 'number' || buffer < 0) {
+    throw new Error(`${record.name}: Expected a positive number for buffer, got ${buffer}`);
+  }
+
   if (globalVars.isPlaying) {
     throw new Error(`${record.name}: Cannot record while another sound is playing!`);
   }
@@ -229,17 +230,24 @@ export function record(buffer: number): () => SoundPromise {
 }
 
 /**
- * Records a sound of given <CODE>duration</CODE> in seconds, after
- * a <CODE>buffer</CODE> also in seconds, and
- * returns a Sound promise: a nullary function
- * that returns a Sound. Example: <PRE><CODE>init_record();
- * const promise = record_for(2, 0.5);
- * // In next query, you can play the promised Sound, by
- * // applying the promise:
- * play(promise());</CODE></PRE>
+ * Records a sound of a given duration. Returns a Sound promise.
+ * 
+ * How the function behaves in detail:
+ * 1. `record_for` is called.
+ * 2. The function waits for the given buffer duration.
+ * 3. The recording signal is played.
+ * 4. Recording begins when the recording signal finishes.
+ * 5. The recording signal plays to signal the end after the given duration.
+ * 
+ * @example
+ * ```
+ * init_record();
+ * const promise = record_for(2, 0.5); // begin recording after 0.5s for 2s
+ * const sound = promise();            // retrieve the recorded sound
+ * play(sound);                        // and do whatever with it
+ * ```
  * @param duration duration in seconds
  * @param buffer pause before recording, in seconds
- * @return <CODE>promise</CODE>: nullary function which returns recorded Sound
  */
 export function record_for(duration: number, buffer: number): SoundPromise {
   if (globalVars.isPlaying) {
@@ -278,15 +286,28 @@ export function record_for(duration: number, buffer: number): SoundPromise {
   return promise;
 }
 
-// =============================================================================
-// Module's Exposed Functions
-//
-// This file only includes the implementation and documentation of exposed
-// functions of the module. For private functions dealing with the browser's
-// graphics library context, see './webGL_curves.ts'.
-// =============================================================================
+/**
+ * Throws an exception if duration is not a number or if
+ * number is negative
+ */
+function validateDuration(func_name: string, duration: unknown): asserts duration is number {
+  if (typeof duration !== 'number') {
+    throw new Error(`${func_name} expects a number for duration, got ${duration}`);
+  }
+
+  if (duration < 0) {
+    throw new Error(`${func_name}: Sound duration must be greater than or equal to 0`);
+  }
+}
 
-// Core functions
+/**
+ * Throws an exception if wave is not a function
+ */
+function validateWave(func_name: string, wave: unknown): asserts wave is Wave {
+  if (typeof wave !== 'function') {
+    throw new Error(`${func_name} expects a wave, got ${wave}`);
+  }
+}
 
 /**
  * Makes a Sound with given wave function and duration.

src/bundles/sound/vitest.config.js

@@ -9,11 +9,6 @@ export default defineConfig({
     root: import.meta.dirname,
     browser: {
       enabled: false,
-      provider: 'playwright',
-      instances: [{
-        screenshotFailures: false,
-        browser: 'chromium',
-      }]
     }
   }
 });

yarn.lock

@@ -3530,6 +3530,7 @@ __metadata:
   dependencies:
     "@sourceacademy/bundle-midi": "workspace:^"
     "@sourceacademy/modules-buildtools": "workspace:^"
+    "@sourceacademy/modules-lib": "workspace:^"
     js-slang: "npm:^1.0.81"
     typescript: "npm:^5.8.2"
   languageName: unknown