feat(Xbox): New backend for Xbox One (#12)

This backend requires:
 - Xbox One device in Dev Mode
 - Windows 10 host
 - Visual Studio
 - Windows 10 SDK

It builds a UWP (Universal Windows Platform) application hosting a
WebView pointing to the desired destination URL, then deploys that app
to the Xbox and launches it.  In this way, it is very similar to the
Tizen backend.

But because this backend uses Visual Studio to build a UWP app, it
**must** be run on Windows.

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/One X/One S/Series X/Series S (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-19)
+
+Initial release.

backends/xboxone/README.md

@@ -0,0 +1,164 @@
+# 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.
+
+
+## Supported Models
+
+These tools should work on Xbox One, Xbox One X, Xbox One S, Xbox Series X, and
+Xbox Series S devices.
+
+These tools will **not** work with Xbox 360 or the original Xbox devices.
+
+
+## Prerequisites
+
+To use these tools, you will need:
+ - Xbox One (or One X, One S, Series X, Series S) 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 have VS 2015 or VS 2017, or 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.  (We have only tested the
+   automatic configuration of the MSBuild path in VS 2019.  See `msbuild`
+   parameter described below under "Usage".)
+
+
+### 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**.  For Visual
+   Studio 2015 or Visual Studio 2017, this option is also **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**.  For Visual Studio 2015 or Visual Studio
+   2017, this option is also **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 an 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 an Xbox One node in Selenium, this package offers a CLI
+for directing an 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,75 @@
+/**
+ * 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.
+
+using Windows.ApplicationModel.Activation;
+using Windows.UI.Xaml;
+using Windows.UI.Xaml.Controls;
+
+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();
+        }
+
+        /// <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();
+
+                // 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();
+            }
+        }
+    }
+}

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>