chromeos/crosapi/mojom/test_controller.mojom

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module crosapi.mojom;

import "chromeos/crosapi/mojom/app_service_types.mojom";
import "chromeos/crosapi/mojom/extension_keeplist.mojom";
import "chromeos/crosapi/mojom/tts.mojom";
import "mojo/public/mojom/base/values.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";

[Stable, Extensible]
enum TouchEventType {
  kUnknown = 0,
  kPressed = 1,
  kMoved = 2,
  kReleased = 3,
  // Touch events can be cancelled if mouse capture or touch capture changes in
  // the middle of a gesture. For example, a long-press might change window or
  // focus activation state in a way that cancels the gesture, even though the
  // user has not released their finger. See ui::GestureRecognizer.
  kCancelled = 4
};

// Augments a bool to include an 'unknown' value.
[Stable, Extensible]
enum OptionalBoolean {
  [Default] kUnknown = 0,
  kFalse,
  kTrue,
};

// Implemented in lacros-chrome.
// Lets the Ash browser tests that require Lacros to send commands to this
// lacros-chrome instance.
// Next version: 4
// Next method id: 4
[Stable, Uuid="20e7f031-f4e1-4ad9-bd91-ad59eb8b1504"]
interface StandaloneBrowserTestController {
  // Installs a test web app in lacros-chrome given a start URL and mode (open
  // in a tab or window) and returns the ID of the installed app (see
  // |web_app::GenerateAppId|).
  InstallWebApp@0(string start_url, WindowMode mode) => (string app_id);

  // Loads a fake extension in lacros-chrome, assigns it the given name and
  // returns the ID of the loaded extension.
  [MinVersion=1]
  LoadVpnExtension@1(string extension_name) => (string extension_id);

  // Returns all available voices in lacros-chrome.
  [MinVersion=2]
  GetTtsVoices@2() => (array<TtsVoice> voices);

  // Returns Ash extension keeplist data from Lacros.
  [MinVersion=3]
  GetExtensionKeeplist@3() => (ExtensionKeepList keep_list);

  // Requests Tts(text to speech) to speak an utterance from Lacros browser.
  [MinVersion=4]
  TtsSpeak@4(TtsUtterance utterance,
             pending_remote<TtsUtteranceClient> utterance_client);
};

// Allows callers running in lacros to trigger test events that are passed to
// the active Vpn configuration.
// See chrome/browser/lacros/vpn_provider_lacros_apitest.cc for details.
// Next version: 1
// Next method id: 2
[Stable, Uuid="e2bca22e-32e9-40b3-a0bc-035b41534496"]
interface TestShillController {
  // Simulate |data| being received by the configuration determined by
  // |extension_id| and |configuration_name|.
  OnPacketReceived@0(string extension_id, string configuration_name,
      array<uint8> data);

  // Simulate |message| being received by the configuration determined by
  // |extension_id| and |configuration_name|.
  OnPlatformMessage@1(string extension_id, string configuration_name,
      uint32 message);
};

// This interface is implemented by Ash-Chrome.
// It enables tests in Lacros-Chrome to access the TestInterfaces
// of ash::Shill*Client classes.
[Stable, Uuid="12d5dbb4-e974-4f41-820e-6d92c2215452"]
interface ShillClientTestInterface {
  // From ash::ShillDeviceClient::TestInterface:

  // Adds a fake networking device.
  AddDevice@0(string device_path, string type,string name) => ();
  // Clear all fake networking devices.
  ClearDevices@1() => ();
  // Sets a property on the given fake device.
  SetDeviceProperty@2(string device_path,
      string name,
      mojo_base.mojom.Value value,
      bool notify_changed) => ();
  // Sets whether the SIM in the given fake device should be locked.
  SetSimLocked@3(string device_path, bool enabled) => ();

  // From ash::ShillServiceClient::TestInterface:

  // Adds a Service to the Manager and Service stubs.
  AddService@4(string service_path,
      string guid,
      string name,
      string type,
      string state,
      bool visible) => ();
  // Clears all Services from the Manager and Service stubs.
  ClearServices@5() => ();
  // Sets a property of the specified service.
  SetServiceProperty@6(string service_path, string property,
      mojo_base.mojom.Value value) => ();

  // From ash::ShillProfileClient::TestInterface:

