feat(Xbox): New backend for Xbox One

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.1.1 (2021-02-11)
+
+Added links to Xbox One backend package from base package README.
+
 ## 1.1.0 (2020-12-22)
 
 Document setup with Chromium-based Edge.  Although this didn't require any code

README.md

@@ -35,6 +35,7 @@ Out of the box, we provide backends for:
  - Chromecast (NPM package [`chromecast-webdriver-server`](https://www.npmjs.com/package/chromecast-webdriver-server))
  - ChromeOS (NPM package [`chromeos-webdriver-server`](https://www.npmjs.com/package/chromeos-webdriver-server))
  - Tizen (NPM package [`tizen-webdriver-server`](https://www.npmjs.com/package/tizen-webdriver-server))
+ - Xbox One (NPM package [`xbox-one-webdriver-server`](https://www.npmjs.com/package/xbox-one-webdriver-server))
 
 In addition, you'll need JAR files from the package [`generic-webdriver-server`](https://www.npmjs.com/package/generic-webdriver-server).
 

backends/tizen/README.md

@@ -40,7 +40,8 @@ properties:
    provided in the client's desired capabilities instead.  (See below.)
  - `genericwebdriver.backend.params.wake-on-lan-address`: The ethernet address
    of the Tizen device, to wake it in case it is sleeping at the beginning of
-   the session.  Optional, but highly recommended.
+   the session.  Optional, but highly recommended.  NOTE: This will only work
+   over wired ethernet connections, **not WiFi**!
 
 
 ## Supported parameters
@@ -50,7 +51,9 @@ This backend supports the following parameters:
  - `hostname`: **(required)** The hostname or IP address of the Tizen device,
    with optional port number.
  - `wake-on-lan-address`: The ethernet address of the Tizen device, to wake it
-   in case it is sleeping at the beginning of the session.
+   in case it is sleeping at the beginning of the session.  Optional, but
+   highly recommended.  NOTE: This will only work over wired ethernet
+   connections, **not WiFi**!
  - `local-tizen-studio`: If true, use a locally-installed copy of Tizen Studio
    instead of a Docker image.
  - `tizen-studio-docker-image`: The name of a Docker image to use for Tizen
@@ -95,7 +98,8 @@ directing a Tizen device to a specific URL.  For example, if installed globally
 with `npm install -g tizen-webdriver-server`:
 
 ```sh
-tizen-webdriver-cli --hostname=192.168.1.42 --url=https://www.google.com/
+tizen-webdriver-cli --hostname=192.168.1.42 \
+  --url=https://shaka-player-demo.appspot.com/demo/
 ```
 
 

backends/tizen/tizen-utils.js

@@ -182,7 +182,8 @@ function addTizenArgs(yargs) {
         description:
             'The ethernet address of the Tizen host, which we will use to ' +
             'wake the device if it is sleeping at the beginning of the ' +
-            'session.',
+            'session.  Optional, but highly recommended.  NOTE: This will ' +
+            'only work over wired ethernet connections, **not WiFi**!',
         type: 'string',
       })
       .option('local-tizen-studio', {

backends/xboxone/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 1.0.0 (2021-02-11)
+
+Initial release.

backends/xboxone/README.md

@@ -0,0 +1,152 @@
+# Xbox One WebDriver Server
+
+A [WebDriver][] server for Xbox One devices, implementing the subset of the
+WebDriver protocol necessary for [Karma][].  Add Xbox One devices to your
+[Selenium grid][]!
+
+Part of the [Generic WebDriver Server][] family.
+
+
+## Prerequisites
+
+To use these tools, you will need:
+ - Xbox One device in Dev Mode
+ - Windows 10 host
+ - Visual Studio 2015 Update 3, Visual Studio 2017, or Visual Studio 2019
+ - Windows 10 SDK w/ Universal Windows App Development Tools (UWP)
+
+
+### Dev Mode Setup
+
+1. To put your Xbox One device in Dev Mode, start with
+   [Microsoft's official docs on dev mode][].
+
+   However, if you find that the official setup never completes, you can try
+   the [alternate method for dev mode setup][] using a secret menu and button
+   sequence instead:
+
+   `Settings > System > Console Info > Press LB RB LT RT > Developer Settings >
+   Developer Mode`
+
+2. Configure the device for remote access and set a username and password.
+
+   1. From dev home, click `Remote Access Settings`.
+   2. Check `Enable Xbox Device Portal`.
+   3. Check `Require authentication to remotely access this console`.
+   4. Click `Set username and password`.
+   5. Set a username and password, which the WebDriver server will use to
+      authenticate.
+
+3. Create a new test account or sign in with an existing account.  Without an
+   account, neither Microsoft Edge nor WebView will work for some reason.
+
+   1. From dev home, under `Test accounts`, click `Add existing` or
+      `Create new`.
+   2. Follow the prompts to sign in.
+
+[Microsoft's official docs on dev mode]: https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/devkit-activation
+[alternate method for dev mode setup]: https://docs.microsoft.com/en-us/answers/questions/81169/almost-there-trying-activate-dev-console.html
+
+
+### Windows 10 host setup
+
+1. If you don't have Visual Studio 2015 Update 3, Visual Studio 2017, or Visual
+   Studio 2019, install it now: https://visualstudio.microsoft.com/
+2. When installing the Windows 10 SDK, check Universal Windows App Development
+   Tools: https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/development-environment-setup
+3. If you install Visual Studio in any unusual location, you may have to
+   provide an explicit path to `MSBuild.exe` when you configure the WebDriver
+   server later.
+
+
+### Screenshot setup
+
+Unlike many others, this backend **does** support screenshots.  However, you
+need to configure the Xbox display settings to make sure the screenshots are
+consistent and correctly-aligned.
+
+1. From dev home, under `Settings`, click `Launch Settings`.
+2. Under `General`, click `TV & display options`.
+3. Under `Advanced`, click `Video fidelity & overscan`.
+4. Under `Overscan border`, uncheck `Apps can add a border`.
+
+
+## Installation
+
+```sh
+npm install --save-dev generic-webdriver-server xbox-one-webdriver-server
+```
+
+
+## Usage
+
+First, please refer to the ["Setup" doc][] for [Generic WebDriver Server][].
+That will explain how to set up Selenium to talk to Generic WebDriver Servers,
+as well as how to set server parameters.
+
+In the command-line for the Selenium node, set the following Java system
+properties:
+
+ - `genericwebdriver.browser.name`: We recommend the value "xboxone".  See also
+   notes in the ["Setup" doc][].
+ - `genericwebdriver.backend.exe`: The path to the executable, such as
+   `node_modules/.bin/xbox-one-webdriver-server.cmd` or
+   `%APPDATA%\npm\xbox-one-webdriver-server.cmd`.
+ - `genericwebdriver.backend.params.hostname`: The hostname or IP address of the
+   Xbox One device, with optional Device Portal port number (default 11443).  If
+   omitted, this **must** be provided in the client's desired capabilities
+   instead.  (See below.)
+ - `genericwebdriver.backend.params.username`: The Xbox One Device Portal
+   username.  If omitted, this **must** be provided in the client's desired
+   capabilities instead.  (See below.)
+ - `genericwebdriver.backend.params.password`: The Xbox One Device Portal
+   password.  If omitted, this **must** be provided in the client's desired
+   capabilities instead.  (See below.)
+ - `genericwebdriver.backend.params.msbuild`: The path to `MSBuild.exe` from
+   Visual Studio.  The server will attempt to locate this at typical locations
+   on all drives.  If that fails, this option becomes **required**.
+
+
+## Supported parameters
+
+This backend supports the following parameters:
+
+ - `hostname`: **(required)** The hostname or IP address of the Xbox One device,
+   with optional Device Portal port number (default 11443).
+ - `username`: **(required)** The Xbox One Device Portal username.
+ - `password`: **(required)** The Xbox One Device Portal password.
+ - `msbuild`: The path to `MSBuild.exe` from Visual Studio.  The server will
+   attempt to locate this at typical locations on all drives.  If that fails,
+   this option becomes **required**.
+
+
+## How it works
+
+See [how-it-works.md](https://github.com/google/generic-webdriver-server/blob/main/backends/xbox-one/how-it-works.md)
+for details.
+
+
+## Tunneling to a Xbox One device on another network
+
+See [tunneling.md](https://github.com/google/generic-webdriver-server/blob/main/backends/xbox-one/tunneling.md)
+for details.
+
+
+## Using the CLI
+
+In addition to running a Xbox One node in Selenium, this package offers a CLI
+for directing a Xbox One device to a specific URL.  For example, if installed
+globally with `npm install -g xbox-one-webdriver-server`:
+
+```sh
+xbox-one-webdriver-cli.cmd ^
+  --hostname=192.168.1.42 --username=myuser --password=mypassword ^
+  --url=https://shaka-player-demo.appspot.com/demo/
+```
+
+
+[Generic WebDriver Server]: https://github.com/google/generic-webdriver-server
+[Karma]: https://karma-runner.github.io/
+[Selenium grid]: https://www.selenium.dev/documentation/en/grid/
+["Setup" doc]: https://github.com/google/generic-webdriver-server/blob/main/setup.md
+[WebDriver]: https://www.w3.org/TR/webdriver2/

backends/xboxone/app-template/.gitignore

@@ -0,0 +1,5 @@
+.vs/
+AppPackages/
+BundleArtifacts/
+bin/
+obj/

backends/xboxone/app-template/App.xaml

@@ -0,0 +1,26 @@
+<!--
+ Copyright 2020 Google LLC
+
+ 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.
+-->
+
+<!--
+This is the overall application definition.
+-->
+
+<Application
+    x:Class="XboxOneWebDriverServer.App"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:local="using:XboxOneWebDriverServer">
+</Application>

backends/xboxone/app-template/App.xaml.cs

@@ -0,0 +1,104 @@
+/**
+ * Copyright 2020 Google LLC
+ *
+ * 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.
+ */
+
+// This is the C# code-behind for App.xaml.  It's all boilerplate generated by
+// Visual Studio, then cleaned up by hand to remove things we definitely didn't
+// need.  There may be more cleanup possible.
+
+using System;
+using Windows.ApplicationModel;
+using Windows.ApplicationModel.Activation;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+using Windows.UI.Xaml.Navigation;
+
+namespace XboxOneWebDriverServer
+{
+    /// <summary>
+    /// Provides application-specific behavior to supplement the default Application class.
+    /// </summary>
+    sealed partial class App : Application
+    {
+        /// <summary>
+        /// Initializes the singleton application object.  This is the first line of authored code
+        /// executed, and as such is the logical equivalent of main() or WinMain().
+        /// </summary>
+        public App()
+        {
+            this.InitializeComponent();
+            this.Suspending += OnSuspending;
+        }
+
+        /// <summary>
+        /// Invoked when the application is launched normally by the end user.  Other entry points
+        /// will be used such as when the application is launched to open a specific file.
+        /// </summary>
+        /// <param name="e">Details about the launch request and process.</param>
+        protected override void OnLaunched(LaunchActivatedEventArgs e)
+        {
+            Frame rootFrame = Window.Current.Content as Frame;
+
+            // Do not repeat app initialization when the Window already has content,
+            // just ensure that the window is active
+            if (rootFrame == null)
+            {
+                // Create a Frame to act as the navigation context and navigate to the first page
+                rootFrame = new Frame();
+
+                rootFrame.NavigationFailed += OnNavigationFailed;
+
+                // Place the frame in the current Window
+                Window.Current.Content = rootFrame;
+            }
+
+            if (e.PrelaunchActivated == false)
+            {
+                if (rootFrame.Content == null)
+                {
+                    // When the navigation stack isn't restored navigate to the first page,
+                    // configuring the new page by passing required information as a navigation
+                    // parameter
+                    rootFrame.Navigate(typeof(MainPage), e.Arguments);
+                }
+                // Ensure the current window is active
+                Window.Current.Activate();
+            }
+        }
+
+        /// <summary>
+        /// Invoked when Navigation to a certain page fails
+        /// </summary>
+        /// <param name="sender">The Frame which failed navigation</param>
+        /// <param name="e">Details about the navigation failure</param>
+        void OnNavigationFailed(object sender, NavigationFailedEventArgs e)
+        {
+            throw new Exception("Failed to load Page " + e.SourcePageType.FullName);
+        }
+
+        /// <summary>
+        /// Invoked when application execution is being suspended.  Application state is saved
+        /// without knowing whether the application will be terminated or resumed with the contents
+        /// of memory still intact.
+        /// </summary>
+        /// <param name="sender">The source of the suspend request.</param>
+        /// <param name="e">Details about the suspend request.</param>
+        private void OnSuspending(object sender, SuspendingEventArgs e)
+        {
+            var deferral = e.SuspendingOperation.GetDeferral();
+            deferral.Complete();
+        }
+    }
+}

backends/xboxone/app-template/MainPage.xaml

@@ -0,0 +1,39 @@
+<!--
+ Copyright 2020 Google LLC
+
+ 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.
+-->
+
+<!--
+This contains the actual WebView that we will point to a target URL.
+The URL will be inserted just before compilation.
+-->
+
+<Page
+    x:Class="XboxOneWebDriverServer.MainPage"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:local="using:XboxOneWebDriverServer"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d"
+    BorderThickness="0"
+    Background="White">
+
+    <WebView
+        Source="DESTINATION"
+        DefaultBackgroundColor="white"
+        FocusVisualPrimaryThickness="0"
+        FocusVisualSecondaryThickness="0"
+        />
+</Page>