Nimble v5.1.1

This release is only a bugfix release.

• Fixes umbrella header import for macOS and tvOS

Nimble v5.1.0

This release includes new features and shouldn't break backwards compatibility
with 5.0.0. Thus, 5.1.0 supports Swift 3 / Xcode 8. The TL;DR list of changes:

New Features:

• Add throwAssertion matcher to test precondition failures. Thanks @mattgallagher and @abbeycode!
• Objective-C supports some C literals

Fixes:

• The regular expression match matcher is available for Linux. Thanks @ikesyo!
• Document about AsyncDefaults. Thanks @wongzigii!
• Fix matchError incorrectly succeeding on any Error type given.

New Feature Details

ThrowAssertion Matcher

Nimble now includes a throwAssertion matcher to test if a given piece of code
fails precondition or invokes fatalError.

// swift
expect { precondition(false, "this will fail") }.to(throwAssertion())
// type-hint that this closure does not return anything
expect { () -> Void in fatalError() }.to(throwAssertion())

Due to the inherit implementation of preconditions and fatalErrors, there are
several limitations:

• This is only available for Swift.
• There is no validation of the failure message.
• This only works for x86 architectures. This means Simulators + macOS only.
• tvOS simulator requires you to disable "Debug executable" in your scheme's test configuration.

Nimble embeds CwlPreconditionTesting to implement throwAssertion. Special
thanks to @mattgallagher for CwlPreconditionTesting and @abbeycode for the bulk
of the adding the matcher for Nimble.

Go test those assertions!

Objective-C: Limited C-Literals Support

Objective-C version of Nimble now can automatically box certain C types for
you. This means you don't need to wrap them yourself:

// objective-c
expect(1).to(equal(2));
expect(98.6).to(beCloseTo(98.6));
expect(YES).to(beTrue());
expect(@[@1, @2]).to(haveCount(2));
expect("hello").toNot(equal("world"));
expect(NSMakeRange(0, 5)).to(equal(NSMakeRange(0, 5)));

Currently, not all matchers support all types. The following matchers support C types:

• equal
• beGreaterThan
• beGreaterThanOrEqual
• beLessThan
• beLessThanOrEqual
• beCloseTo
• beTrue
• beFalse
• beTruthy
• beFalsy
• haveCount

The C types each supports is matcher specific. But there's here's the basic heuristics:

• C numeric types are boxed as NSNumber *. (eg - uint64_t -> NSNumber *)
• C booleans are boxed as NSNumber *. (eg - BOOL -> NSNumber *)
• C strings are boxed as NSString * (eg - char * -> NSString *)
• NSRange are boxed as NSValue * (eg - NSRange -> NSValue *)

While they shouldn't cause too many suprises in practice, note that you still
can have some gotchas with everything boxing as NSNumber * (eg -
expect(1).to(beTrue()) passes).

Please file an issue if you want more matchers.

---

Happy testing! 😁

Nimble v5.0.0

Version 5 supports Swift 3. For older versions of swift, please use an older version of Nimble.

Features / Breaking Changes:

• Convert to Swift 3
• Change NMBOrderedCollection to use -[objectForIndex:] / object(at index: Int). See bugfix.
• beCloseTo supports CGFloat

Bugfixes:

• Fix endsWith matcher not working if the expected value was repeated
  multiple times for strings and NMBOrderedCollection-conforming types.

Special thanks to @NachoSoto, @andersio, @briancroom, @ikesyo, @liscio,
@mokagio, @norio-nomura, @raphaelcruzeiro for all the effort in getting
Nimble to Swift 3!

v4.1.0

v4.1.0

Added:

