feat: Add wrappers for the Windows screen recorder (#1313)

Author: mykola-mokhnach

azure-pipelines.yml

@@ -15,43 +15,46 @@ variables:
   IOS_PLATFORM_VERSION: 12.2
   IOS_DEVICE_NAME: iPhone X
 
-steps:
-- task: NodeTool@0
-  inputs:
-    versionSpec: '11.x'
-
-- script: |
-    echo "Configuring Environment"
-    echo "y" | $ANDROID_HOME/tools/bin/sdkmanager --install 'system-images;$(ANDROID_EMU_TARGET);$(ANDROID_EMU_TAG);$(ANDROID_EMU_ABI)'
-    echo "no" | $ANDROID_HOME/tools/bin/avdmanager create avd -n "$(ANDROID_EMU_NAME)" -k 'system-images;$(ANDROID_EMU_TARGET);$(ANDROID_EMU_TAG);$(ANDROID_EMU_ABI)' --force
-    echo $ANDROID_HOME/emulator/emulator -list-avds
-
-    echo "Starting emulator"
-    nohup $ANDROID_HOME/emulator/emulator -avd "$(ANDROID_EMU_NAME)" -no-snapshot > /dev/null 2>&1 &
-    $ANDROID_HOME/platform-tools/adb wait-for-device
-    while [[ $? -ne 0 ]]; do sleep 1; $ANDROID_HOME/platform-tools/adb shell pm list packages; done;
-    $ANDROID_HOME/platform-tools/adb devices
-    echo "Emulator started"
-
-    sudo xcode-select -s /Applications/Xcode_$(XCODE_VERSION).app/Contents/Developer
-    xcrun simctl list
-
-    npm config delete prefix
-    npm config set prefix $NVM_DIR/versions/node/`node --version`
-    node --version
-
-    npm install -g appium@beta
-    appium --version
-
-    java -version
-
-- task: Gradle@2
-  inputs:
-    gradleWrapperFile: 'gradlew'
-    gradleOptions: '-Xmx3072m'
-    javaHomeOption: 'JDKVersion'
-    jdkVersionOption: '1.8'
-    jdkArchitectureOption: 'x64'
-    publishJUnitResults: true
-    tasks: 'build'
-    options: 'xcuiTest uiAutomationTest -x checkstyleTest -x test -x signMavenJavaPublication'
+jobs:
+- job: E2E_Tests
+  timeoutInMinutes: 120
+  steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '11.x'
+
+  - script: |
+      echo "Configuring Environment"
+      echo "y" | $ANDROID_HOME/tools/bin/sdkmanager --install 'system-images;$(ANDROID_EMU_TARGET);$(ANDROID_EMU_TAG);$(ANDROID_EMU_ABI)'
+      echo "no" | $ANDROID_HOME/tools/bin/avdmanager create avd -n "$(ANDROID_EMU_NAME)" -k 'system-images;$(ANDROID_EMU_TARGET);$(ANDROID_EMU_TAG);$(ANDROID_EMU_ABI)' --force
+      echo $ANDROID_HOME/emulator/emulator -list-avds
+
+      echo "Starting emulator"
+      nohup $ANDROID_HOME/emulator/emulator -avd "$(ANDROID_EMU_NAME)" -no-snapshot > /dev/null 2>&1 &
+      $ANDROID_HOME/platform-tools/adb wait-for-device
+      while [[ $? -ne 0 ]]; do sleep 1; $ANDROID_HOME/platform-tools/adb shell pm list packages; done;
+      $ANDROID_HOME/platform-tools/adb devices
+      echo "Emulator started"
+
+      sudo xcode-select -s /Applications/Xcode_$(XCODE_VERSION).app/Contents/Developer
+      xcrun simctl list
+
+      npm config delete prefix
+      npm config set prefix $NVM_DIR/versions/node/`node --version`
+      node --version
+
+      npm install -g appium@beta
+      appium --version
+
+      java -version
+
+  - task: Gradle@2
+    inputs:
+      gradleWrapperFile: 'gradlew'
+      gradleOptions: '-Xmx3072m'
+      javaHomeOption: 'JDKVersion'
+      jdkVersionOption: '1.8'
+      jdkArchitectureOption: 'x64'
+      publishJUnitResults: true
+      tasks: 'build'
+      options: 'xcuiTest uiAutomationTest -x checkstyleTest -x test -x signMavenJavaPublication'

src/main/java/io/appium/java_client/android/AndroidStartScreenRecordingOptions.java

@@ -21,6 +21,7 @@
 import com.google.common.collect.ImmutableMap;
 
 import io.appium.java_client.screenrecording.BaseStartScreenRecordingOptions;
+import io.appium.java_client.screenrecording.ScreenRecordingUploadOptions;
 
 import java.time.Duration;
 import java.util.Map;
@@ -49,6 +50,14 @@ public AndroidStartScreenRecordingOptions withBitRate(int bitRate) {
         this.bitRate = bitRate;
         return this;
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public AndroidStartScreenRecordingOptions withUploadOptions(ScreenRecordingUploadOptions uploadOptions) {
+        return (AndroidStartScreenRecordingOptions) super.withUploadOptions(uploadOptions);
+    }
 
     /**
      * The video size of the generated media file. The format is WIDTHxHEIGHT.

src/main/java/io/appium/java_client/ios/IOSStartScreenRecordingOptions.java

@@ -22,6 +22,7 @@
 import com.google.common.collect.ImmutableMap;
 
 import io.appium.java_client.screenrecording.BaseStartScreenRecordingOptions;
+import io.appium.java_client.screenrecording.ScreenRecordingUploadOptions;
 
 import java.time.Duration;
 import java.util.Map;
@@ -38,6 +39,14 @@ public static IOSStartScreenRecordingOptions startScreenRecordingOptions() {
         return new IOSStartScreenRecordingOptions();
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public IOSStartScreenRecordingOptions withUploadOptions(ScreenRecordingUploadOptions uploadOptions) {
+        return (IOSStartScreenRecordingOptions) super.withUploadOptions(uploadOptions);
+    }
+
     /**
      * The video codec type used for encoding of the recorded screen capture.
      * Execute `ffmpeg -codecs` in the terminal to see the list of supported video codecs.

src/main/java/io/appium/java_client/screenrecording/BaseScreenRecordingOptions.java

@@ -33,7 +33,7 @@ public abstract class BaseScreenRecordingOptions<T extends BaseScreenRecordingOp
      *                      for more details.
      * @return self instance for chaining.
      */
-    public T withUploadOptions(ScreenRecordingUploadOptions uploadOptions) {
+    protected T withUploadOptions(ScreenRecordingUploadOptions uploadOptions) {
         this.uploadOptions = checkNotNull(uploadOptions);
         //noinspection unchecked
         return (T) this;

src/main/java/io/appium/java_client/screenrecording/BaseStartScreenRecordingOptions.java

@@ -29,27 +29,6 @@ public abstract class BaseStartScreenRecordingOptions<T extends BaseStartScreenR
     private Boolean forceRestart;
     private Duration timeLimit;
 
-    /**
-     * The remotePath upload option is the path to the remote location,
-     * where the resulting video should be uploaded.
-     * The following protocols are supported: http/https (multipart), ftp.
-     * Missing value (the default setting) means the content of the resulting
-     * file should be encoded as Base64 and passed as the endpoint response value, but
-     * an exception will be thrown if the generated media file is too big to
-     * fit into the available process memory.
-     * This option only has an effect if there is a screen recording session in progress
-     * and forced restart is not enabled (the default setting).
-     *
-     * @param uploadOptions see the documentation on {@link ScreenRecordingUploadOptions}
-     *                      for more details.
-     * @return self instance for chaining.
-     */
-    @Override
-    public T withUploadOptions(ScreenRecordingUploadOptions uploadOptions) {
-        //noinspection unchecked
-        return (T) super.withUploadOptions(uploadOptions);
-    }
-
     /**
      * The maximum recording time.
      *
@@ -64,8 +43,7 @@ public T withTimeLimit(Duration timeLimit) {
 
     /**
      * Whether to ignore the result of previous capture and start a new recording
-     * immediately. By default the endpoint will try to catch and return the result of
-     * the previous capture if it's still available.
+     * immediately.
      *
      * @return self instance for chaining.
      */
@@ -75,6 +53,17 @@ public T enableForcedRestart() {
         return (T) this;
     }
 
+    /**
+     * Whether to return silently if there is an active video recording.
+     *
+     * @return self instance for chaining.
+     */
+    public T disableForcedRestart() {
+        this.forceRestart = false;
+        //noinspection unchecked
+        return (T) this;
+    }
+
     @Override
     public Map<String, Object> build() {
         final ImmutableMap.Builder<String, Object> builder = ImmutableMap.builder();

src/main/java/io/appium/java_client/screenrecording/CanRecordScreen.java

@@ -31,17 +31,13 @@ public interface CanRecordScreen extends ExecutesMethod {
      *
      * @param options see the documentation on the {@link BaseStartScreenRecordingOptions}
      *                descendant for the particular platform.
-     * @return Base-64 encoded content of the recorded media file or an empty string
-     *     if the file has been successfully uploaded to a remote location (depends on the actual options).
      */
     default <T extends BaseStartScreenRecordingOptions> String startRecordingScreen(T options) {
         return CommandExecutionHelper.execute(this, startRecordingScreenCommand(options));
     }
 
     /**
      * Start asynchronous screen recording process with default options.
-     *
-     * @return Base-64 encoded content of the recorded media file.
      */
     default String startRecordingScreen() {
         return this.execute(START_RECORDING_SCREEN).getValue().toString();

src/main/java/io/appium/java_client/windows/WindowsDriver.java

@@ -21,6 +21,7 @@
 import io.appium.java_client.AppiumDriver;
 import io.appium.java_client.FindsByWindowsAutomation;
 import io.appium.java_client.HidesKeyboardWithKeyName;
+import io.appium.java_client.screenrecording.CanRecordScreen;
 import io.appium.java_client.service.local.AppiumDriverLocalService;
 import io.appium.java_client.service.local.AppiumServiceBuilder;
 import org.openqa.selenium.Capabilities;
@@ -32,7 +33,7 @@
 
 public class WindowsDriver<T extends WebElement>
         extends AppiumDriver<T> implements PressesKeyCode, HidesKeyboardWithKeyName,
-        FindsByWindowsAutomation<T> {
+        FindsByWindowsAutomation<T>, CanRecordScreen {
 
     public WindowsDriver(HttpCommandExecutor executor, Capabilities capabilities) {
         super(executor, updateDefaultPlatformName(capabilities, WINDOWS));

src/main/java/io/appium/java_client/windows/WindowsStartScreenRecordingOptions.java

@@ -0,0 +1,151 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * 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.
+ */
+
+package io.appium.java_client.windows;
+
+import com.google.common.collect.ImmutableMap;
+import io.appium.java_client.screenrecording.BaseStartScreenRecordingOptions;
+
+import java.time.Duration;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+public class WindowsStartScreenRecordingOptions
+        extends BaseStartScreenRecordingOptions<WindowsStartScreenRecordingOptions> {
+    private Integer fps;
+    private String videoFilter;
+    private String preset;
+    private Boolean captureCursor;
+    private Boolean captureClicks;
+    private String audioInput;
+
+    public static WindowsStartScreenRecordingOptions startScreenRecordingOptions() {
+        return new WindowsStartScreenRecordingOptions();
+    }
+
+    /**
+     * The count of frames per second in the resulting video.
+     * Increasing fps value also increases the size of the resulting
+     * video file and the CPU usage.
+     *
+     * @param fps The actual frames per second value.
+     *            The default value is 15.
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions withFps(int fps) {
+        this.fps = fps;
+        return this;
+    }
+
+    /**
+     * Whether to capture the mouse cursor while recording
+     * the screen. Disabled by default.
+     *
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions enableCursorCapture() {
+        this.captureCursor = true;
+        return this;
+    }
+
+    /**
+     * Whether to capture the click gestures while recording
+     * the screen. Disabled by default.
+     *
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions enableClicksCapture() {
+        this.captureClicks = true;
+        return this;
+    }
+
+    /**
+     * If provided then the given audio input will be used to record the computer audio
+     * along with the desktop video. The list of available devices could be retrieved using
+     * `ffmpeg -list_devices true -f dshow -i dummy` command.
+     *
+     * @param audioInput One of valid audio input names listed by ffmpeg
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions withAudioInput(String audioInput) {
+        this.audioInput = audioInput;
+        return this;
+    }
+    
+    /**
+     * The video filter spec to apply for ffmpeg.
+     * See https://trac.ffmpeg.org/wiki/FilteringGuide for more details on the possible values.
+     * Example: Set it to `scale=ifnot(gte(iw\,1024)\,iw\,1024):-2` in order to limit the video width
+     * to 1024px. The height will be adjusted automatically to match the actual screen aspect ratio.
+     *
+     * @param videoFilter Valid ffmpeg video filter spec string.
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions withVideoFilter(String videoFilter) {
+        this.videoFilter = videoFilter;
+        return this;
+    }
+
+    /**
+     * A preset is a collection of options that will provide a certain encoding speed to compression ratio.
+     * A slower preset will provide better compression (compression is quality per filesize).
+     * This means that, for example, if you target a certain file size or constant bit rate, you will
+     * achieve better quality with a slower preset. Read https://trac.ffmpeg.org/wiki/Encode/H.264
+     * for more details.
+     *
+     * @param preset One of the supported encoding presets. Possible values are:
+     *     - ultrafast
+     *     - superfast
+     *     - veryfast (default)
+     *     - faster
+     *     - fast
+     *     - medium
+     *     - slow
+     *     - slower
+     *     - veryslow
+     * @return self instance for chaining.
+     */
+    public WindowsStartScreenRecordingOptions withPreset(String preset) {
+        this.preset = preset;
+        return this;
+    }
+
+    /**
+     * The maximum recording time. The default value is 600 seconds (10 minutes).
+     * The minimum time resolution unit is one second.
+     *
+     * @param timeLimit The actual time limit of the recorded video.
+     * @return self instance for chaining.
+     */
+    @Override
+    public WindowsStartScreenRecordingOptions withTimeLimit(Duration timeLimit) {
+        return super.withTimeLimit(timeLimit);
+    }
+
+    @Override
+    public Map<String, Object> build() {
+        final ImmutableMap.Builder<String, Object> builder = ImmutableMap.builder();
+        builder.putAll(super.build());
+        ofNullable(fps).map(x -> builder.put("fps", x));
+        ofNullable(preset).map(x -> builder.put("preset", x));
+        ofNullable(videoFilter).map(x -> builder.put("videoFilter", x));
+        ofNullable(captureClicks).map(x -> builder.put("captureClicks", x));
+        ofNullable(captureCursor).map(x -> builder.put("captureCursor", x));
+        ofNullable(audioInput).map(x -> builder.put("audioInput", x));
+        return builder.build();
+    }
+}