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

using zx;

/// Human-readable name for a test case.
alias Name = string:512;

/// Optional unique tag to identitfy Invocation.
alias Tag = string:512;

/// Describes a single test case.
table Case {
    /// Uniquely identifies a test case within a test suite.
    /// This member is required.
    1: Name name;
    /// Whether the test is enabled or disabled (marked ignored/skipped) by the developer.
    /// If the member is omitted, the test is assumed to be enabled.
    2: bool enabled;
};

/// Represents success, failure, or other possible conditions following a test invocation.
enum Status {
    /// The test passed.
    PASSED = 1;

    /// The test failed.
    FAILED = 2;

    /// The test was skipped.
    /// A skipped status 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;
};

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

    /// Optional tag, arbitrarily specified by clients of `Suite`.
    /// This field is not used by Suite protocol, but passed
    /// back as is by `OnTestCaseStarted`.
    2: Tag tag;
};

/// Optional additional instructions for running test cases.
table RunOptions {
    /// If set to true, test cases that have been disabled by the test author will nonetheless be
    /// executed.
    1: bool include_disabled_tests;

    /// Defines maximum number of test cases to run simultaneously.
    /// If unspecified, the default behavior is chosen by the `Suite`
    /// implementation.
    2: uint16 parallel;

    /// Optional arguments to pass to the test.
    3: vector<string:MAX>:MAX arguments;
};

/// Result of invoking a single test case.
table Result {
    /// This member is required.
    1: Status status;
};

/// Listens to updates from an individual test case run.
protocol CaseListener {
    /// Indicates that an invididual test case has completed and result is
    /// available.
    Finished(Result result);
};

/// Listens to updates from test runs.
protocol RunListener {
    /// Indicates that an individual test invocation has started execution.
    OnTestCaseStarted(Invocation invocation, zx.handle:SOCKET primary_log, request<CaseListener> listener);

    /// Indicates that the last test case that started has finished, and no more test cases will start.
    OnFinished();
};

/// Iterator for listing available test cases.
protocol CaseIterator {
    /// Returns the next batch of test cases.
    GetNext() -> (vector<Case>:MAX cases);
};

[Discoverable]
protocol Suite {
    /// Enumerate the test cases available in this test suite.
    GetTests(request<CaseIterator> iterator);

    /// Run the specified test cases. Results are returned over the results
    /// channel.
    ///
    /// `tests` may contain duplicate elements, in which case the same test is
    /// run multiple times as indicated.
    /// Closing `test_listener` marks the end of this call.
    Run(vector<Invocation>:MAX tests, RunOptions options, RunListener listener);
};