lib/src/expect.dart

// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

library matcher.expect;

import 'core_matchers.dart';
import 'description.dart';
import 'interfaces.dart';
import 'util.dart';

/// The objects thrown by the default failure handler.
class TestFailure extends Error {
  final String message;

  TestFailure(this.message);

  String toString() => message;
}

/// Failed matches are reported using a default IFailureHandler.
/// The default implementation simply throws [TestFailure]s;
/// this can be replaced by some other implementation of
/// IFailureHandler by calling configureExpectHandler.
abstract class FailureHandler {
  /// This handles failures given a textual decription
  void fail(String reason);

  /// This handles failures given the actual [value], the [matcher]
  /// the [reason] (argument from [expect]), some additonal [matchState]
  /// generated by the [matcher], and a verbose flag which controls in
  /// some cases how much [matchState] information is used. It will use
  /// these to create a detailed error message (typically by calling
  /// an [ErrorFormatter]) and then call [fail] with this message.
  void failMatch(
      actual, Matcher matcher, String reason, Map matchState, bool verbose);
}

/// The ErrorFormatter type is used for functions that
/// can be used to build up error reports upon [expect] failures.
/// There is one built-in implementation ([defaultErrorFormatter])
/// which is used by the default failure handler. If the failure handler
/// is replaced it may be desirable to replace the [stringDescription]
/// error formatter with another.
typedef String ErrorFormatter(
    actual, Matcher matcher, String reason, Map matchState, bool verbose);

/// This Function is used by certain Matchers to catch certain exceptions.
///
/// Some matchers, like those for Futures and exception testing,
/// can fail in asynchronous sections, and throw exceptions.
/// A user of this library will typically want to catch and handle
/// such exceptions. The [wrapAsync] property is a function that
/// can wrap callbacks used by these Matchers so that they can be
/// used safely. For example, the unittest library will set this
/// to be `expectAsync`. By default this is an identity function.
Function wrapAsync = (Function f, [id]) => f;

/// Assert that [actual] matches [matcher].
///
/// This is the main assertion function. [reason] is optional and is typically
/// not supplied, as a reason is generated from the matcher; if [reason]
/// is included it is appended to the reason generated by the matcher.
///
/// [matcher] can be a value in which case it will be wrapped in an
/// [equals] matcher.
///
/// If the assertion fails, then the default behavior is to throw a
/// [TestFailure], but this behavior can be changed by calling
/// [configureExpectFailureHandler] and providing an alternative handler that
/// implements the [IFailureHandler] interface. It is also possible to
/// pass a [failureHandler] to [expect] as a final parameter for fine-
/// grained control.
///
/// In some cases extra diagnostic info can be produced on failure (for
/// example, stack traces on mismatched exceptions). To enable these,
/// [verbose] should be specified as true;
void expect(actual, matcher,
    {String reason, FailureHandler failureHandler, bool verbose: false}) {
  matcher = wrapMatcher(matcher);
  bool doesMatch;
  var matchState = {};
  try {
    doesMatch = matcher.matches(actual, matchState);
  } catch (e, trace) {
    doesMatch = false;
    if (reason == null) {
      reason = '${(e is String) ? e : e.toString()} at $trace';
    }
  }
  if (!doesMatch) {
    if (failureHandler == null) {
      failureHandler = getOrCreateExpectFailureHandler();
    }
    failureHandler.failMatch(actual, matcher, reason, matchState, verbose);
  }
}

void fail(String message, {FailureHandler failureHandler}) {
  if (failureHandler == null) {
    failureHandler = getOrCreateExpectFailureHandler();
  }
  failureHandler.fail(message);
}

// The handler for failed asserts.
FailureHandler _assertFailureHandler = null;

// The default failure handler that throws [TestFailure]s.
class DefaultFailureHandler implements FailureHandler {
  DefaultFailureHandler() {
    if (_assertErrorFormatter == null) {
      _assertErrorFormatter = _defaultErrorFormatter;
    }
  }
  void fail(String reason) {
    throw new TestFailure(reason);
  }
  void failMatch(
      actual, Matcher matcher, String reason, Map matchState, bool verbose) {
    fail(_assertErrorFormatter(actual, matcher, reason, matchState, verbose));
  }
}

/// Changes the default failure handler for [expect].
///
/// [handler] is a reference to the new handler; if this is omitted
/// or null then the failure handler is reset to the default, which
/// throws [TestFailure]s on [expect] assertion failures.
void configureExpectFailureHandler([FailureHandler handler = null]) {
  if (handler == null) {
    handler = new DefaultFailureHandler();
  }
  _assertFailureHandler = handler;
}

FailureHandler getOrCreateExpectFailureHandler() {
  if (_assertFailureHandler == null) {
    configureExpectFailureHandler();
  }
  return _assertFailureHandler;
}

// The error message formatter for failed asserts.
ErrorFormatter _assertErrorFormatter = null;

// The default error formatter implementation.
String _defaultErrorFormatter(
    actual, Matcher matcher, String reason, Map matchState, bool verbose) {
  var description = new StringDescription();
  description.add('Expected: ').addDescriptionOf(matcher).add('\n');
  description.add('  Actual: ').addDescriptionOf(actual).add('\n');

  var mismatchDescription = new StringDescription();
  matcher.describeMismatch(actual, mismatchDescription, matchState, verbose);

  if (mismatchDescription.length > 0) {
    description.add('   Which: ${mismatchDescription}\n');
  }
  if (reason != null) {
    description.add(reason).add('\n');
  }
  return description.toString();
}

/// Changes the failure message formatter for expect().
///
/// [formatter] is a reference to the new formatter; if this is omitted or
/// null then the failure formatter is reset to the default. The new
/// formatter is returned; this allows custom expect handlers to easily
/// get a reference to the default formatter.
ErrorFormatter configureExpectFormatter([ErrorFormatter formatter = null]) {
  if (formatter == null) {
    formatter = _defaultErrorFormatter;
  }
  return _assertErrorFormatter = formatter;
}