feat: Add before:run event

cli/schema/cypress.schema.json

@@ -243,7 +243,7 @@
     "experimentalRunEvents": {
       "type": "boolean",
       "default": false,
-      "description": "Allows listening to the `before:spec` and `after:spec` events in the plugins file."
+      "description": "Allows listening to the `before:run`, `before:spec`, and `after:spec` events in the plugins file."
     },
     "experimentalSourceRewriting": {
       "type": "boolean",

cli/types/cypress.d.ts

@@ -2577,7 +2577,7 @@ declare namespace Cypress {
      */
     firefoxGcInterval: Nullable<number | { runMode: Nullable<number>, openMode: Nullable<number> }>
     /**
-     * Allows listening to the `before:spec` and `after:spec` events in the plugins file.
+     * Allows listening to the `before:run`, `before:spec`, and `after:spec` events in the plugins file.
      * @default false
      */
     experimentalRunEvents: boolean
@@ -4999,9 +4999,28 @@ declare namespace Cypress {
     [key: string]: Task
   }
 
+  interface SystemDetails {
+    osName: string
+    osVersion: string
+  }
+
+  interface BeforeRunDetails {
+    browser: Browser
+    config: ConfigOptions
+    cypressVersion: string
+    group?: string
+    parallel: boolean
+    runUrl?: string
+    specs: Spec[]
+    specPattern: string[]
+    system: SystemDetails
+    tag?: string
+  }
+
   interface PluginEvents {
     (action: 'after:screenshot', fn: (details: ScreenshotDetails) => void | AfterScreenshotReturnObject | Promise<AfterScreenshotReturnObject>): void
     (action: 'after:spec', fn: (spec: Spec, results: CypressCommandLine.RunResult) => void | Promise<void>): void
+    (action: 'before:run', fn: (runDetails: BeforeRunDetails) => void | Promise<void>): void
     (action: 'before:spec', fn: (spec: Spec) => void | Promise<void>): void
     (action: 'before:browser:launch', fn: (browser: Browser, browserLaunchOptions: BrowserLaunchOptions) => void | BrowserLaunchOptions | Promise<BrowserLaunchOptions>): void
     (action: 'file:preprocessor', fn: (file: FileObject) => string | Promise<string>): void

packages/server/__snapshots__/4_plugin_run_events_spec.ts.js

@@ -1,12 +1,3 @@
-exports['e2e plugin run events / fails if experimentalRunEvents is not enabled'] = `
-The following validation error was thrown by your plugins file (\`/foo/bar/.projects/plugin-run-events/cypress/plugins/index.js\`).
-
- Error: The \`before:spec\` event requires the experimentalRunEvents flag to be enabled.
-
-To enable it, set \`"experimentalRunEvents": true\` in your cypress.json
-      [stack trace lines]
-`
-
 exports['e2e plugin run events / sends events'] = `
 
 ====================================================================================================
@@ -21,6 +12,8 @@ exports['e2e plugin run events / sends events'] = `
   │ Experiments:  experimentalRunEvents=true                                                       │
   └────────────────────────────────────────────────────────────────────────────────────────────────┘
 
+before:run: cypress/integration/run_events_spec_1.js electron
+before:run is awaited
 
 ────────────────────────────────────────────────────────────────────────────────────────────────────
 
@@ -33,6 +26,8 @@ before:spec is awaited
 
   1 passing
 
+spec:end: cypress/integration/run_events_spec_1.js { tests: 1, passes: 1, failures: 0 }
+after:spec is awaited
 
   (Results)
 
@@ -48,8 +43,6 @@ before:spec is awaited
   │ Spec Ran:     run_events_spec_1.js                                                             │
   └────────────────────────────────────────────────────────────────────────────────────────────────┘
 
-spec:end: cypress/integration/run_events_spec_1.js { tests: 1, passes: 1, failures: 0 }
-after:spec is awaited
 
 ────────────────────────────────────────────────────────────────────────────────────────────────────
 
@@ -62,6 +55,8 @@ before:spec is awaited
 
   1 passing
 
+spec:end: cypress/integration/run_events_spec_2.js { tests: 1, passes: 1, failures: 0 }
+after:spec is awaited
 
   (Results)
 
@@ -77,8 +72,6 @@ before:spec is awaited
   │ Spec Ran:     run_events_spec_2.js                                                             │
   └────────────────────────────────────────────────────────────────────────────────────────────────┘
 
-spec:end: cypress/integration/run_events_spec_2.js { tests: 1, passes: 1, failures: 0 }
-after:spec is awaited
 
 ====================================================================================================
 
@@ -96,6 +89,74 @@ after:spec is awaited
 
 `
 
+exports['e2e plugin run events / handles video being deleted in after:spec'] = `
+
+====================================================================================================
+
+  (Run Starting)
+
+  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
+  │ Cypress:      1.2.3                                                                            │
+  │ Browser:      FooBrowser 88                                                                    │
+  │ Specs:        1 found (after_spec_deletes_video.js)                                            │
+  │ Searched:     cypress/integration/*                                                            │
+  │ Experiments:  experimentalRunEvents=true                                                       │
+  └────────────────────────────────────────────────────────────────────────────────────────────────┘
+
+
+────────────────────────────────────────────────────────────────────────────────────────────────────
+
+  Running:  after_spec_deletes_video.js                                                     (1 of 1)
+
+
+  ✓ is true
+
+  1 passing
+
+Warning: We could not find the video at the following path, so we were unable to process it.
+
+Video path: /foo/bar/.projects/plugin-after-spec-deletes-video/cypress/videos/after_spec_deletes_video.js.mp4
+
+This error will not alter the exit code.
+
+  (Results)
+
+  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
+  │ Tests:        1                                                                                │
+  │ Passing:      1                                                                                │
+  │ Failing:      0                                                                                │
+  │ Pending:      0                                                                                │
+  │ Skipped:      0                                                                                │
+  │ Screenshots:  0                                                                                │
+  │ Video:        false                                                                            │
+  │ Duration:     X seconds                                                                        │
+  │ Spec Ran:     after_spec_deletes_video.js                                                      │
+  └────────────────────────────────────────────────────────────────────────────────────────────────┘
+
+
+====================================================================================================
+
+  (Run Finished)
+
+
+       Spec                                              Tests  Passing  Failing  Pending  Skipped  
+  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
+  │ ✔  after_spec_deletes_video.js              XX:XX        1        1        -        -        - │
+  └────────────────────────────────────────────────────────────────────────────────────────────────┘
+    ✔  All specs passed!                        XX:XX        1        1        -        -        -  
+
+
+`
+
+exports['e2e plugin run events / fails if experimentalRunEvents is not enabled'] = `
+The following validation error was thrown by your plugins file (\`/foo/bar/.projects/plugin-run-events/cypress/plugins/index.js\`).
+
+ Error: The \`before:run\` event requires the experimentalRunEvents flag to be enabled.
+
+To enable it, set \`"experimentalRunEvents": true\` in your cypress.json
+      [stack trace lines]
+`
+
 exports['e2e plugin run events / fails run if event handler throws'] = `
 
 ====================================================================================================

packages/server/__snapshots__/5_spec_isolation_spec.js

@@ -407,7 +407,7 @@ exports['e2e spec_isolation fails [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -523,7 +523,7 @@ exports['e2e spec_isolation fails [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -645,7 +645,7 @@ exports['e2e spec_isolation fails [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_hooks_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -708,7 +708,7 @@ exports['e2e spec_isolation fails [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_passing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",
@@ -971,7 +971,7 @@ exports['e2e spec_isolation fails [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1087,7 +1087,7 @@ exports['e2e spec_isolation fails [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1209,7 +1209,7 @@ exports['e2e spec_isolation fails [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_hooks_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1272,7 +1272,7 @@ exports['e2e spec_isolation fails [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_passing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",
@@ -1535,7 +1535,7 @@ exports['e2e spec_isolation fails [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1651,7 +1651,7 @@ exports['e2e spec_isolation fails [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1773,7 +1773,7 @@ exports['e2e spec_isolation fails [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_hooks_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -1836,7 +1836,7 @@ exports['e2e spec_isolation fails [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_passing_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",
@@ -2157,7 +2157,7 @@ exports['e2e spec_isolation failing with retries enabled [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -2281,7 +2281,7 @@ exports['e2e spec_isolation failing with retries enabled [electron] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_retrying_spec.js",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",
@@ -2602,7 +2602,7 @@ exports['e2e spec_isolation failing with retries enabled [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -2726,7 +2726,7 @@ exports['e2e spec_isolation failing with retries enabled [chrome] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_retrying_spec.js",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",
@@ -3047,7 +3047,7 @@ exports['e2e spec_isolation failing with retries enabled [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_failing_hook_spec.coffee",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     },
     {
       "stats": {
@@ -3171,7 +3171,7 @@ exports['e2e spec_isolation failing with retries enabled [firefox] 1'] = {
         "absolute": "/foo/bar/.projects/e2e/cypress/integration/simple_retrying_spec.js",
         "specType": "integration"
       },
-      "shouldUploadVideo": true
+      "shouldUploadVideo": false
     }
   ],
   "browserPath": "path/to/browser",

packages/server/__snapshots__/non_root_read_only_fs_spec.ts.js

@@ -24,11 +24,6 @@ If you don't require screenshots or videos to be stored you can safely ignore th
 ────────────────────────────────────────────────────────────────────────────────────────────────────
 
   Running:  spec.js                                                                         (1 of 1)
-Warning: We failed to record the video.
-
-This error will not alter the exit code.
-
-Error: EACCES: permission denied, mkdir '/foo/bar/.projects/read-only-project-root/cypress/videos'
 
 
   1) fails
@@ -53,19 +48,11 @@ Error: EACCES: permission denied, mkdir '/foo/bar/.projects/read-only-project-ro
   │ Pending:      0                                                                                │
   │ Skipped:      0                                                                                │
   │ Screenshots:  0                                                                                │
-  │ Video:        true                                                                             │
+  │ Video:        false                                                                            │
   │ Duration:     X seconds                                                                        │
   │ Spec Ran:     spec.js                                                                          │
   └────────────────────────────────────────────────────────────────────────────────────────────────┘
 
-Warning: We failed processing this video.
-
-This error will not alter the exit code.
-
-Error: ffmpeg exited with code 1: /foo/bar/.projects/read-only-project-root/cypress/videos/spec.js.mp4: No such file or directory
-
-      [stack trace lines]
-
 
 ====================================================================================================
 

packages/server/lib/errors.js

@@ -111,6 +111,13 @@ const getMsgByType = function (type, arg1 = {}, arg2, arg3) {
         This error will not alter the exit code.
 
         ${arg1}`
+    case 'VIDEO_DOESNT_EXIST':
+      return stripIndent`\
+        Warning: We could not find the video at the following path, so we were unable to process it.
+
+        Video path: ${arg1}
+
+        This error will not alter the exit code.`
     case 'CHROME_WEB_SECURITY_NOT_SUPPORTED':
       return stripIndent`\
         Your project has set the configuration option: \`chromeWebSecurity: false\`

packages/server/lib/experiments.ts

@@ -53,7 +53,7 @@ interface StringValues {
 const _summaries: StringValues = {
   experimentalComponentTesting: 'Framework-specific component testing, uses `componentFolder` to load component specs.',
   experimentalFetchPolyfill: 'Polyfills `window.fetch` to enable Network spying and stubbing.',
-  experimentalRunEvents: 'Allows listening to the `before:spec` and `after:spec` events in the plugins file.',
+  experimentalRunEvents: 'Allows listening to the `before:run`, `before:spec`, and `after:spec` events in the plugins file.',
   experimentalSourceRewriting: 'Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm.',
 }