// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.modular.testing;

using fuchsia.mem;
using fuchsia.modular;
using fuchsia.modular.session;
using fuchsia.sys;

/// The |TestHarness| service is used to run the modular runtime under a
/// hermetic environment and drive integration tests under it. Tests may use
/// this service to intercept components and assume their role. Additionally,
/// tests may use |TestHarness/ConnectToModularService()| to get capabilities
/// for controlling stories (using PuppetMaster) and connecting to agents
/// (using ComponentContext).
///
/// Closing the |TestHarness| connection will kill the |TestHarness| environment
/// including the modular runtime running under it.
///
/// On error, this connection is closed with the following epitaphs:
/// * ZX_ERR_INVALID_ARGS: Run() failed to execute succesfully.
/// * ZX_ERR_BAD_STATE: Other methods are called before Run() is called.
/// * ZX_ERR_ALREADY_BOUND: Run() was already called.
/// * ZX_ERR_ALREADY_EXISTS: The same environment service is being provided
///   twice.
[Discoverable]
protocol TestHarness {
    /// Initializes an instance of the modular runtime in an enclosed
    /// environment, configured with parameters provided in |spec|. Closing the
    /// |TestHarness| connection will kill the enclosed environment.
    ///
    /// This protocol connection is closed if Run() fails, with the following
    /// epitaphs:
    ///  * ZX_ERR_INVALID_ARGS: |spec| is mal-formed.
    ///  * ZX_ERR_ALREADY_EXISTS: The same environment service is being provided
    ///    twice in |spec.env_services|
    ///  * ZX_ERR_ALREADY_BOUND: Run() was already called.
    Run(TestHarnessSpec spec);

    /// This event is sent when a component specified in
    /// |TestHarnessSpec.components_to_intercept| is created.
    /// |startup_info.launch_info.url| contains the component URL.
    ///
    /// Closing |intercepted_component| will signal to the component manager
    /// that this component has exited unexpectedly. Prefer to use
    /// InterceptedComponent/Exit to provide exit code and reason.
    -> OnNewComponent(fuchsia.sys.StartupInfo startup_info,
                      InterceptedComponent intercepted_component);

    /// Tests may use this method to connect to services provided by the modular
    /// runtime. These services share the same component namespace for any
    /// resources they create (e.g., entities, message queues, and module
    /// names).
    ///
    /// This protocol connection is closed with the following epitaphs:
    ///  * ZX_ERR_BAD_STATE: if |ConnectToModularService()| is called before
    ///   |Run()|.
    ///  * ZX_ERR_INVALID_ARGS: if |service| is not set to a value.
    ConnectToModularService(ModularService service);

    /// Connects to environment services injected into the TestHarness
    /// environment.
    ConnectToEnvironmentService(string service_name, handle<channel> request);

    /// DEPRECATED. Use |ConnectToModularService()| instead.
    GetService(TestHarnessService service);
};

/// Describes which service to connect to using |ConnectToModularService()|.
xunion ModularService {
    request<fuchsia.modular.PuppetMaster> puppet_master;
    request<fuchsia.modular.ComponentContext> component_context;
    request<fuchsia.modular.AgentContext> agent_context;
};

/// InterceptedComponent represents an intercepted component's lifecycle.
/// Closing this connection causes the component to be killed, and is
/// equivalent in behaviour to the |ComponentController| being closed.
protocol InterceptedComponent {
    /// Signals that component has exit'd with the specified exit code. The
    /// values here are bubbled up to the
    /// |fuchsia.sys.ComponentController.OnTerminated| event. The |OnKill| event
    /// is sent, and this InterceptedComponent handle is closed.
    Exit(int64 exit_code, fuchsia.sys.TerminationReason reason);

    /// The event is sent when the component is killed by the associated
    /// |fuchsia.sys.ComponentController|, or when |Exit()| is called.
    -> OnKill();
};

