Capriccio

Capriccio is a tool to generate UI Tests from gherkins .feature files.

Capriccio generates test files using XCTest-Gherkin by default, but can use your own Stencil template :)

An example of how it works

If you have a feature files like

Feature: Feature number one

Scenario: Scenario I want to  test
Given I'm in a situation
When something happens
Then something else happens

Scenario: Other scenario I want to  test
Given I'm in another situation
When something different happens
Then something else happens

It generates:

import XCTest
import XCTest_Gherkin

final class FeatureNumberOne: XCTestCase {
    func testScenarioIWantToTest() {
        Given("I'm in a situation")
        When("Something happens")
        Then("Something else happens")
    }

    func testOtherScenarioIWantToTest() {
        Given("I'm in another situation")
        When("Something different happens")
        Then("Something else happens")
    }
}

What is the benefit of using Capriccio?

Gherkin feature files can be easly shared between different platform. With Capriccio you to generate executable code from the feature files on a specific folder, all you have to do is run Capriccio as part of your build process (For example in a script phase).

Runtime vs Compile time

There a lot of different tools that allows to run tests from a feature files, like Cumberish or XCTest-Gherkin. But they generates the tests at runtime. By generating the tests at compile time you get some benefits:

You can use the navigator to see, inspect and re run the tests
You have a better integration with some CI services
You can actually see the generated test code

How to use it

to use it just run:

capriccio source destination <option>

source The path to the folder that contains the feature files destination The path to the folder where the swift files will be generated

Command line options

--excluded-tags - The list of excluded tags separated by a comma
--included-tags - The list of included tags separated by a comma
--class-type [default: XCTestCase] - The class type of the generated class
--single-file - Generates a single swift file with the content of all the feature files
--disable-swiflint - Disables swiftlint on the file
--template-file - Path to the stencil template file

Configuration file

Instead of CLI arguments you can use .capriccio.yml configuration file:

source: <source path>
output: <destination path>
template: <template path>
excludedTags:
    - <string value>
    - <string value>
includedTags:
    - <string value>
    - <string value>
classType: <string value>
singleFile: <bool value>
disableSwiftLint: <bool value>

Personalise setUp and tearDown

Your UI Tests will probably need to do something that is specific to your code base before and after every test. In order to allow Capriccio to support all this needs you can use the -c or --class-type option. This allows you to create a generic class that you can use as superclass for all the generated classes.

e.g.

class GherkinTestCase: XCTestCase {
    var mockedServer: MockedServer
    var stepDefinition: StepDefinitions!
    var application: App!

    override func setUp() {
        super.setUp()
        mockedServer = MockedServer()
        mockedServer.start()
        
        stepDefinition = StepDefinitions(testCase: self)

        application = App()
        application.launch()
    }

    override func tearDown() {
        mockedServer.stop()
        application.terminate()
        super.tearDown()
    }
}

Then if you run:

capriccio source destination -c GherkinTestCase

All the generated classes will be a subclass of GherkinTestCase instead of a subclass of XCTestCase

Scenario outline

Capriccio creates a different test for each example.

e.g.

Feature: Feature number one

Scenario Outline: Scenario I want to  test
Given I'm in a situation
When something happens <key1>
Then something else happens <key2>
Examples:
| key1 | key2 |
| value1 | value2 |
| value3 | value4 |

Generates:

import XCTest
import XCTest_Gherkin

final class FeatureNumberOne: XCTestCase {
    func testScenarioIWantToTestWithValue1AndValue2() {
        Given("I'm in a situation")
        When("Something happens value1")
        Then("Something else happens value2")
    }
        
    func testScenarioIWantToTestWithValue3AndValue4() {
        Given("I'm in a situation")
        When("Something happens value3")
        Then("Something else happens value4")
    }
}

Create your own template

Check our Model class to see which properties you can use on your Stencil template.

shibapm / capriccio