feat: video recordings

Author: noomorph

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.0"
   }
 }

src/index.ts

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

src/listener.ts

@@ -16,13 +16,15 @@ import { ScreenshotHelper } from './screenshots';
 import { wrapWithSteps } from './steps';
 import type { DetoxAllure2AdapterOptions } from './types';
 import { DeviceWrapper, WorkerWrapper } from './utils';
+import { VideoManager } from './video';
 
 export const listener: EnvironmentListenerFn = (
   { testEvents },
   {
     useSteps = false,
     deviceLogs = false,
     deviceScreenshots = false,
+    deviceVideos = false,
     onError,
   }: DetoxAllure2AdapterOptions = {},
 ) => {
@@ -33,6 +35,9 @@ export const listener: EnvironmentListenerFn = (
   let artifactsManager: any;
   let logs: LogBuffer | undefined;
   let screenshots: ScreenshotHelper | undefined;
+  let videoManager: VideoManager | undefined;
+
+  let isFirstTest = true;
 
   testEvents
     .on('setup', () => {
@@ -65,15 +70,30 @@ export const listener: EnvironmentListenerFn = (
           onError,
         });
       }
+
+      if (deviceVideos) {
+        videoManager = VideoManager.getInstance(device, deviceVideos);
+      }
     })
     .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 () => {
+      await videoManager?.ensureRecording(true);
+    })
+    .on('test_start', async () => {
       $test = allure.$bind();
       logs?.attachBefore(allure);
+
+      if (isFirstTest) {
+        isFirstTest = false;
+      } else {
+        await videoManager?.stopAndAttach();
+      }
+
+      videoManager?.setAllureContext($test);
     })
     .on('hook_start', () => {
       logs?.attachBefore(allure);
@@ -90,17 +110,20 @@ export const listener: EnvironmentListenerFn = (
     .on('test_fn_success', async () => {
       await Promise.all([logs?.attachAfterSuccess(allure), screenshots?.attachSuccess(allure)]);
     })
-    .on('test_done', async () => {
+    .on('run_finish', async () => {
+      await videoManager?.stopAndAttach();
+      videoManager?.setAllureContext();
       $test = undefined;
     })
     .on('teardown', flushArtifacts, -1)
     .on('test_environment_teardown', flushArtifacts, -1);
 
   async function flushArtifacts() {
     await artifactsManager?._idlePromise;
-    await logs?.close();
+    await Promise.all([logs?.close(), videoManager?.stopAndAttach()]);
     artifactsManager = undefined;
     logs = undefined;
+    videoManager = undefined;
   }
 
   function onTrackArtifact(artifact: any) {

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,19 @@ 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;
+  ios?: Partial<VideokittenOptionsIOS>;
+  android?: Partial<VideokittenOptionsAndroid>;
 }

src/video/index.ts

@@ -0,0 +1 @@
+export * from './manager';