Fix oppia#21633: Added screenshot feature for failed acceptance tests (oppia#22043)

* Acceptance Tests, Screenshot feature added

* Added the custom-jest-environment file to root files config

* Fixed Screenshot capturing on the retry attempt

* Fixed comments

* Fixed lints

* Resolve comments: added failure terms

* resolve comment: fixed the function name

* fix path in test-constant file

* Resolve comments: removed close browser object

* fix CI failure

Author: omgupta-iitk

.github/workflows/full_stack_tests.yml

@@ -163,6 +163,12 @@ jobs:
           xvfb-run -a --server-args="-screen 0, 1285x1000x24" 
           python -m scripts.run_acceptance_tests 
           --skip-build --suite=${{ matrix.suite.name }} --prod_env
+      - name: Upload desktop test failure screenshots as artifacts
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-acceptance-test-failure-screenshot-${{steps.generate_suite_name_for_artifacts.outputs.MODIFIED_SUITE_NAME}}
+          path: /home/runner/work/oppia/oppia_full_stack_test_failure_screenshots/acceptance
       - name: Run Desktop Acceptance Test ${{ matrix.suite.name }} (Attempt 2 with screen recording)
         if: ${{ failure() }}
         run: >
@@ -184,6 +190,12 @@ jobs:
           path: /home/runner/work/oppia/oppia/core/tests/test-modules-mappings/acceptance/${{ steps.generate_suite_name_for_artifacts.outputs.MODIFIED_SUITE_NAME }}.txt
       - name: Run Mobile Acceptance Test ${{ matrix.suite.name }}
         run: xvfb-run -a --server-args="-screen 0, 1285x1000x24" python -m scripts.run_acceptance_tests --skip-build --suite=${{ matrix.suite.name }} --prod_env --mobile
