feat: Introduce the webScreenshotMode setting (#2415)

docs/reference/settings.md

@@ -40,3 +40,4 @@ Along with the common settings, the following driver-specific settings are avail
 | `pageSourceExcludedAttributes` | `string` | One or more comma-separated attribute names to be excluded from the XML output. It might be sometimes helpful to exclude, for example, the `visible` attribute, to significantly speed-up page source retrieval. This does not affect the XML output when `useJSONSource` is enabled. Defaults to an empty string. Example: `"visible,accessible"` |
 | `maxTypingFrequency` | `int` | Maximum frequency of keystrokes for typing and clear. If your tests are failing because of typing errors, you may want to adjust this. Defaults to `60` keystrokes per minute. |
 | `respectSystemAlerts` | `boolean` | Currently we detect the app under test as active if XCTest returns XCUIApplicationStateRunningForeground state for it. In case the app under test is covered by a system alert from the Springboard app this approach might be confusing as we cannot interact with it unless an alert is properly handled. If this setting is set to true (by default it is false) then it forces WDA to verify the presence of alerts shown by Springboard and return the latter while performing the automated app detection. It affects the performance of active app detection, but might be more convenient for writing test scripts (e.g. eliminates the need of proactive switching between system and custom apps). Also, this behavior emulates the legacy active application detection logic before version 6 of the driver. |
+| `webScreenshotMode` | `native` or `page` or `viewport` | Defines the screenshoting logic if the current context is set to a web one. The default value is `native`, which makes the driver to take screenshots from WDA, e.g. the whole device screen including status bars. The `page` mode tries to retrieve the screenshot of the whole active web page, while the `viewport` one only retrieves a shot of the visible viewport. |

lib/commands/screenshots.js

@@ -9,6 +9,27 @@ export default {
    * @returns {Promise<string>}
    */
   async getScreenshot() {
+    if (this.isWebContext()) {
+      const webScreenshotMode = (await this.settings.getSettings()).webScreenshotMode;
+      switch (_.toLower(webScreenshotMode)) {
+        case 'page':
+        case 'viewport':
+          return await this.remote.captureScreenshot({
+            coordinateSystem: _.capitalize(webScreenshotMode),
+          });
+        case 'native':
+        case undefined:
+        case null:
+          break;
+        default:
+          this.log.warn(
+            `The webScreenshotMode setting value '${webScreenshotMode}' is not known. ` +
+            `Supported values are: page, viewport and native. Falling back to the native mode.`
+          );
+          break;
+      }
+    }
+
     const getScreenshotFromWDA = async () => {
       this.log.debug(`Taking screenshot with WDA`);
       const data = await this.proxyCommand('/screenshot', 'GET');

lib/driver.js

@@ -84,6 +84,7 @@ const DEFAULT_SETTINGS = {
   nativeWebTap: false,
   nativeWebTapStrict: false,
   useJSONSource: false,
+  webScreenshotMode: 'native',
   shouldUseCompactResponses: true,
   elementResponseAttributes: 'type,label',
   // Read https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBConfiguration.m for following settings' values
@@ -1119,6 +1120,7 @@ export class XCUITestDriver extends BaseDriver {
           try {
             const device = await getSimulator(this.opts.udid, {
               devicesSetPath: this.opts.simulatorDevicesSetPath,
+              // @ts-ignore This is ok
               logger: this.log,
             });
             return {device, realDevice: false, udid: this.opts.udid};

lib/simulator-management.js

@@ -42,6 +42,7 @@ export async function createSim() {
     platform,
     checkExistence: false,
     devicesSetPath,
+    // @ts-ignore This is ok
     logger: this.log,
   });
 }
@@ -76,6 +77,7 @@ export async function getExistingSim() {
       platform,
       checkExistence: false,
       devicesSetPath,
+      // @ts-ignore This is ok
       logger: this.log,
     });