sdk/fidl/fuchsia.testing.harness/realm_proxy.fidl

// Copyright 2023 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.testing.harness;

using zx;
using fuchsia.io;

/// The maximum number of characters allowed in a FIDL protocol name.
/// This is set to the maximum length of filesystem node name because
/// we generally use the filesystem for protocol discovery.
@available(added=HEAD)
const MAX_PROTOCOL_LEN uint64 = fuchsia.io.MAX_NAME_LENGTH;

/// This protocol mediates a test suite's access to a component under test.
///
/// A RealmProxy is a test harness which allows some test suite to create instances
/// of the component(s) under test on demand. Most importantly, the test suite
/// does not have to know which components are created or how they are created;
/// It is only required to know which capabilities the components expose.
///
/// For example, a generic test suite for Fuchsia filesystems can use the RealmProxy
/// protocol to spawn components that serve protocols from the fuchsia.io FIDL
/// library. The test suite doesn't need to know which filesystem it's testing
/// or how the filesystem is initialized. It just needs to call
/// [ConnectToNamedProtocol] with the name of a fuchsia.io protocol and start
/// testing. By running this test suite with different proxies that initialize
/// different filesystems, we can use the same suite to validate each system.
///
/// Prefer to connect to RealmFactory instead to obtain an instance of RealmProxy;
/// in the future RealmProxy will no longer be discoverable TODO(https://fxbug.dev/42077343).
@available(added=HEAD)
@discoverable
closed protocol RealmProxy {
    /// Connects [server_end] to the [protocol] from this proxy's namespace.
    strict ConnectToNamedProtocol(resource struct {
        protocol string:MAX_PROTOCOL_LEN;
        server_end zx.Handle:CHANNEL;
    }) -> () error OperationError;

    /// Connects [server_end] to the [service] directory from this proxy's namespace.
    strict OpenService(resource struct {
        service string:MAX_PROTOCOL_LEN;
        server_end zx.Handle:CHANNEL;
    }) -> () error OperationError;

    /// Connects [server_end] to the [service]/[instance] from this proxy's namespace.
    strict ConnectToServiceInstance(resource struct {
        service string:MAX_PROTOCOL_LEN;
        instance string:MAX_PROTOCOL_LEN;
        server_end zx.Handle:CHANNEL;
    }) -> () error OperationError;
};