feat: video recordings (#24)

Author: noomorph

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Wix Incubator
+Copyright (c) 2025 Wix Incubator
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -49,6 +49,7 @@ module.exports = {
           useSteps: true,
           deviceLogs: true,
           deviceScreenshots: true,
+          deviceVideos: true,
         }],
       ],
     },
@@ -62,6 +63,89 @@ Here's a brief explanation of what you just added:
 
 - `testEnvironmentOptions` section: We added three event listener modules that will run during our tests — `jest-metadata`, `jest-allure2-reporter`, and `detox-allure2-adapter`. These listeners will collect necessary metadata and feed test result data to our Allure reports.
 
+## Adapter Options
+
+### `useSteps: boolean`
+
+If set to true, the adapter will wrap all Detox device interactions (like `device.launchApp()`, `element(by.id('loginButton')).tap()`) into Allure steps. This provides a detailed, step-by-step report of your test execution.
+
+### `deviceLogs: boolean | DetoxAllure2AdapterDeviceLogsOptions`
+
+Enables capturing device (iOS/Android) logs for each step. This feature uses the [`logkitten`](https://www.npmjs.com/package/logkitten) library.
+
+**Configuration:**
+
+- **`true`**: Enables log capture with default settings.
+- **`false`** (default): Disables log capture.
+- **`DetoxAllure2AdapterDeviceLogsOptions`** (object): Enables log capture and provides fine-grained control over the settings.
+
+  - `ios: (entry: IosEntry) => boolean`: Filter function for iOS logs. Return `true` to include the log entry.
+  - `android: (entry: AndroidEntry) => boolean`: Filter function for Android logs. Return `true` to include the log entry.
+  - `override: boolean`: Whether to override existing log handlers.
+  - `saveAll: boolean` (default: `false`): If `true`, saves logs for all steps. By default, only logs for failed steps are kept.
+  - `syncDelay: number | { ios?: number; android?: number }` (default: `500`): Synchronization delay in milliseconds for log collection. Set to `0` to disable, or provide per-platform delays.
+
+### `deviceScreenshots: boolean | DetoxAllure2AdapterDeviceScreenshotOptions`
+
+Enables taking screenshots for each step. This feature uses the [`screenkitten`](https://www.npmjs.com/package/screenkitten) library.
+
+**Configuration:**
+
+- **`true`**: Enables screenshot capture with default settings.
+- **`false`** (default): Disables screenshot capture.
+- **`DetoxAllure2AdapterDeviceScreenshotOptions`** (object): Enables screenshot capture and provides fine-grained control over the settings.
+
+  - `saveAll: boolean` (default: `false`): If `true`, saves screenshots for all steps. By default, only screenshots for failed steps are kept.
+
+### `deviceVideos: boolean | DetoxAllure2AdapterDeviceVideoOptions`
+
+Enables "on-demand" video recording for your tests. This feature uses the [`videokitten`](https://www.npmjs.com/package/videokitten) library.
+The recording starts automatically upon the first interaction with the device and stops when the test is complete.
+
+**Configuration:**
+
+- **`true`**: Enables video recording with default settings.
+- **`false`** (default): Disables video recording.
+- **`DetoxAllure2AdapterDeviceVideoOptions`** (object): Enables recording and provides fine-grained control over the settings.
+
+  - `saveAll: boolean` (default: `false`): If `true`, saves videos for all tests. By default, only videos for failed tests are kept.
+  - `ios: Partial<VideokittenOptionsIOS>`: Custom options for iOS, as defined by `videokitten`.
+  - `android: Partial<VideokittenOptionsAndroid>`: Custom options for Android, as defined by `videokitten`.
+
+**Example with custom options:**
+
+```js
+// jest.config.js
+module.exports = {
+  eventListeners: [
+    'jest-metadata/environment-listener',
+    'jest-allure2-reporter/environment-listener',
+    ['detox-allure2-adapter', {
+      useSteps: true,
+      deviceLogs: {
+        saveAll: true,
+        ios: (entry) => entry.level === 'error',
+        android: (entry) => entry.priority === 'E',
+      },
+      deviceScreenshots: {
+        saveAll: true,
+      },
+      deviceVideos: {
+        saveAll: true,
+        ios: {
+          codec: 'hevc',
+        },
+        android: {
+          bitRate: 4_000_000,
+        }
+      }
+    }],
+  ],
+},
+```
+
+Refer to the [`videokitten` documentation](https://www.npmjs.com/package/videokitten) for a full list of options for each platform.
+
 ## Running Tests
 
 After making these changes, you can run your tests as usual. The tests will run with Detox and Jest, and the results will be reported using Allure. Configure your `npm test` script in the `package.json` file to run your Detox tests.

package-e2e/test.ts

@@ -1,7 +1,12 @@
 import type { ReporterOptions } from 'jest-allure2-reporter';
 
 import listener from 'detox-allure2-adapter';
-import type { DetoxAllure2AdapterOptions, DetoxAllure2AdapterDeviceLogsOptions, DetoxAllure2AdapterDeviceScreenshotOptions } from 'detox-allure2-adapter';
+import type {
+  DetoxAllure2AdapterOptions,
+  DetoxAllure2AdapterDeviceLogsOptions,
+  DetoxAllure2AdapterDeviceScreenshotOptions,
+  DetoxAllure2AdapterDeviceVideoOptions,
+} from 'detox-allure2-adapter';
 import DetoxAllurePathBuilder from 'detox-allure2-adapter/path-builder';
 import presetAllure from 'detox-allure2-adapter/preset-allure';
 import presetDetox from 'detox-allure2-adapter/preset-detox';
@@ -21,6 +26,7 @@ assertType<DetoxAllure2AdapterOptions>({
   useSteps: true,
   deviceLogs: true,
   deviceScreenshots: true,
+  deviceVideos: true,
 });
 
 assertType<DetoxAllure2AdapterDeviceLogsOptions>({
@@ -38,3 +44,15 @@ assertType<DetoxAllure2AdapterDeviceLogsOptions>({
 assertType<DetoxAllure2AdapterDeviceScreenshotOptions>({
   saveAll: true,
 });
+
+assertType<DetoxAllure2AdapterDeviceVideoOptions>({
+  saveAll: true,
+  ios: {
+    codec: 'hevc',
+  },
+  android: {
+    recording: {
+      bitRate: 4_000_000,
+    },
+  },
+});

package.json

@@ -109,6 +109,7 @@
   "dependencies": {
     "archiver": "^6.0.1",
     "logkitten": "^1.3.0",
-    "screenkitten": "^1.0.0"
+    "screenkitten": "^1.0.0",
+    "videokitten": "^1.0.1"
   }
 }

src/index.ts

@@ -2,6 +2,7 @@ export type {
   DetoxAllure2AdapterOptions,
   DetoxAllure2AdapterDeviceLogsOptions,
   DetoxAllure2AdapterDeviceScreenshotOptions,
+  DetoxAllure2AdapterDeviceVideoOptions,
 } from './types';
 
 export { listener as default } from './listener';

src/listener.ts

@@ -15,24 +15,38 @@ import { LogBuffer } from './logs';
 import { ScreenshotHelper } from './screenshots';
 import { wrapWithSteps } from './steps';
 import type { DetoxAllure2AdapterOptions } from './types';
-import { DeviceWrapper, WorkerWrapper } from './utils';
+import { DeviceWrapper, WorkerWrapper, once } from './utils';
+import { VideoManager } from './video';
 
 export const listener: EnvironmentListenerFn = (
   { testEvents },
   {
     useSteps = false,
     deviceLogs = false,
     deviceScreenshots = false,
+    deviceVideos = false,
     onError,
   }: DetoxAllure2AdapterOptions = {},
 ) => {
   let logHandler: ReturnType<typeof createLogHandler>;
   let zipHandler: ReturnType<typeof createZipHandler>;
   let inferMimeType: MIMEInferer;
-  let $test: ReturnType<typeof allure.$bind> | undefined;
-  let artifactsManager: any;
+  let workerWrapper: WorkerWrapper | undefined;
   let logs: LogBuffer | undefined;
   let screenshots: ScreenshotHelper | undefined;
+  let videoManager: VideoManager | undefined;
+
+  let $test: ReturnType<typeof allure.$bind> | undefined;
+  let $hook: ReturnType<typeof allure.$bind> | undefined;
+  let failing = false;
+
+  const flushArtifacts = once(async () => {
+    await workerWrapper?.artifactsManager?._idlePromise;
+    await Promise.all([logs?.close(), videoManager?.stopAndAttach($hook, failing)]);
+    workerWrapper = undefined;
+    logs = undefined;
+    videoManager = undefined;
+  });
 
   testEvents
     .on('setup', () => {
@@ -42,7 +56,7 @@ export const listener: EnvironmentListenerFn = (
         inferMimeType = context.inferMimeType;
       });
 
-      const workerWrapper = new WorkerWrapper(worker);
+      workerWrapper = new WorkerWrapper(worker);
       workerWrapper.artifactsManager.on('trackArtifact', onTrackArtifact);
 
       const device = new DeviceWrapper(detox.device);
@@ -65,43 +79,60 @@ export const listener: EnvironmentListenerFn = (
           onError,
         });
       }
+
+      if (deviceVideos) {
+        const baseOptions = deviceVideos === true ? {} : deviceVideos;
+        const effectiveOptions = useSteps ? baseOptions : { ...baseOptions, lazyStart: false };
+        videoManager = new VideoManager({ device, options: effectiveOptions });
+      }
     })
     .on('setup', async () => {
       if (useSteps) {
-        wrapWithSteps({ detox, worker, allure, logs, screenshots });
+        wrapWithSteps({ detox, worker, allure, logs, screenshots, videoManager });
       }
     })
-    .on('test_start', () => {
+    .on('run_start', async () => {
+      // Only start early if configured (lazyStart === false)
+      await videoManager?.ensureRecordingEager();
+    })
+    .on('test_started', async () => {
+      // Start recording eagerly if configured or when not using step wrappers
+      await videoManager?.ensureRecordingEager();
+    })
+    .on('test_start', async () => {
       $test = allure.$bind();
+      $hook = undefined;
       logs?.attachBefore(allure);
+      failing = false;
     })
-    .on('hook_start', () => {
+    .on('hook_start', async ({ event }) => {
       logs?.attachBefore(allure);
+
+      if (event.hook.type === 'beforeAll' || event.hook.type === 'afterAll') {
+        $hook ??= allure.$bind();
+        await videoManager?.ensureRecordingEager();
+      }
     })
     .on('hook_failure', async () => {
+      failing = true;
       await Promise.all([logs?.attachAfterFailure(allure), screenshots?.attachFailure(allure)]);
     })
     .on('hook_success', async () => {
       await Promise.all([logs?.attachAfterSuccess(allure), screenshots?.attachSuccess(allure)]);
     })
     .on('test_fn_failure', async () => {
+      failing = true;
       await Promise.all([logs?.attachAfterFailure(allure), screenshots?.attachFailure(allure)]);
     })
     .on('test_fn_success', async () => {
       await Promise.all([logs?.attachAfterSuccess(allure), screenshots?.attachSuccess(allure)]);
     })
     .on('test_done', async () => {
+      await videoManager?.stopAndAttach($test, failing);
       $test = undefined;
     })
-    .on('teardown', flushArtifacts, -1)
-    .on('test_environment_teardown', flushArtifacts, -1);
-
-  async function flushArtifacts() {
-    await artifactsManager?._idlePromise;
-    await logs?.close();
-    artifactsManager = undefined;
-    logs = undefined;
-  }
+    .once('teardown', flushArtifacts, -1)
+    .once('test_environment_teardown', flushArtifacts, -1);
 
   function onTrackArtifact(artifact: any) {
     const $step = allure.$bind();

src/steps/wrapWithSteps.ts

@@ -2,6 +2,7 @@
 import type { AllureRuntime } from 'jest-allure2-reporter/api';
 import { type StepLogRecorder } from '../logs';
 import { type ScreenshotHelper } from '../screenshots';
+import { type VideoManager } from '../video';
 import { androidDescriptionMaker, iosDescriptionMaker } from './description-maker';
 import type { StepDescriptionMaker } from './description-maker';
 
@@ -11,10 +12,11 @@ export interface WrapWithStepsOptions {
   allure: AllureRuntime;
   logs?: StepLogRecorder;
   screenshots?: ScreenshotHelper;
+  videoManager?: VideoManager;
 }
 
 export function wrapWithSteps(options: WrapWithStepsOptions) {
-  const { detox, worker, allure, logs, screenshots } = options;
+  const { detox, worker, allure, logs, screenshots, videoManager } = options;
   const { device } = detox;
   const platform = device.getPlatform();
 
@@ -57,6 +59,7 @@ export function wrapWithSteps(options: WrapWithStepsOptions) {
         ? allure.step(desc.message, async () => {
             if (desc.args) allure.parameters(desc.args);
             logs?.attachBefore(allure);
+            await videoManager?.ensureRecording();
 
             try {
               const result = await send(...args);
@@ -84,7 +87,7 @@ function initDescriptionMaker(platform: string): StepDescriptionMaker | undefine
 }
 
 function wrapDeviceMethod(
-  { detox, allure, logs, screenshots }: WrapWithStepsOptions,
+  { detox, allure, logs, screenshots, videoManager }: WrapWithStepsOptions,
   methodName: string,
   stepDescription: string,
 ) {
@@ -93,6 +96,8 @@ function wrapDeviceMethod(
   if (typeof originalMethod !== 'function') return;
 
   device[methodName] = async (...args: any[]) => {
+    await videoManager?.ensureRecording();
+
     return await allure.step(stepDescription, async () => {
       try {
         logs?.attachBefore(allure);

src/types.ts

@@ -1,4 +1,5 @@
 import type { AndroidEntry, IosEntry } from 'logkitten';
+import type { VideokittenOptionsIOS, VideokittenOptionsAndroid } from 'videokitten';
 
 export type DetoxAllure2AdapterOptions = {
   /**
@@ -14,6 +15,10 @@ export type DetoxAllure2AdapterOptions = {
    * Device screenshots configuration for per-step logging
    */
   deviceScreenshots?: boolean | DetoxAllure2AdapterDeviceScreenshotOptions;
+  /**
+   * Device video recording for failed tests
+   */
+  deviceVideos?: boolean | DetoxAllure2AdapterDeviceVideoOptions;
   /**
    * Callback to handle errors
    */
@@ -33,5 +38,28 @@ export interface DetoxAllure2AdapterDeviceLogsOptions {
 }
 
 export interface DetoxAllure2AdapterDeviceScreenshotOptions {
+  /**
+   * Whether to save all screenshots
+   * @default false
+   */
   saveAll?: boolean;
 }
+
+export interface DetoxAllure2AdapterDeviceVideoOptions {
+  /**
+   * Whether to save all videos
+   * @default false
+   */
+  saveAll?: boolean;
+  /**
+   * Controls when video recording starts.
+   * - If `true` (default), recording begins lazily on the first device interaction (step).
+   * - If `false`, recording starts immediately at the beginning of each test.
+   *
+   * This option is only effective when `useSteps` is enabled.
+   * @default true
+   */
+  lazyStart?: boolean;
+  ios?: Partial<VideokittenOptionsIOS>;
+  android?: Partial<VideokittenOptionsAndroid>;
+}

src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './deferred';
 export * from './device-wrapper';
+export * from './once';
 export * from './worker-wrapper';

src/utils/once.ts

@@ -0,0 +1,14 @@
+export function once<T>(fn: () => T): () => T {
+  let result: T | undefined;
+  let called = false;
+
+  return () => {
+    if (called) {
+      return result!;
+    }
+
+    called = true;
+    result = fn();
+    return result;
+  };
+}