Sleipnir

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 835)

BDD-style framework for Swift

Sleipnir Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Sleipnir

Sleipnir is a BDD-style framework for Swift. Sleipnir is highly inspired by [Cedar](https://github.com/pivotal/cedar). 
Also
> In Norse mythology, [Sleipnir](http://en.wikipedia.org/wiki/Sleipnir) is Odin's steed, is the child of Loki and Svaðilfari, is described as the best of all horses, and is sometimes ridden to the location of Hel. 
  
```swift
class SampleSpec : SleipnirSpec {
    var spec : () = describe("Horse") {
        context("usual") {
            it("is not awesome") {
                let usualHorse = UsualHorse()
                usualHorse.legsCount.should.equal(4)
                expect(usualHorse.isAwesome()).to(beFalse())
            }
        }
        
        context("Sleipnir") {
            it("is awesome") {
                let sleipnirHorse = Sleipnir()
                sleipnirHorse.legsCount.should.equal(8)
                expect(sleipnirHorse.isAwesome()).to(beTrue())
            }
        }
    }
}
```
## Core principles

* Sleipnir is not dependent of ```NSObject```, it is pure Swift BDD testing framework
* Sleipnir is not using ```XCTest```
* Sleipnir has nice command line output and support for custom test reporters
* Other features, like seeded random tests invocation, focused and excluded examples/groups, etc.

## Installation

#### Manually (preferred way)

1. Add Sleipnir as a submodule: `git submodule add https://github.com/railsware/sleipnir ThirdParty/Sleipnir`
2. Drag'n'drop `Sleipnir.xcodeproj` to your test target
3. Link `Sleipnir.framework`
4. Start writing specs!

#### Manually (from XCode Project template)

1. Clone `Sleipnir` repo `git clone https://github.com/railsware/sleipnir /tmp/Sleipnir`
2. Execute the following command `cd /tmp/Sleipnir && make install_templates`

The command will install templates for OSX and iOS projects and Spec file template as well.

**Note:** this way you should manage framework updates on your own. Try to reinstall templates before creating new project/target from "old" ones

#### Via CocoaPods

You can install statically built `Sleipnir.framework` into you project simply by adding it to the `Podfile`

```
pod 'Sleipnir'
```

**Note: it is experimental way** 
**Current build does not work on iPhone Simulator, but works for OSX and iOS Devices**

## Usage sample

See [LibrarySpec](https://github.com/railsware/Sleipnir/blob/master/Sample/Sample/LibrarySpec.swift) file in [Sample](https://github.com/railsware/Sleipnir/tree/master/Sample/Sample) project.

## Writing specs

All spec classes should inherit from `SleipnirSpec`.

Root ExampleGroups in a spec should be assigned to some void variable. This allows specs to initialize correctly:
```swift
import Sleipnir

class SomeSpec : SleipnirSpec {
 
    let someSpec : () = describe("Some spec") {
        it("should pass") {
            expect(1).to(equal(1))
        }
    }
    
}
```
## Running specs

In order to run your specs you should invoke `Runner.run()` from the `main.swift` of your test target.

The default test runner will produce the following command line output, indicating all the failures and some meta information about each failure:
```
Running With Random Seed: 1234

.....F..

FAILURE Some spec should pass:
/Path/To/Your/Specs/TestSpec.swift:16 Expected <1> to equal <2>

Finished in 0.0075 seconds

8 examples, 1 failures
```

#### Seeded random specs run

All examples would run in random order with the random seed specified in output. If you would like to re-run tests in the same order you should pass a seed to `run()` method:
```swift
Runner.run(seed: 1234)
```

## Examples and ExampleGroups

ExampleGroups are created with `describe` or `context` keywords.
Within the block passed to ExampleGroup you can declare examples using the `it` keyword.

ExampleGroups can be nested in order to create clean structure of your tests.

Under the hood `describe` method creates an instance of `ExampleGroup` and evaluates the block passed to it. Blocks passed to examples are evaluated dynamically during the test execution.

## Setup/Teardown code

Sleipnir supports some hooks to execute before or after examples. This allows to share some setup/teardown code between examples.

`beforeEach` block will be executed before each example in the current group and all nested groups.

`afterEach` block will be executed after each example.

```swift
class SomeSpec : SleipnirSpec {
 
    let someSpec : () = describe("Some spec") {
        var someArray: [Int]?
        beforeEach {
            someArray = [1, 2, 3]
        }
        
        afterEach {
            someArray = nil
        }
        
        it("should pass") {
            expect(someArray).toNot(beNil())
            expect(someArray).to(contain(3))
        }
    }
    
}
```
You can also specify global setup/teardown blocks using `beforeAll` and `afterAll` keywords. 
They will run once before or after all examples in the current group and all the nested groups.

## Focused and excluded specs

You can specify examples and example groups to be focused by placing `f` letter before declaration: `fdescribe`, `fcontext`, `fit`. In this case the spec runner will only run focused examples/example groups and ignore all the others.

You can also mark an example or example group as `pending`. It won't run but will be printed along with the test results. 
To mark something as `pending` add an `x` letter before declaration: `xdescribe`, `xcontext`, `xit`. 
Example can also be marked as `pending` by passing `PENDING` instead of spec block: 
```swift
it("is pending", PENDING)
```
## Shared example groups

Sleipnir supports extracting common specs through shared example groups. 
They can include any number of `it`, `context`, `describe`, `before` and `after` blocks. 
You can pass example-specific state into the shared example group through `sharedContext` dictionary.
```swift
var nonNilObject : () =
 sharedExamplesFor("a non-nil object") { (sharedContext : SharedContext) in
 var object: AnyObject?
 beforeEach {
 object = sharedContext()["object"]
 }
 
 it("should not be nil") {
 expect(object).toNot(beNil())
 }
 }

var spec : () = context("A non-nil object") {
    let someObject: String = "Some Object"
    itShouldBehaveLike("a non-nil object", { ["object" : someObject] })
}
```

If you don't need any context, you can use closures without parameters:
```swift
sharedExamplesFor("some awesome stuff") {
    it("should be awesome") {
        //...
    }
}

describe("Some stuff") {
    itShouldBehaveLike("some awesome stuff")
}
```

## Expectations

Sleipnir supports defining expectations using `expect(someValue/expession).to(SomeMatcher)` syntax.
```swift
expect(true).to(beTrue())
```
`expect` method supports passing values or a block of code in a closure:
```swift
expect {
    var x = 1
    x++
    return x
}.to(equal(2))
```

### `Should` syntax

In addition to the `expect` syntax, Sleipnir supports the `should` syntax:
```swift
actual.should.equal(expected)
[1, 2, 3].shouldNot.contain(4)
```
[See detailed information on the `should` syntax and its usage](https://github.com/railsware/Sleipnir/blob/master/ShouldSyntax.md)

## Available matchers

##### Equal
Values must be [`Equatable`](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/SwiftStandardLibraryReference/Equatable.html), [`Comparable`](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/SwiftStandardLibraryReference/Comparable.html) or derive from `NSObject`.
```swift
expect([1,2,3]).to(equal([1,2,3]))
expect("some string").toNot(equal("another string"))
expect(1) == 1
```

##### BeNil
```swift
expect(nil).to(beNil())
expect("some string").toNot(beNil())
```

##### BeTrue/BeFalse
```swift
expect(true).to(beTrue())
expect(false).to(beFalse())
```

##### BeGreaterThan/BeLessThan
Values must be [`Comparable`](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/SwiftStandardLibraryReference/Comparable.html).
```swift
expect(3).to(beGreaterThan(1))
expect(3) > 1

expect(1).to(beLessThan(3))
expect(1) < 3
```

##### BeGreaterThanOrEqualTo/BeLessThanOrEqualTo
Values must be [`Comparable`](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/SwiftStandardLibraryReference/Comparable.html).
```swift
expect(3).to(beGreaterThanOrEqualTo(1))
expect(3) >= 1
expect(1) >= 1

expect(1).to(beLessThanOrEqualTo(3))
expect(1) <= 3
expect(1) <= 1
```

##### Collections/String matchers
Sleipnir supports some matchers on collections and strings:

##### Contain
Matches if an item is in the container. Supports Swift collections with [`Equatable`](https://developer.apple.com/library/prerelease/ios/documentation/General/Reference/SwiftStandardLibraryReference/Equatable.html) elements, `NSArrays`, `NSSets` and `Strings`.
```swift
expect([1,2,3]).to(contain(1))
expect("some string").toNot(contain("another"))
```

##### BeginWith/EndWith
Matches if the container begins/ends with the specified element. Supports Swift collections with `Equatable` elements, `NSArrays` and `Strings`.
```swift
expect([1,2,3]).to(beginWith(1))
expect("some string").to(endWith("string"))
```

##### BeEmpty
Matches if a container is empty.
```swift
expect("").to(beEmpty())
expect([1,2,3]).toNot(beEmpty())
```

## TODO

- [x] Ease of distribution (CocoaPods probably)
- [x] XCode templates
- [x] Shared examples support
- [x] ```should``` syntax support
- [ ] asynchronous matchers (```will```, ```willNot```, ```after```)

## Who uses Sleipnir

- [SGL](https://github.com/AlexDenisov/sgl) - Swift Generic Library

## Contributing

Please read the [Contributor Guide](https://github.com/railsware/Sleipnir/blob/master/CONTRIBUTING.md).

## License

Licensed under MIT license. See the [LICENSE](https://github.com/railsware/Sleipnir/blob/master/LICENSE) file for details.

Sleipnir

Sleipnir Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Sleipnir

Sleipnir Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README