Configuration

Configuring Cedar output

Cedar can be configured to output test results in different ways. You can also configure Cedar to add your own custom matchers.

Running iOS tests suites in headless mode

• In older versions of Cedar (prior to 0.9.4), when you run an iOS test suite target, the results are displayed in a UITableView in the simulator by default. If you prefer to have the results output to the console instead, just add the CEDAR_HEADLESS_SPECS to the environment of the spec suite target:
  • Select the spec suite target
  • Edit the scheme (Cmd-<)
  • Select Run > Arguments
  • Add CEDAR_HEADLESS_SPECS to the Environment section.

Running iOS tests suites with an user interface

• In Cedar 0.9.4 and greater, iOS test suite target outputs its results in the console. To have the older behavior displaying test results in a UITableView in the simulator, Add CEDAR_GUI_SPECS to the environment of the spec suite target:
  • Select the spec suite target
  • Edit the scheme (Cmd-<)
  • Select Run > Arguments
  • Add CEDAR_GUI_SPECS to the Environment section.

Finding Slow-Running Tests

Set the CEDAR_REPORT_SLOW_TESTS environment vairables to have Cedar identify and prints out the slowest N (10 by default) tests in your suite, and the slowest N top-level groups. These top-level groups typically have a one to one correspondence with your spec files allowing you to easily identify the slowest running slow files. You can change N by setting the CEDAR_TOP_N_SLOW_TESTS env variable.

Faster Failure Reporting

Set the CEDAR_REPORT_FAILURES_IMMEDIATELY environment variable to have Cedar print failure details before finishing running all tests.

Output Verbosity

When running in headless mode by default Cedar uses CDRDefaultReporter to output test results. Here is how it looks:

.P..P..F

PENDING CDRExample hasChildren should return false by default
PENDING CDRExample hasFocusedExamples should return false by default

FAILURE CDRExample hasChildren should return false
/Users/workspace/cedar/Spec/CDRExampleSpec.mm:149 Expected <NO> to evaluate to true


Finished in 0.0166 seconds
8 examples, 1 failures, 2 pending

Note: For improved Xcode integration see BetterConsole, an Xcode plugin that makes file paths shown in the console clickable.

Most of the time above output is exactly what you want to see; however, in some cases you might actually want to see full names of running examples. You can get more detailed output by setting CEDAR_REPORTER_OPTS env variable to nested. Here is how it looks after that:

   CDRExample
     hasChildren
.      should return false
     isFocused
P      should return false by default
.      should return false when example is not focused
.      should return true when example is focused
     hasFocusedExamples
P      should return false by default
.      should return false when example is not focused
.      should return true when example is focused

PENDING CDRExample hasChildren should return false by default
PENDING CDRExample hasFocusedExamples should return false by default

Finished in 0.0173 seconds
7 examples, 0 failures, 2 pending

Symbolicating Exceptions

By default Cedar does not symbolicate exceptions that caused test failures, since symbolicating many exceptions can become a lengthy operation; however, this feature can be turned on by setting the CEDAR_SYMBOLICATE_EXCEPTIONS environment variable.

Changing output format

If the default reporter for some reason does not fit your needs you can always write a custom reporter. Cedar includes a few built-in ones: CDRColorizedReporter, CDRTeamCityReporter and CDRJUnitXMLReporter. You can tell Cedar which reporter to use by setting CEDAR_REPORTER_CLASS env variable to your custom reporter class name.

Colorized Reporting

CDRColorizedReporter works just like the default reporter, except that it outputs ANSI escape codes to color passing, failing and pending tests as green, red and yellow. If you are running your specs from the command line, output formatted this way can be handy to understand what's currently passing in at a glance.

Team City Reporting

CDRTeamCityReporter outputs test results in a way that TeamCity CI server can understand.

JUnit XML Reporting

The CDRJUnitXMLReporter can be used to generate (simple) JUnit compatible XML that can be read by build servers such as Jenkins. To use this reporter, you can take advantage of the ability to specify multiple reporters like so:

CEDAR_REPORTER_CLASS=CDRColorizedReporter,CDRJUnitXMLReporter

By default, the XML file will be written to build/TEST-Cedar.xml but this path can be overridden with the CEDAR_JUNIT_XML_FILE env variable.

Adding your own custom matchers

Create a header file in your spec target to contain (or include) your custom matchers. If you are adding a matcher for a new type, be sure to also create a Stringifier so that Cedar knows how to correctly describe the instance of that type in a failure message.

Next, go to the "Preprocessor Macros" build setting for your spec target and set CEDAR_CUSTOM_COMPARATORS to your custom matcher header. For example: CEDAR_CUSTOM_COMPARATORS=\"CustomMatchers.h\".

Here's a trivial example of how to add comparison of a CoreMedia type (CMTimeRange) to the existing Equals matcher:

#import <CoreMedia/CoreMedia.h>

#if TARGET_OS_IPHONE
#import <Cedar-iOS/ComparatorsBase.h>
#else
#import <Cedar/ComparatorsBase.h>
#endif

namespace Cedar { namespace Matchers { namespace Comparators {
    template<typename U>
    bool compare_equal(CMTimeRange const actualValue, const U & expectedValue) {
        return CMTimeRangeEqual(actualValue, expectedValue);
    }
}}}

#if TARGET_OS_IPHONE
#import <Cedar-iOS/StringifiersBase.h>
#else
#import <Cedar/StringifiersBase.h>
#endif

namespace Cedar { namespace Matchers { namespace Stringifiers {
    inline NSString * string_for(const CMTimeRange value) {
        return [NSString stringWithFormat:@"%lld/%d (duration %lld/%d)", value.start.value, value.start.timescale, value.duration.value, value.duration.timescale];
    }
}}}

Configuring Test Runs

Specifying random seed

If you want to run with a particular seed, set the CEDAR_RANDOM_SEED environment variable.