fix(comparadise-utils): enforce rawName argument when test file conta…

…ins multiple tests (#355)

Co-authored-by: danadajian <[email protected]>

comparadise-utils/match-screenshot.ts

@@ -28,6 +28,17 @@ function getTestFolderPathFromScripts(rawName?: string) {
     );
   }
 
+  const currentTestNumber = Cypress.mocha.getRunner().currentRunnable?.order;
+  if (
+    !rawName &&
+    typeof currentTestNumber === 'number' &&
+    currentTestNumber > 1
+  ) {
+    throw new Error(
+      '❌ The rawName argument was not provided to matchScreenshot and is required for test files containing multiple tests!'
+    );
+  }
+
   const testName = relativeTestPath.substring(
     relativeTestPath.lastIndexOf('/') + 1,
     relativeTestPath.lastIndexOf(SUFFIX_TEST_IDENTIFIER)
@@ -118,3 +129,19 @@ Cypress.Commands.add(
   { prevSubject: ['optional', 'element', 'window', 'document'] },
   matchScreenshot
 );
+
+interface ExtendedCurrentRunnable extends Mocha.Runnable {
+  currentRunnable?: {
+    order?: unknown;
+  };
+}
+
+declare global {
+  namespace Cypress {
+    interface Cypress {
+      mocha: {
+        getRunner: () => ExtendedCurrentRunnable;
+      };
+    }
+  }
+}

docs/docs/setup/writing-visual-tests.md

@@ -70,7 +70,7 @@ describe('MyComponent visual test', () => {
 
 By default, `matchScreenshot` will infer the name of your test from the name of your file and create a folder to save the base, new, and diff images to.
 
-However, if you have multiple visual tests in a single file, you should pass a different `rawName` for each test to vary the paths where screenshots will be saved.
+However, if you have multiple visual tests in a single file, you are required to provide a different `rawName` for each test to vary the paths where screenshots will be saved.
 
 #### options - optional (Cypress.ScreenshotOptions)