// 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.
using Name = string:512;

/// Optional unique tag to identitfy Invocation.
using 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;
};

/// 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.
    2: Tag tag;
};

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

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