jspsych 8.2.2 → 8.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych",
-  "version": "8.2.2",
+  "version": "8.2.3",
   "description": "Behavioral experiments in a browser",
   "type": "module",
   "main": "dist/index.cjs",

package/src/modules/plugins.ts

@@ -51,6 +51,7 @@ export type ParameterInfo = (
   array?: boolean;
   pretty_name?: string;
   default?: any;
+  options?: any;
 };
 
 export type ParameterInfos = Record<string, ParameterInfo>;

package/src/timeline/Trial.spec.ts

@@ -235,7 +235,7 @@ describe("Trial", () => {
     });
 
     it("respects the `save_trial_parameters` parameter", async () => {
-      const consoleSpy = jest.spyOn(console, "warn").mockImplementation();
+      const consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
 
       TestPlugin.setParameterInfos({
         stringParameter1: { type: ParameterType.STRING },
@@ -560,6 +560,110 @@ describe("Trial", () => {
       });
     });
 
+    describe("with parameter type mismatches", () => {
+      //TODO: redo these to expect errors on v9!
+      let consoleSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        consoleSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+      });
+
+      afterEach(() => {
+        consoleSpy.mockRestore();
+      });
+
+      it("errors on non-boolean values for boolean parameters", async () => {
+        TestPlugin.setParameterInfos({
+          boolParameter: { type: ParameterType.BOOL },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, boolParameter: true }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, boolParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-boolean value (`foo`) was provided for the boolean parameter "boolParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on non-string values for string parameters", async () => {
+        TestPlugin.setParameterInfos({
+          stringParameter: { type: ParameterType.STRING },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, stringParameter: "foo" }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, stringParameter: 1 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-string value (`1`) was provided for the parameter "stringParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on non-numeric values for numeric parameters", async () => {
+        TestPlugin.setParameterInfos({
+          intParameter: { type: ParameterType.INT },
+          floatParameter: { type: ParameterType.FLOAT },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, intParameter: 1, floatParameter: 1.5 }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, intParameter: "foo", floatParameter: 1.5 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-numeric value (`foo`) was provided for the numeric parameter "intParameter" in the "test" plugin.'
+        );
+
+        await createTrial({ type: TestPlugin, intParameter: 1, floatParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-numeric value (`foo`) was provided for the numeric parameter "floatParameter" in the "test" plugin.'
+        );
+
+        // this should warn but not error (behavior in v9):
+        await createTrial({ type: TestPlugin, intParameter: 1.5, floatParameter: 1.5 }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          `A float value (\`1.5\`) was provided for the integer parameter "intParameter" in the "test" plugin. The value will be truncated to an integer.`
+        );
+      });
+
+      it("errors on non-function values for function parameters", async () => {
+        TestPlugin.setParameterInfos({
+          functionParameter: { type: ParameterType.FUNCTION },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, functionParameter: () => {} }).run();
+
+        // this shouldn't:
+        await createTrial({ type: TestPlugin, functionParameter: "foo" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'A non-function value (`foo`) was provided for the function parameter "functionParameter" in the "test" plugin.'
+        );
+      });
+
+      it("errors on select parameters with values not in the options array", async () => {
+        TestPlugin.setParameterInfos({
+          selectParameter: {
+            type: ParameterType.SELECT,
+            options: ["foo", "bar"],
+          },
+        });
+
+        // this should work:
+        await createTrial({ type: TestPlugin, selectParameter: "foo" }).run();
+
+        // this shouldn't:
+
+        await createTrial({ type: TestPlugin, selectParameter: "baz" }).run();
+        expect(consoleSpy).toHaveBeenCalledWith(
+          'The value "baz" is not a valid option for the parameter "selectParameter" in the "test" plugin. Valid options are: foo, bar.'
+        );
+      });
+    });
+
     it("respects `default_iti` and `post_trial_gap``", async () => {
       dependencies.getDefaultIti.mockReturnValue(100);
       TestPlugin.setManualFinishTrialMode();

package/src/timeline/Trial.ts

@@ -360,6 +360,7 @@ export class Trial extends TimelineNode {
       for (const [parameterName, parameterConfig] of Object.entries(parameterInfos)) {
         const parameterPath = [...parentParameterPath, parameterName];
 
+        // evaluate parameter and validate required parameter
         let parameterValue = this.getParameterValue(parameterPath, {
           evaluateFunctions: parameterConfig.type !== ParameterType.FUNCTION,
           replaceResult: (originalResult) => {
@@ -379,6 +380,83 @@ export class Trial extends TimelineNode {
           },
         });
 
+        // TODO: ensure that this throws an error in v9!
+        // major parameter type validation
+        if (!parameterConfig.array && parameterValue !== null) {
+          switch (parameterConfig.type) {
+            case ParameterType.BOOL:
+              if (typeof parameterValue !== "boolean") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-boolean value (\`${parameterValue}\`) was provided for the boolean parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            // @ts-ignore falls through
+            case ParameterType.KEYS: // "ALL_KEYS", "NO_KEYS", and single key strings are checked here
+              if (Array.isArray(parameterValue)) break;
+            case ParameterType.STRING:
+            case ParameterType.HTML_STRING:
+            case ParameterType.KEY:
+            case ParameterType.AUDIO:
+            case ParameterType.VIDEO:
+            case ParameterType.IMAGE:
+              if (typeof parameterValue !== "string") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-string value (\`${parameterValue}\`) was provided for the parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.FLOAT:
+            case ParameterType.INT:
+              if (typeof parameterValue !== "number") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-numeric value (\`${parameterValue}\`) was provided for the numeric parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.FUNCTION:
+              if (typeof parameterValue !== "function") {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `A non-function value (\`${parameterValue}\`) was provided for the function parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+              break;
+            case ParameterType.SELECT:
+              if (!parameterConfig.options) {
+                const parameterPathString = parameterPathArrayToString(parameterPath);
+                console.warn(
+                  `The "options" array is required for the "select" parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin.`
+                );
+              }
+          }
+
+          // truncate floats to integers if the parameter type is INT
+          if (parameterConfig.type === ParameterType.INT && parameterValue % 1 !== 0) {
+            const parameterPathString = parameterPathArrayToString(parameterPath);
+            console.warn(
+              `A float value (\`${parameterValue}\`) was provided for the integer parameter "${parameterPathString}" in the "${this.pluginInfo.name}" plugin. The value will be truncated to an integer.`
+            );
+
+            parameterValue = Math.trunc(parameterValue);
+          }
+        }
+
+        if (parameterConfig.type === ParameterType.SELECT) {
+          if (!parameterConfig.options.includes(parameterValue)) {
+            const parameterPathString = parameterPathArrayToString(parameterPath);
+            console.warn(
+              `The value "${parameterValue}" is not a valid option for the parameter "${parameterPathString}" in the "${
+                this.pluginInfo.name
+              }" plugin. Valid options are: ${parameterConfig.options.join(", ")}.`
+            );
+          }
+        }
+
+        // array validation
         if (parameterConfig.array && !Array.isArray(parameterValue)) {
           const parameterPathString = parameterPathArrayToString(parameterPath);
           throw new Error(