/// Defines the setup of an environment running an instance of the modular
/// framework used for testing purposes. This table is supplied to
/// |TestHarness.Run()|. A malformed |TestHarnessSpec| will cause |TestHarness|
/// connection to close with an epitaph of ZX_ERR_INVALID_ARGS.
///
/// By default, the following services are made available to the hermetic
/// environment:
///  * fuchsia.auth.account.AccountManager
///  * fuchsia.devicesettings.DeviceSettingsManager
///
/// Additional services may be supplied using using
/// |TestHarnessSpec.env_services_to_inherit| and
/// |TestHarnessSpec.injected_services|. Additional services override the
/// default services listed above.
table TestHarnessSpec {
    /// Configuration for basemgr. See |fuchsia.modular.session.BasemgrConfig|
    /// for a description of the defaults.
    ///
    /// The test harness will amend |basemgr_config| before passing it off to
    /// the modular runtime in the following way:
    /// * If |basemgr_config.base_shell.app_config.url| is not set, the test
    ///   harness will use a base shell which automatically logs into the
    ///   session.
    /// * If |basemgr_config.session_shell_map[0].config.app_config.url| is not
    ///   set, the test harness will use a shell which automatically starts new
    ///   stories.
    /// * If |basemgr_config.story_shell.app_config.url| is not set, the test
    ///   harness use a minimally functioning story shell which displays all
    ///   mods in a story.
    ///
    /// To intercept and mock the shells, users may provide fake URLs for the
    /// shells and specify that the fake URL be intercepted using
    /// |components_to_intercept|.
    1: fuchsia.modular.session.BasemgrConfig basemgr_config;

    /// Configuration for sessionmgr. See
    /// |fuchsia.modular.session.SessionmgrConfig| for a description of the
    /// defaults.
    2: fuchsia.modular.session.SessionmgrConfig sessionmgr_config;

    /// List of component URLs (and additional .cmx contents) to intercept.
    4: vector<InterceptSpec> components_to_intercept;

    /// Options to configure the test harness environment. Use this to inject
    /// services into the environment.
    ///
    /// Optional.
    6: EnvironmentServicesSpec env_services;

    /// DEPRECATED. Use |env_services.service_dir| to pass through services from
    /// parent environment.
    3: vector<string> env_services_to_inherit;

    /// DEPRECATED. Use |env_services.services_from_components| instead.
    5: vector<InjectedService> env_services_to_inject;
};

/// Options for configuring the test harness environment with services.
///
/// If the same service is provided in more than one place, |TestHarness|
/// connection is closed with a ZX_ERR_ALREADY_EXISTS epitaph.
table EnvironmentServicesSpec {
    /// A directory of services to be provided to the test harness environment.
    ///
    /// Optional.
    1: handle<channel> service_dir;

    /// A list of services provided by components to inject into the test
    /// harness environment. Multiple services may be provided by the same
    /// component, but only one instance of the component is launched to serve
    /// its services. Components are started when one of their services is
    /// requested, and are kept alive for the duration of the test harness
    /// environment's life.
    ///
    /// Optional.
    2: vector<ComponentService> services_from_components;
};

/// Describes a service to be provided by a component instance.
struct ComponentService {
    /// Name of the service.
    string name;

    /// URL of the component which will provide the service.
    /// The service is retrieved from this component's /out/svc namespace.
    fuchsia.sys.component_url url;
};

/// Describes a component to intercept. Malformed parameters result in closing
/// |TestHarness| with a |ZX_ERR_INVALID_ARGS| epitaph.
table InterceptSpec {
    /// Required. Must be a valid component URL (e.g., fuchsia-pkg://..), or is
    /// considered malformed.
    1: fuchsia.sys.component_url component_url;

    /// The .cmx contents of this component's manifest. A minimal manifest is
    /// constructed by default. If set, the contents of |extra_cmx_contents|
    /// override the default constructed manifest, which only has the required
    /// "program.binary" field defined.
    ///
    /// |extra_cmx_contents| must be a valid .cmx JSON. Example:
    ///
    /// {
    ///   "sandbox": {
    ///     "services": [
    ///       "fuchsia.sys.Launcher",
    ///     ]
    ///   }
    /// }
    2: fuchsia.mem.Buffer extra_cmx_contents;
};

/// DEPRECATED. Use |ConnectToModularService| instead.
xunion TestHarnessService {
    request<fuchsia.modular.PuppetMaster> puppet_master;
    request<fuchsia.modular.ComponentContext> component_context;
    request<fuchsia.modular.AgentContext> agent_context;
};

/// DEPRECATED. Renamed to ComponentService.
struct InjectedService {
    /// Name of the service.
    string name;

    /// URL of the component which will provide the service.
    /// The service is retrieved from this component's /out/svc namespace.
    fuchsia.sys.component_url url;
};