  // Adds a profile.
  AddProfile@7(string profile_path, string userhash) => ();
  // Adds a service to the profile, copying properties from the
  // ShillServiceClient entry matching |service_path|.
  AddServiceToProfile@8(string profile_path, string service_path) => ();

  // From ash::ShillIPConfigClient::TestInterface:

  // Adds an IPConfig entry.
  AddIPConfig@9(string ip_config_path, mojo_base.mojom.Value properties) => ();
};

// This interface is implemented by Ash-Chrome.
// It enables tests in Lacros-Chrome to send commands as an input method.
// Next version: 2
// Next method id: 3
[Stable, Uuid="c214f4f5-c583-44d1-9547-bb2456d9e70b"]
interface InputMethodTestInterface {
  // Calls the callback when the input method has focused on some input field.
  WaitForFocus@0() => ();

  // Calls ui::InputMethodAsh::CommitText with
  // InsertTextCursorBehavior::kMoveCursorAfterText.
  CommitText@1(string text) => ();

  // Calls ui::InputMethodAsh::UpdateComposition.
  [MinVersion=1] SetComposition@2(string text, uint32 index) => ();
};

// This interface is implemented by Ash-Chrome.
// This interface provides tests a mechanism to mutate or query ash.
// In the future, this interface may merge with an automation or a11y interface.
// Next version: 21
// Next method id: 32
[Stable, Uuid="1f93f9d7-e466-466c-a675-c21b48cf30d3"]
interface TestController {
  // Clicks the middle of the views element identified by |element_name|.
  [MinVersion=11]
  ClickElement@20(string element_name) => (bool success);

  // Clicks the middle of the window. Assumes that the window exists and is
  // visible on screen. |window_id| should be obtained from
  // PlatformWindow::GetWindowUniqueId(). A typical format might be:
  // "org.chromium.lacros.9A82A161B2A0B9BADF75E9BB958B9FCB"
  ClickWindow@1(string window_id);

  // Checks whether an item with a given ID exists in the shelf.
  [MinVersion=5]
  DoesItemExistInShelf@9(string item_id) => (bool exists);

  // Checks if ash is currently showing any views UI element with the given
  // element_name.
  [MinVersion=11]
  DoesElementExist@19(string element_name) => (bool exists);

  // Queries whether a window with the given |window_id| exists and is either
  // visible or minimized. |window_id| should be obtained from
  // PlatformWindow::GetWindowUniqueId(). A typical format might be:
  // "org.chromium.lacros.9A82A161B2A0B9BADF75E9BB958B9FCB"
  DoesWindowExist@0(string window_id) => (bool exist);

  // Causes ash to enter or exit overview mode. The callback is invoked after
  // overview mode is entered (and the animation is finished).
  [MinVersion=1]
  EnterOverviewMode@2() => ();
  [MinVersion=1]
  ExitOverviewMode@3() => ();

  // Causes ash to enter tablet mode. The callback is invoked after animations
  // are finished. Note that tablet mode cannot be activated if mouse devices
  // are connected; the callback will run, but ash will not be in tablet mode.
  [MinVersion=2]
  EnterTabletMode@4() => ();

  // Causes ash to exit tablet mode. The callback is invoked after animations
  // are finished.
  [MinVersion=2]
  ExitTabletMode@5() => ();

  // Gets the context menu for a shelf item. This assumes the item is already in
  // the shelf.
  [MinVersion=7]
  GetContextMenuForShelfItem@13(string item_id) => (array<string> items);

  // Returns the value of the ash::kMinimizeOnBackKey property for the given
  // window.
  // This allows the client (eg lacros) to verify assumptions eg whether
  // the current active tab should react to a system wide back gesture.
  //
  // Note: For simplicity, the return callback is called with `true` in case
  // the property is not set, of the window is not found.
  [MinVersion=4]
  GetMinimizeOnBackKeyWindowProperty@10(string window_id)
      => (OptionalBoolean value);

  // Returns the position of a window's top-left corner in global "screen"
  // coordinates in DIPs. By design, Wayland clients do not know the global
  // position of their windows on the display. However, for window manager
  // integration testing, some tests may need to assert a window is in a certain
  // position (e.g. at the top of the display). Returns null if the window does
  // not exist.
  [MinVersion=3]
  GetWindowPositionInScreen@8(string window_id) => (gfx.mojom.Point? position);