+      - name: Upload mobile test failure screenshots as artifacts
+        if: ${{ failure() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: desktop-acceptance-test-failure-screenshot-${{steps.generate_suite_name_for_artifacts.outputs.MODIFIED_SUITE_NAME}}
+          path: /home/runner/work/oppia/oppia_full_stack_test_failure_screenshots/acceptance
       - name: Run Mobile Acceptance Test ${{ matrix.suite.name }} (Attempt 2 with screen recording)
         if: ${{ failure() }}
         # We use xvfb-run to create a virtual screen to run tests without headless mode.

core/tests/puppeteer-acceptance-tests/custom-jest-environment.js

@@ -0,0 +1,41 @@
+// Copyright 2025 The Oppia Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS-IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @fileoverview Custom Jest environment for enhanced test failure handling.
+ *
+ * This custom Jest environment extends NodeEnvironment to detect test failures
+ * in real-time and trigger actions like capturing screenshots for debugging.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {showMessage} = require('./utilities/common/show-message');
+const NodeEnvironment = require('jest-environment-node');
+
+const CONFIG_FILE = path.resolve(__dirname, 'jest-runtime-config.json');
+
+class CustomJestEnvironment extends NodeEnvironment {
+  async handleTestEvent(event) {
+    if (event.name === 'test_done' && event.test.errors.length > 0) {
+      showMessage('Test failed: Capturing screenshots...');
+      fs.writeFileSync(
+        CONFIG_FILE,
+        JSON.stringify({testFailureDetected: true})
+      );
+    }
+  }
+}
+
+module.exports = CustomJestEnvironment;

core/tests/puppeteer-acceptance-tests/jest.config.js

@@ -25,7 +25,7 @@ module.exports = {
   testMatch: ['**/?(*.)+(spec).[t]s'],
   transform: {'^.+\\.ts?$': 'ts-jest'},
   preset: 'ts-jest',
-  testEnvironment: 'node',
+  testEnvironment: './custom-jest-environment.js',
   testTimeout: 300000,
   bail: 0,
   transformIgnorePatterns: ['node_modules/(?!expect/)'],

core/tests/puppeteer-acceptance-tests/utilities/common/puppeteer-utils.ts

@@ -71,8 +71,11 @@ export class BaseUser {
   username: string = '';
   startTimeInMilliseconds: number = -1;
   screenRecorder!: PuppeteerScreenRecorder;
+  static instances: BaseUser[] = []; // Track instances.
 
-  constructor() {}
+  constructor() {
+    BaseUser.instances.push(this);
+  }
 
   /**
    * This is a function that opens a new browser instance for the user.
@@ -202,6 +205,33 @@ export class BaseUser {
     return this.page;
   }
 
+  /**
+   * This function takes the screenshot of all the instances of browser during a test failure.
+   */
+  async captureScreenshotsForFailedTest(): Promise<void> {
+    let i: number = 0;
+    const specName = process.env.SPEC_NAME;
+    const outputDir = testConstants.TEST_SCREENSHOT_DIR;
+    const outputFileName = `${specName}-${new Date().toISOString()}`.replace(
+      /[^a-z0-9.-]/gi,
+      '_'
+    );
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, {recursive: true});
+    }
+    for (const instance of BaseUser.instances) {
+      if (instance.page) {
+        await instance.page.screenshot({
+          path: path.join(outputDir, outputFileName + `-instance-${i}.png`),
+        });
+        showMessage(
+          `Screenshot captured for test failure and saved as : ${path.join(outputDir, outputFileName + `-instance-${i}.png`)}`
+        );
+        i = i + 1;
+      }
+    }
+  }
+
   /**
    * Checks if the application is in production mode.
    * @returns {Promise<boolean>} Returns true if the application is in development mode,
@@ -514,6 +544,21 @@ export class BaseUser {
     if (this.screenRecorder) {
       await this.screenRecorder.stop();
     }
+    const CONFIG_FILE = path.resolve(
+      __dirname,
+      '../../jest-runtime-config.json'
+    );
+    if (
+      fs.existsSync(CONFIG_FILE) &&
+      !(process.env.VIDEO_RECORDING_IS_ENABLED === '1')
+    ) {
+      const configData = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+      if (configData.testFailureDetected) {
+        fs.unlinkSync(CONFIG_FILE);
+        // Signal all BaseUser instances to take screenshots.
+        await this.captureScreenshotsForFailedTest();
+      }
+    }
     await this.browserObject.close();
   }
 

core/tests/puppeteer-acceptance-tests/utilities/common/test-constants.ts

@@ -243,4 +243,7 @@ export default {
   TEST_VIDEO_DIR: path.resolve(
     '../oppia_full_stack_test_video_recordings/acceptance'
   ),
+  TEST_SCREENSHOT_DIR: path.resolve(
+    '../oppia_full_stack_test_failure_screenshots/acceptance'
+  ),
 };

core/tests/root-files-config.json

@@ -60,6 +60,7 @@
     "core/templates/domain/skill/MisconceptionObjectFactorySpec.ts",
     "core/templates/domain/exploration/AnswerGroupObjectFactorySpec.ts",
     "core/tests/puppeteer-acceptance-tests/jest.config.js",
+    "core/tests/puppeteer-acceptance-tests/custom-jest-environment.js",
     "core/tests/puppeteer-acceptance-tests/specs/exploration-editor/manage-exploration-misconceptions.spec.ts"
   ],
   "RUN_ALL_TESTS_ROOT_FILES": [

scripts/clean.py

@@ -25,6 +25,8 @@
 OPPIA_TOOLS_DIR = os.path.join(CURR_DIR, '..', 'oppia_tools')
 FULL_STACK_TEST_VIDEO_RECORDING_DIR = os.path.join(
     CURR_DIR, '..', 'oppia_full_stack_test_video_recordings')
+FULL_STACK_TEST_SCREENSHOT_DIR = os.path.join(
+    CURR_DIR, '..', 'oppia_full_stack_test_screenshots')
 
 _PARSER = argparse.ArgumentParser(
     description="""
@@ -61,6 +63,7 @@ def main(args: Optional[Sequence[str]] = None) -> None:
 
     delete_directory_tree(OPPIA_TOOLS_DIR)
     delete_directory_tree(FULL_STACK_TEST_VIDEO_RECORDING_DIR)
+    delete_directory_tree(FULL_STACK_TEST_SCREENSHOT_DIR)
     delete_directory_tree('node_modules/')
     delete_directory_tree('third_party/')
     delete_directory_tree('build/')

scripts/clean_test.py

@@ -109,7 +109,7 @@ def test_function_calls(self) -> None:
             'delete_file_is_called': 0
         }
         expected_check_function_calls = {
-            'delete_directory_tree_is_called': 10,
+            'delete_directory_tree_is_called': 11,
             'delete_file_is_called': 4
         }
         def mock_delete_dir(unused_path: str) -> None: