LCOV - code coverage report
Current view: top level - test_api-0.4.8/lib/src/backend - live_test.dart (source / functions) Hit Total Coverage
Test: lcov.info Lines: 1 8 12.5 %
Date: 2021-11-28 14:37:50 Functions: 0 0 -

          Line data    Source code
       1             : // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
       2             : // for details. All rights reserved. Use of this source code is governed by a
       3             : // BSD-style license that can be found in the LICENSE file.
       4             : 
       5             : import 'dart:async';
       6             : 
       7             : import 'group.dart';
       8             : import 'message.dart';
       9             : import 'state.dart';
      10             : import 'suite.dart';
      11             : import 'test.dart';
      12             : 
      13             : /// A runnable instance of a test.
      14             : ///
      15             : /// This is distinct from [Test] in order to keep [Test] immutable. Running a
      16             : /// test requires state, and [LiveTest] provides a view of the state of the test
      17             : /// as it runs.
      18             : ///
      19             : /// If the state changes, [state] will be updated before [onStateChange] fires.
      20             : /// Likewise, if an error is caught, it will be added to [errors] before being
      21             : /// emitted via [onError]. If an error causes a state change, [onStateChange]
      22             : /// will fire before [onError]. If an error or other state change causes the
      23             : /// test to complete, [onComplete] will complete after [onStateChange] and
      24             : /// [onError] fire.
      25             : abstract class LiveTest {
      26             :   /// The suite within which this test is being run.
      27             :   Suite get suite;
      28             : 
      29             :   /// The groups within which this test is being run, from the outermost to the
      30             :   /// innermost.
      31             :   ///
      32             :   /// This will always contain at least the implicit top-level group.
      33             :   List<Group> get groups;
      34             : 
      35             :   /// The running test.
      36             :   Test get test;
      37             : 
      38             :   /// The current state of the running test.
      39             :   ///
      40             :   /// This starts as [Status.pending] and [Result.success]. It will be updated
      41             :   /// before [onStateChange] fires.
      42             :   ///
      43             :   /// Note that even if this is marked [Status.complete], the test may still be
      44             :   /// running code asynchronously. A test is considered complete either once it
      45             :   /// hits its first error or when all [expectAsync] callbacks have been called
      46             :   /// and any returned [Future] has completed, but it's possible for further
      47             :   /// processing to happen, which may cause further errors. It's even possible
      48             :   /// for a test that was marked [Status.complete] and [Result.success] to be
      49             :   /// marked as [Result.error] later.
      50             :   State get state;
      51             : 
      52             :   /// Returns whether this test has completed.
      53             :   ///
      54             :   /// This is equivalent to [state.status] being [Status.complete].
      55             :   ///
      56             :   /// Note that even if this returns `true`, the test may still be
      57             :   /// running code asynchronously. A test is considered complete either once it
      58             :   /// hits its first error or when all [expectAsync] callbacks have been called
      59             :   /// and any returned [Future] has completed, but it's possible for further
      60             :   /// processing to happen, which may cause further errors.
      61          44 :   bool get isComplete => state.status == Status.complete;
      62             : 
      63             :   // A stream that emits a new [State] whenever [state] changes.
      64             :   //
      65             :   // This will only ever emit a [State] if it's different than the previous
      66             :   // [state]. It will emit an event after [state] has been updated. Note that
      67             :   // since this is an asynchronous stream, it's possible for [state] not to
      68             :   // match the [State] that it emits within the [Stream.listen] callback.
      69             :   Stream<State> get onStateChange;
      70             : 
      71             :   /// An unmodifiable list of all errors that have been caught while running
      72             :   /// this test.
      73             :   ///
      74             :   /// This will be updated before [onError] fires. These errors are not
      75             :   /// guaranteed to have the same types as when they were thrown; for example,
      76             :   /// they may need to be serialized across isolate boundaries. The stack traces
      77             :   /// will be [Chain]s.
      78             :   List<AsyncError> get errors;
      79             : 
      80             :   /// A stream that emits a new [AsyncError] whenever an error is caught.
      81             :   ///
      82             :   /// This will be emit an event after [errors] is updated. These errors are not
      83             :   /// guaranteed to have the same types as when they were thrown; for example,
      84             :   /// they may need to be serialized across isolate boundaries. The stack traces
      85             :   /// will be [Chain]s.
      86             :   Stream<AsyncError> get onError;
      87             : 
      88             :   /// A stream that emits messages produced by the test.
      89             :   Stream<Message> get onMessage;
      90             : 
      91             :   /// A [Future] that completes once the test is complete.
      92             :   ///
      93             :   /// This will complete after [onStateChange] has fired, and after [onError]
      94             :   /// has fired if the test completes because of an error. It's the same as the
      95             :   /// [Future] returned by [run].
      96             :   ///
      97             :   /// Note that even once this completes, the test may still be running code
      98             :   /// asynchronously. A test is considered complete either once it hits its
      99             :   /// first error or when all [expectAsync] callbacks have been called and any
     100             :   /// returned [Future] has completed, but it's possible for further processing
     101             :   /// to happen, which may cause further errors.
     102             :   Future get onComplete;
     103             : 
     104             :   /// The name of this live test without any group prefixes.
     105           0 :   String get individualName {
     106           0 :     var group = groups.last;
     107           0 :     if (group.name.isEmpty) return test.name;
     108           0 :     if (!test.name.startsWith(group.name)) return test.name;
     109             : 
     110             :     // The test will have the same name as the group for virtual tests created
     111             :     // to represent skipping the entire group.
     112           0 :     if (test.name.length == group.name.length) return '';
     113             : 
     114           0 :     return test.name.substring(group.name.length + 1);
     115             :   }
     116             : 
     117             :   /// Loads a copy of this [LiveTest] that's able to be run again.
     118           0 :   LiveTest copy() => test.load(suite, groups: groups);
     119             : 
     120             :   /// Signals that this test should start running as soon as possible.
     121             :   ///
     122             :   /// A test may not start running immediately for various reasons specific to
     123             :   /// the means by which it's defined. Until it starts running, [state] will
     124             :   /// continue to be marked [Status.pending].
     125             :   ///
     126             :   /// This returns the same [Future] as [onComplete]. It may not be called more
     127             :   /// than once.
     128             :   Future run();
     129             : 
     130             :   /// Signals that this test should stop emitting events and release any
     131             :   /// resources it may have allocated.
     132             :   ///
     133             :   /// Once [close] is called, [onComplete] will complete if it hasn't already
     134             :   /// and [onStateChange] and [onError] will close immediately. This means that,
     135             :   /// if the test was running at the time [close] is called, it will never emit
     136             :   /// a [Status.complete] state-change event. Once a test is closed, [expect]
     137             :   /// and [expectAsync] will throw a [ClosedException] to help the test
     138             :   /// terminate as quickly as possible.
     139             :   ///
     140             :   /// This doesn't automatically happen after the test completes because there
     141             :   /// may be more asynchronous work going on in the background that could
     142             :   /// produce new errors.
     143             :   ///
     144             :   /// Returns a [Future] that completes once all resources are released *and*
     145             :   /// the test has completed. This allows the caller to wait until the test's
     146             :   /// tear-down logic has run.
     147             :   Future close();
     148             : }

Generated by: LCOV version 1.14