feat: Merge videos generated by playwright into a single mp4 (#53)

* Generate a combined video

* Encapsulate video syncing

* Module org

* timestamp needs to be in seconds

* Better support case where there are sparse videos

That is, not every test case generated a video

* Better naming, maybe?

* Update eslint config to ignore `_` prefixed args

Matches default exemptions of ts compiler.

* Update local dev instructions

* Linting

* Check for merged video in integration test

* Improve error messaging for video conversion

* Setup ffmpeg for video conversion testing

* lint

* Fix readme table

* Emphasize ffmpeg requirement

* Better optional arg

* Apply suggestions from code review

Co-authored-by: Alex Plischke <[email protected]>

* Use Milliseconds type alias more broadly

* Improve error handling

Cleanup tmp dir

* Use Result pattern and let the caller handle logging errors

* lint

* More specific naming

---------

Co-authored-by: Alex Plischke <[email protected]>

Author: mhan83

.github/workflows/test.yml

@@ -36,6 +36,9 @@ jobs:
           node-version-file: ".nvmrc"
           cache: "npm"
 
+      - name: Setup ffmpeg
+        uses: FedericoCarboni/setup-ffmpeg@v3
+
       - name: Install Dependencies
         run: npm ci
 

README.md

@@ -63,6 +63,7 @@ const config = {
 | `region`     | Sets the region. <br> Default: `us-west-1`                                                       | `us-west-1` \| `eu-central-1`  |
 | `upload`     | Whether to upload report and assets to Sauce Labs. <br> Default: `true`                          | `boolean`                      |
 | `outputFile` | The local path to write the Sauce test report. Can be set in env var `SAUCE_REPORT_OUTPUT_NAME`. | `string`                       |
+| `mergeVideos` | Whether to merge all video files generated by Playwright. This is useful when used with the `upload` option to upload the test report to Sauce Labs since it will allow you to view the merged video in the Sauce Labs Test Results page. **Requires ffmpeg to be installed.**<br> Default: `false` | `boolean` |
 
 ## Limitations
 
@@ -72,11 +73,24 @@ Some limitations apply to `@saucelabs/playwright-reporter`:
 
 ## Development
 
+### Running integration tests
+
+There are tests included in `tests/integration` where the reporter is referenced
+directly.
+
+```sh
+$ npm run build
+$ cd tests/integration
+$ npx playwright test
+```
+
 ### Running Locally
 
-To test the reporter locally, link it to itself and then run a test with the reporter set.
+If you have playwright tests outside of the repo, you can link and install the
+reporter to run in your external repo.
 
 ```sh
+$ npm run build
 $ npm link
 $ npm link @saucelabs/playwright-reporter
 $ npx playwright test --reporter=@saucelabs/playwright-reporter

eslint.config.js

@@ -15,6 +15,18 @@ module.exports = ts.config(
     rules: {
       '@typescript-eslint/no-var-requires': 'off',
       '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          args: 'all',
+          argsIgnorePattern: '^_',
+          caughtErrors: 'all',
+          caughtErrorsIgnorePattern: '^_',
+          destructuredArrayIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          ignoreRestSiblings: true,
+        },
+      ],
     },
   },
   {

src/reporter.ts

@@ -24,6 +24,7 @@ import {
   TestRunRequestBody,
 } from './api';
 import { CI, IS_CI } from './ci';
+import { Syncer, MergeSyncer, OffsetSyncer } from './video';
 
 export interface Config {
   buildName?: string;
@@ -33,6 +34,7 @@ export interface Config {
   outputFile?: string;
   upload?: boolean;
   webAssetsDir: string;
+  mergeVideos?: boolean;
 }
 
 // Types of attachments relevant for UI display.
@@ -58,6 +60,7 @@ export default class SauceReporter implements Reporter {
   region: Region;
   outputFile?: string;
   shouldUpload: boolean;
+  mergeVideos: boolean;
   /*
    * When webAssetsDir is set, this reporter syncs web UI-related attachments
    * from the Playwright output directory to the specified web assets directory.
@@ -88,8 +91,6 @@ export default class SauceReporter implements Reporter {
   startedAt?: Date;
   endedAt?: Date;
 
-  videoStartTime?: number;
-
   constructor(reporterConfig: Config) {
     this.projects = {};
 
@@ -99,6 +100,7 @@ export default class SauceReporter implements Reporter {
     this.outputFile =
       reporterConfig?.outputFile || process.env.SAUCE_REPORT_OUTPUT_NAME;
     this.shouldUpload = reporterConfig?.upload !== false;
+    this.mergeVideos = reporterConfig?.mergeVideos === true;
 
     this.webAssetsDir =
       reporterConfig.webAssetsDir || process.env.SAUCE_WEB_ASSETS_DIR;
@@ -112,7 +114,7 @@ export default class SauceReporter implements Reporter {
         fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'),
       );
       reporterVersion = packageData.version;
-    } catch (e) {
+    } catch (_e) {
       /* empty */
     }
 
@@ -138,12 +140,6 @@ export default class SauceReporter implements Reporter {
     }
 
     this.playwrightVersion = 'unknown';
-
-    if (process.env.SAUCE_VIDEO_START_TIME) {
-      this.videoStartTime = new Date(
-        process.env.SAUCE_VIDEO_START_TIME,
-      ).getTime();
-    }
   }
 
   onBegin(config: FullConfig, suite: PlaywrightSuite) {
@@ -170,7 +166,7 @@ export default class SauceReporter implements Reporter {
     const jobUrls = [];
     const suites = [];
     for await (const projectSuite of this.rootSuite.suites) {
-      const { report, assets } = this.createSauceReport(projectSuite);
+      const { report, assets } = await this.createSauceReport(projectSuite);
 
       const result = await this.reportToSauce(projectSuite, report, assets);
 
@@ -365,7 +361,7 @@ export default class SauceReporter implements Reporter {
     return str.replace(ansiRegex, '');
   }
 
-  constructSauceSuite(rootSuite: PlaywrightSuite) {
+  constructSauceSuite(rootSuite: PlaywrightSuite, videoSyncer?: Syncer) {
     const suite = new SauceSuite(rootSuite.title);
     const assets: Asset[] = [];
 
@@ -407,10 +403,6 @@ export default class SauceReporter implements Reporter {
         startTime: lastResult.startTime,
         code: new TestCode(lines),
       });
-      if (this.videoStartTime) {
-        test.videoTimestamp =
-          (lastResult.startTime.getTime() - this.videoStartTime) / 1000;
-      }
       if (testCase.id) {
         test.metadata = {
           id: testCase.id,
@@ -445,12 +437,25 @@ export default class SauceReporter implements Reporter {
           });
         }
       }
+
+      if (videoSyncer) {
+        const videoAttachment = lastResult.attachments.find((a) =>
+          a.contentType.includes('video'),
+        );
+        videoSyncer.sync(test, {
+          path: videoAttachment?.path,
+          duration: test.duration,
+        });
+      }
     }
 
     for (const subSuite of rootSuite.suites) {
-      const { suite: s, assets: a } = this.constructSauceSuite(subSuite);
-      suite.addSuite(s);
+      const { suite: s, assets: a } = this.constructSauceSuite(
+        subSuite,
+        videoSyncer,
+      );
 
+      suite.addSuite(s);
       assets.push(...a);
     }
 
@@ -467,8 +472,32 @@ ${err.stack}
     `;
   }
 
-  createSauceReport(rootSuite: PlaywrightSuite) {
-    const { suite: sauceSuite, assets } = this.constructSauceSuite(rootSuite);
+  async createSauceReport(rootSuite: PlaywrightSuite) {
+    let syncer: Syncer | undefined;
+    if (process.env.SAUCE_VIDEO_START_TIME) {
+      const offset = new Date(process.env.SAUCE_VIDEO_START_TIME).getTime();
+      syncer = new OffsetSyncer(offset);
+    } else if (this.mergeVideos) {
+      syncer = new MergeSyncer();
+    }
+
+    const { suite: sauceSuite, assets } = this.constructSauceSuite(
+      rootSuite,
+      syncer,
+    );
+
+    if (syncer instanceof MergeSyncer) {
+      const { kind, value } = await syncer.mergeVideos();
+      if (kind === 'ok') {
+        assets.push({
+          filename: 'video.mp4',
+          path: value,
+          data: fs.createReadStream(value),
+        });
+      } else if (kind === 'err') {
+        console.error('Failed to merge video:', value.message);
+      }
+    }
 
     const report = new TestRun();
     report.addSuite(sauceSuite);

src/video/index.ts

@@ -0,0 +1,3 @@
+export { Syncer } from './sync/types';
+export { MergeSyncer } from './sync/merge';
+export { OffsetSyncer } from './sync/offset';

src/video/sync/merge.ts

@@ -0,0 +1,110 @@
+import child_process from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { Test } from '@saucelabs/sauce-json-reporter';
+
+import { Milliseconds, Syncer, VideoFile } from './types';
+
+const exec = promisify(child_process.exec);
+
+type MergeResult<T, E> =
+  | { kind: 'ok'; value: T }
+  | { kind: 'noop'; value: null }
+  | { kind: 'err'; value: E };
+
+/**
+ * MergeSyncer is used to synchronize the video start time of a test case with
+ * a collection of video files. Videos are aggregated and their cumulative
+ * runtime is used to mark the video start time of the next test case to be
+ * added.
+ */
+export class MergeSyncer implements Syncer {
+  duration: Milliseconds;
+  videoFiles: VideoFile[];
+
+  constructor() {
+    this.duration = 0;
+    this.videoFiles = [];
+  }
+
+  public sync(test: Test, video: VideoFile): void {
+    if (video.path && video.duration) {
+      test.videoTimestamp = this.duration / 1000;
+
+      this.videoFiles.push({ ...video });
+      this.duration += video.duration;
+    }
+  }
+
+  public async mergeVideos(): Promise<MergeResult<string, Error>> {
+    if (this.videoFiles.length === 0) {
+      return { kind: 'noop', value: null };
+    }
+
+    const hasFFMpeg =
+      child_process.spawnSync('ffmpeg', ['-version']).status === 0;
+    if (!hasFFMpeg) {
+      const e = new Error(
+        'ffmpeg could not be found. Ensure ffmpeg is available in your PATH',
+      );
+      return { kind: 'err', value: e };
+    }
+
+    let tmpDir: string;
+    try {
+      tmpDir = await mkdtemp(join(tmpdir(), 'pw-sauce-video-'));
+      process.on('exit', () => {
+        // NOTE: exit handler must be synchronous
+        rmSync(tmpDir, { recursive: true, force: true });
+      });
+    } catch (e) {
+      const error = e as Error;
+      return { kind: 'err', value: error };
+    }
+
+    const inputFile = join(tmpDir, 'videos.txt');
+    const outputFile = join(tmpDir, 'video.mp4');
+
+    try {
+      await writeFile(
+        inputFile,
+        this.videoFiles.map((v) => `file '${v.path}'`).join('\n'),
+      );
+    } catch (e) {
+      return { kind: 'err', value: e as Error };
+    }
+
+    const args = [
+      '-f',
+      'concat',
+      '-safe',
+      '0',
+      '-threads',
+      '1',
+      '-y',
+      '-i',
+      inputFile,
+      outputFile,
+    ];
+    const cmd = ['ffmpeg', ...args].join(' ');
+    try {
+      await exec(cmd);
+    } catch (e) {
+      const error = e as Error;
+      let msg = `ffmpeg command: ${cmd}`;
+      if ('stdout' in error) {
+        msg = `${msg}\nstdout: ${error.stdout}`;
+      }
+      if ('stderr' in error) {
+        msg = `${msg}\nstderr: ${error.stderr}`;
+      }
+      return { kind: 'err', value: new Error(msg) };
+    }
+
+    return { kind: 'ok', value: outputFile };
+  }
+}

src/video/sync/offset.ts

@@ -0,0 +1,18 @@
+import { Test } from '@saucelabs/sauce-json-reporter';
+import { Milliseconds, Syncer, VideoFile } from './types';
+
+/**
+ * OffsetSyncer is used to synchronize the video start time of a test case
+ * against a simple offset.
+ */
+export class OffsetSyncer implements Syncer {
+  private videoOffset: Milliseconds;
+
+  constructor(offset: Milliseconds) {
+    this.videoOffset = offset;
+  }
+
+  public sync(test: Test, _video: VideoFile): void {
+    test.videoTimestamp = (test.startTime.getTime() - this.videoOffset) / 1000;
+  }
+}

src/video/sync/types.ts

@@ -0,0 +1,21 @@
+import { Test } from '@saucelabs/sauce-json-reporter';
+
+export type Milliseconds = number;
+
+/**
+ * VideoFile represents a video on disk.
+ */
+export type VideoFile = {
+  /**
+   * The path to the video on disk.
+   */
+  path?: string;
+  /**
+   * The duration of the video file in milliseconds.
+   */
+  duration?: Milliseconds;
+};
+
+export interface Syncer {
+  sync(test: Test, video: VideoFile): void;
+}

tests/integration/playwright.config.ts

@@ -9,6 +9,7 @@ const config: PlaywrightTestConfig = {
         buildName: 'Playwright Integration Tests',
         tags: ['playwright', 'demo', 'e2e'],
         outputFile: 'sauce-test-report.json',
+        mergeVideos: true,
       },
     ],
     ['line'],

tests/integration/playwright.spec.js

@@ -80,9 +80,7 @@ describe('runs tests on cloud', function () {
     const assets = response.data;
     expect(assets['console.log']).toBe('console.log');
     expect(assets['sauce-test-report.json']).toBe('sauce-test-report.json');
-    expect(Object.keys(assets).some((key) => key.indexOf('video') != -1)).toBe(
-      true,
-    );
+    expect(assets['video']).toBe('video.mp4');
   });
 
   test('job has name/tags correctly set', async function () {