sdk/fidl/fuchsia.test/suite.fidl

// 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.test;

/// Developer-defined human-readable name for a test case.
using Name = string:512;

/// Describes a single test case.
table Case {
    /// Uniquely identifies a test case within a test suite.
    1: Name name;
};

/// Defines the outcome of running a test case.
enum Status {
    /// The test passed.
    PASSED = 1;

    /// The test failed.
    FAILED = 2;

    /// The test was skipped.
    /// A skipped outcome typically indicates that no attempt was made to run
    /// the test.
    ///
    /// Examples:
    /// The test was disabled by the developer.
    /// A precondition for running the test was not satisfied.
    SKIPPED = 3;

    /// The test was inconclusive.
    /// An inconclusive outcome typically indicates a problem that is unrelated
    /// to the subject under test.
    ///
    /// Examples:
    /// The test could not accurately determine whether the intended
    /// behavior was actually observed.
    /// The test was marked as flaky by the developer.
    /// The test was canceled prior to completion.
    /// The test infrastructure needed to run the test was not available.
    /// An unknown error occurred while attempting to run the test.
    INCONCLUSIVE = 4;
};

/// Specification of a test to run.
table Invocation {
    /// Uniquely identifies a test case within a test suite.
    1: Name name;
};

/// Optional additional instructions for running test cases.
table RunOptions {
};

/// Results of invoking a single test case.
table Outcome {
    1: Status status;
};

/// Listens to updates from test runs.
protocol RunListener {
    /// Indicates that an individual test case has started execution.
    /// Provides the primary log stream used by this test case.
    OnTestCaseStarted(Name name, handle<socket> primary_log);

    /// Indicates that an invididual test case has completed and outcome is
    /// available.
    OnTestCaseFinished(Name name, Outcome outcome);
};

[Discoverable]
protocol Suite {
    /// Enumerate the test cases available in this test suite.
    GetTests() -> (vector<Case>:MAX cases);

    /// Run the specified test cases. Results are returned over the results
    /// channel. The Suite is expected to execute tests one at a time in the order
    /// specified. Closing |run_listener| marks end of this call.
    Run(vector<Invocation>:MAX tests, RunOptions options, RunListener listener);
};