Close Menu

nimble

Nimble is a powerful and flexible matcher framework for Swift. It provides a highly readable and expressive way to define and test conditions. With Nimble, you can easily write concise and precise assertions.

Key Features

  • Expressive matchers for defining conditions and expectations
  • Powerful assertion model for writing clear and readable tests
  • Custom matchers to extend the functionality of Nimble
  • Swift and Objective-C compatibility
  • Support for asynchronous testing

Installation

To install Nimble using CocoaPods, simply add the following line to your “Podfile”:

pod 'Nimble'

To install Nimble using Carthage, add the following line to your Cartfile:

github "Quick/Nimble"

Getting Started

Once you have Nimble installed, you can start using it in your tests. Here’s a basic example of how to use Nimble matchers:

// Import Nimble
import Nimble

// Example test case
describe("Calculator") {
    it("should add two numbers correctly") {
        // Arrange
        let calculator = Calculator()
        
        // Act
        let result = calculator.add(2, 3)
        
        // Assert
        expect(result).to(equal(5))
    }
}

Available Matchers

Nimble provides a wide range of matchers to help you define conditions and expectations in your tests. Some of the commonly used matchers include:

  • equal: checks if two values are equal
  • beGreaterThan: checks if a value is greater than another value
  • beLessThan: checks if a value is less than another value
  • beCloseTo: checks if a value is close to another value
  • contain: checks if a collection contains an element
  • beNil: checks if a value is nil
  • beTrue: checks if a value is true
  • beFalse: checks if a value is false

For a full list of available matchers and their usage, refer to the Nimble GitHub page.

Custom Matchers

If the built-in matchers don’t cover your specific needs, you can easily create your own custom matchers. Nimble provides a flexible and extensible API for defining custom matchers. Here’s an example of how to define and use a custom matcher:

// Define a custom matcher
let beDivisibleBy = Matcher<Int>("be divisible by") { actualExpression, failureMessage in
    let actual = try actualExpression.evaluate()
    failureMessage.postfixMessage = "be divisible by <\(expected)>"
    return actual % expected == 0
}

// Use the custom matcher in a test
expect(10).to(beDivisibleBy(2))

For more details on creating custom matchers, consult the Nimble documentation.

Asynchronous Testing

Nimble provides excellent support for writing tests that involve asynchronous operations. You can use the waitForExpectations method to wait for expectations to be fulfilled within a specified timeout. Here’s an example of how to perform asynchronous testing with Nimble:

let expectation = XCTestExpectation(description: "Async Operation")
        
DispatchQueue.global().async {
    // Perform asynchronous operation
        
    DispatchQueue.main.async {
        // Fulfill expectation once asynchronous operation is complete
        expectation.fulfill()
    }
}
        
waitForExpectations(timeout: 5) { error in
    // Handle timeout or test failure
    XCTAssertNil(error, "Timeout occurred")
}

For more information on writing asynchronous tests with Nimble, refer to the official documentation.

Conclusion

Nimble is a powerful matcher framework that simplifies testing in Swift. It provides expressive matchers, a versatile assertion model, and support for custom and asynchronous testing. With Nimble, you can write clear and precise assertions, making your tests more readable and easier to maintain.