• NSDate is now supported when using the beCloseTo & beCloseWithin matchers (#295 - thanks @mishimay!).
• Expectation's expression property is now public, for use when creating custom matchers (#300 - thanks @akashivskyy!).

Improved:

• The contain matcher now accepts sequences, in addition to the existing variadic form (#297 - thanks @stigi!).
• The documentation for beIdenticalTo has been improved (#299 - thanks @lukeredpath!).

Fixed:

• Bitcode is now disabled for the tvOS platform (#287 - thanks @phatblat!).
• Nimble can now be compiled under Xcode 8 with Swift 2.3 (#302). Swift 3 support will be part of a future release.

v4.0.1

Bug Fixes

• Fixes a race condition in Xcode 7.3 that would prevent Nimble from writing output to the Xcode console during a test run. See #273.
• Fixes a problem with CocoaPods integration concerning header files that can't be found. See #280.

v4.0.0

Breaking Changes

• Remove FullMatcherFunc. Use Matcher or MatcherFunc instead. More
  breaking changes around the protocols will probably occur in the future.

Features

• beEmpty() supports NSIndexSet
• Expose stringify() which Nimble matchers use to convert values to string.
  • You can add custom support to stringify by conforming your type to
    TestDebugStringConvertible

Bug Fixes

• Fix bug where exceptions weren't properly caught for cocoapods users
• Resolve warnings for Xcode 7.3

Nimble v3.2.0

Nimble v3.2.0

This release includes bug fixes, minor enhancements, and a couple of new matchers. This release targets Xcode 7.2.x and Swift 2.1. It also generally works with Xcode 7.3 betas and Swift 2.2 (thanks @NachoSoto!), although many deprecation warnings are emitted.

Additionally, initial support is available for using Nimble with the Swift Package Manager on both OS X and Linux. This should be considered a technical preview as SwiftPM and the do not yet have any stable releases.

New Matcher: postNotifications

This matcher allows testing that an expression causes one or more NSNotifications to be posted to a notification center. Thanks to @bgerstle for this work! (#228)

expect {
    NSNotificationCenter.defaultCenter().postNotification(myNotification)
}.to(postNotifications(equal([myNotification]))

New Matcher: beVoid

This matcher allows testing whether an optional value of type Void? contains a value, or is nil. Thanks to @inamiy for this! (#250)

expect(() as ()?).to(beVoid())

Asynchronous Expectation Defaults

It is now possible to modify the global default values for the timeout and poll interval used by toEventually. Thanks @mjbeauregard! (#256)

AsyncDefaults.Timeout = 2
AsyncDefaults.PollInterval = 0.05

Swift Package Manager

It is now possible to reference Nimble as a package dependency in a Package.swift file for use with the Swift Package Manager. As SwiftPM is not yet stable, this integration should be considered an early preview and may break.

Linux Support

Complementing SwiftPM support, Nimble can now be used on Linux, with the caveat that not all behaviors and matchers are supported. Features that rely on the Objective-C runtime are disabled in this environment. On Linux, Nimble integrates with the swift-corelibs-xctest library.

Miscellaneous

• be can now be used as an alias for the beIdenticalTo matcher. Thanks @jwfriese! (#241)
• The compiler will now produce a warning if expect is used without being followed up by to, toNot, etc. Thanks @pcantrell! (#245)
• NSData now has a special string representation to prevent failure messages from including excessively long data descriptions. Thanks @inket! (#263)

Nimble v3.1.0

This is a bug fix + feature addition release. Thanks to @jwfriese for the work in this release.

Note that this release does not include a pre-built binary for Carthage. Xcode doesn't gaurantee binary compatibility for pre-built frameworks. See more details: Carthage/Carthage#924.

On to the changes...

New Matcher: || (aka - satisfyAnyOf)

Matchers can be combined using the || operator:

expect(value).to(equal(2) || equal(3))

This expects value to be either 2 or 3. Using || can be useful in complex expectations or integration tests, where less-specific expectations are usually utilized.

Warning: Conditionals in expectations are generally considered bad practice. Using || is a form of conditional that weakens the strength of the assertion. This matcher should be used sparingly if at all.

Updated Matcher: Equals + Optional Collections

Equals now supports optional collections:

let a: [String?] = ["a", "b", nil]
let b: [String?] = ["a", "b", nil]

expect(a).to(equal(b))

Previously, the above code caused a compiler error. Now this will work like non-optional collection types.

Asynchronous Expectations

Async expectations have been rewritten to reduce flakiness. The public API remains the same but uses lower-level features to avoid complex interactions with common run loop features.

Async expectations are any waitUntil or expect(..).toEventually(..) forms.

Also, Nimble emits errors on invalid usages of async expectations:

• Async expectations must be done on the main thread.
• Async expectations cannot be nested.

This is because async requires controlling the main run loop. These limitations were part of the old implementation, but left the test writer to discover them via flaky tests. The new implementation will immediately fail.

Nimble v3.0.0

This release supports Xcode 7.1 with better tvOS support.

Changes:

• tvOS is a separate build target from iOS.
• updated import headers to be relative from module-based for Xcode 7.1
• revert waitUntil variadic completion function to avoid ambiguities for some edge cases
• fix haveCount matcher's expected and actual values reversed in expectation message

Nimble v2.0.0

This release is compatible with Xcode 7.0 (Swift 2.0). If you're looking for the swift-2.0 branch, it is now the master branch.

Breaking Changes from RCs

There's one breaking changes besides the upgrade to Swift 2.0 if you haven't be using the release candidates.

Weak Linking to XCTest

Nimble is now weakly linked to XCTest. If you're not explicitly linking to XCTest (either via import or explicitly linking frameworks), you must now do so or else XCTest may not be automatically linked into your project. The default behavior of test bundles will link XCTest correctly.

The README documents using Nimble without XCTest, if you choose to integrate Nimble to your own test runner or framework.

Changes from RCs

• Added tvOS support
• Added haveCount matcher which is a convenience to check for length.
• Added NSMapTable support for beEmpty. haveCount also supports
  NSMapTable.
• Fix warning of missing reference to $SDKROOT/Developer/Library/Frameworks
• waitUntil's done argument now accepts variadic arguments to allow passing
  directly to completion blocks that requires other arguments.

Past Release Candidate Changes

For convenience, here's the list of changes between the release candidates to 1.x.x versions.

Backwards Incompatible Changes

• Backwards incompatible changes for Swift 2.0
• swift: Expectations now properly handle the new Swift error handling syntax.
  This means expectations implicitly allow throws and will fail with a useful
  error message if a closure throws one:

expect { try throwError() }.to(equal(1)) // Failed - Expected to equal 1, got an unexpected error thrown: ...

• objc: expectAction() is now a macro that requires an Objective-C block instead of building an implicit block:

Old:

expectAction([obj raiseException]).to(raiseException(...));

New:

expectAction(^{ [obj raiseException]; }).to(raiseException(...));

Changes in Release Candidates

• beEmpty() matcher is now defined specifically for String
• beCloseTo now works with NSDate without having to convert it
• Cocoapod users can now run Nimble in devices
• objc: Added fail() and failWithMessage() functions
• You can now specify custom error messages for expectations. This is useful
  for large integration tests, where an expectation is usually a sanity check to
  a larger operation:

expect(1).to(equal(2), description: "Just checking equality!") // failed - Just checking equality!

• swift: Fixed ≈ precedence
• swift: beAKindOf() and beAnInstanceOf() emits useful errors when trying to
  compare against Swift Types. This is not allowed in Nimble because the Swift
  compiler already enforces this.
• swift: Added throwError() matcher for verifying the behavior of closures that throw an error:

expect { try somethingDangerous() }.to(throwError())

• objc: NMBObjCMatcher initializers are now public
• objc: contain() matcher now accepts variadic arguments. Each value passed to contain() is expected to be in the container:

expect(@[@1, @2, @3]).to(contain(@1, @2)); // passes