  // Pins or unpins an item to the shelf. This assumes the item is already in
  // the shelf. Returns |false| on any error.
  [MinVersion=6]
  PinOrUnpinItemInShelf@11(string item_id, bool pin) => (bool success);

  // Select the context menu item for the shelf item with |item_id| at |index|.
  // Returns false on any error.
  [MinVersion=11]
  SelectContextMenuForShelfItem@18(string item_id, uint32 index)
      => (bool success);

  // Simulates a user left-clicking an item in the shelf. This assumes the item
  // is already in the shelf. Returns |false| on any error.
  [MinVersion=6]
  SelectItemInShelf@12(string item_id) => (bool success);

  // Creates a touch event and dispatches it to the window with |window_id|.
  // Returns immediately if the window does not exist. The |pointer_id|
  // specifies which touch-point is involved in a multi-touch gesture.
  // |pointer_id| is typically 0, meaning the first touch-point, usually the
  // index finger. |location_in_window| is in DIPs, in coordinates relative to
  // the window origin with 0,0 representing top-left. Note that the location
  // is a float, as some input devices report sub-pixel positions for touch
  // events.
  [MinVersion=3]
  SendTouchEvent@7(string window_id, TouchEventType type, uint8 pointer_id,
                   gfx.mojom.PointF location_in_window) => ();

  // Get the number of open Ash browser windows.
  [MinVersion=8]
  GetOpenAshBrowserWindows@14() => (uint32 number);

  // Close all browser windows.
  // Note: Usually there should be no Ash window open unless the test opened
  // one.
  [MinVersion=8]
  CloseAllBrowserWindows@15() => (bool success);

  // Register a lacros-chrome test controller with ash-chrome to let ash-chrome
  // send commands to lacros-chrome.
  [MinVersion=9] RegisterStandaloneBrowserTestController@16(
      pending_remote<StandaloneBrowserTestController> controller);

  // Provides a mechanism for lacros to tell ash to perform tab scrubbing.
  [MinVersion=10]
  TriggerTabScrubbing@17(float x_offset) => (bool scrubbing);

  // Simulates a user always selecting the specified app from future
  // Sharesheets.
  [MinVersion=12]
  SetSelectedSharesheetApp@21(string app_id) => ();

  // Returns the version of ash-chrome, e.g. "103.0.5029.0". The returned string
  // is intended to be compatible with the base::Version(StringPiece)
  // constructor.
  // Consider using the convenience wrapper
  // lacros_test_helper.h:IsAshVersionAtLeastForTesting instead.
  // Introduced in M-103.
  [MinVersion=13]
  GetAshVersion@22() => (string ash_version);

  // Binds |test_shill_controller| that can be used to simulate packet/message
  // events.
  [MinVersion=14]
  BindTestShillController@23(
      pending_receiver<TestShillController> test_shill_controller) => ();

  // Creates and then cancels a print job.
  [MinVersion=15]
  CreateAndCancelPrintJob@24(string job_title) => ();

  // Binds a |shill_client| that Lacros-Chrome can use to access the Shill
  // test intefaces in Ash-Chrome.
  [MinVersion=16]
  BindShillClientTestInterface@25(
      pending_receiver<ShillClientTestInterface> shill_client) => ();

  // Returns the sanitized (aka "hashed") username of the active user.
  [MinVersion=16]
  GetSanitizedActiveUsername@26() => (string sanitized_active_username);

  // Binds a |test_input_method| that Lacros-Chrome can use to receive commands
  // from a test input method in Ash-Chrome.
  [MinVersion=17]
  BindInputMethodTestInterface@27(
      pending_receiver<InputMethodTestInterface> test_input_method) => ();

  // Connects to network according to |service_path| (e.g.,"/service/eth1" and
  // "/service/wifi1") through shill service client.
  [MinVersion=18]
  ConnectToNetwork@28(string service_path);

  // Disconnects to network according to |service_path| (e.g.,"/service/eth1"
  // and "/service/wifi1") through shill service client.
  [MinVersion=18]
  DisconnectFromNetwork@29(string service_path);

  // Launches an app from the Launcher grid.
  [MinVersion=19]
  LaunchAppFromAppList@30(string app_id);

  // Clear App Service state, including from any previously installed apps.
  [MinVersion=20]
  ReinitializeAppService@31() => ();
};