Full Stack BDD in Xcode With Page Object Model: Part I

XCFit 2.0

Glad to announce a new version of XCFit with brand new features. You can find release notes on GitHub here. If you are new to XCFit then XCFit a.k.a (XCUI, Cucumberish, and FitNesse Integrations Tests) is a full stack Xcode BDD framework for Swift iOS and macOS apps. XCFit allows us to write API level, UI and Acceptance Tests with Swift in human readable language using tools like Cucumber and FitNesse in Xcode.

We can still use Apple’s brand new UI Testing framework (XCUI) under the hood of Cucumberish. XCFit is a fully automated solution for Cucumberish and FitNesse. You can use 80(FitNesse):20(Cucumberish) formula to automate Acceptance and UI Testing for better coverage and faster feedback. XCFit is available on RubyGem, CocoaPods, and Swift Package Manager.

XCFit 2.0 Has Just Released!

XCFit 2.0 New Features

• Improved Xcode Templates with support of Page Object Pattern
• New Xcode Target Template to support Page Object Pattern for Apple’s XCUI Test Framework
• Separated Xcode Templates to support both Xcode 7 (Swift 2) and Xcode 8 ( Swift 3). Added Separate option in the XCFit RubyGem to download XCFit Templates for Xcode 8 and Xcode 7.
• Added Helper method to support XCUI Testing and made it available with Swift Package Manager
• Introducing Swift Package Manager for XCFit. It’s available to use with major version 2
• Embedded Stable version of Cucumberish in XCFit and made it available via Cocoapods

XCFit: Step-by-step Guide

• You can now write Given When Then (Gherkin) and Decision Table in Xcode. In Short, you can do BDD in Xcode for your iOS app.
• You can now write/Execute all your Acceptance Tests and UI Tests using Apple’s brand new programming language “Swift” in Xcode. Goodbye Appium, Calabash, Frank, KIF and goodbye Ruby,Java, Python. It’s pure Swift !!
• XCFit provides automated Xcode Target Templates for Cucumberish, FitNesse and Page Object Pattern(XCUI) targets which reduce hectic Xcode configuration steps. It also arranges code in Xcode groups. All happens in one command
• XCFit will setup test frameworks within a minute and works for Xcode 8 and Xcode 7.

XCFit Allows the Following Frameworks

• Cucumberish BDD FrameworkXCFit setup Cucumber style BDD framework with “Cucumberish UI Test Bundle’ Templates
• Page Object Pattern for XCUI Test framework from AppleXCFit setup Page Object Pattern for Apple’s XCUI Test using ‘XCUI POM Test Bundle’ Templates
• Fitnesse Acceptance Tests for iOS using OCSlim ProjectXCFit allows us to setup FitNesse style decision table test framework with OCSlimProject using ‘Acceptance Tests Bundle’ templates.

XCFit Available On

• CocoaPods — XCFit-CocoaPods : BDD Style scenarios for iOS App
• RubyGems — xcfit-RubyGem : Automated Xcode Templates
• Swift Package Manager : 2.0.0 : XCUI Test Framework Helpers

Tech & Software Requirements

XCFit uses a number of open source projects to work properly. You need to have following

Hardware

You must have Mac Operating System with OSX/MacOS version > 10.9

Software

• Ruby
  • Use RVM for GEM management. Ideally Ruby > 2.X. You can use system Ruby with sudo
• Xcode8
  • Ideally Xcode 8 but works on Xcode 7 as well.
• RubyGems
  • RubyGem with Cocoapods installed
• Curl on Mac
  • Might be pre-installed but worth double checking.
• iOS-Sim
  • Node Package required to launch iOS app for Fitnesse Acceptance tests.
• Java
  • Java should be installed on Mac, it is required for Fitnesse Acceptance Test
• Ruby Packages(optional)
  • Xcpretty, Fastlane(Optional), Rake, Bundler, etc.

Installation

Install XCFit Gem

In order to get started, We need to install XCFit from RubyGems. This will set our Xcode for BDD.

$ gem install xcfit

You need to use with ‘sudo’ if you are using system (pre-installed) Ruby(2.0). XCFit gem will be used to set all the Xcode Templated for Xcode 8 as well Xcode 7

Now that you can execute ‘xcfit’ command from your terminal/iTerm, etc., etc. Example Output

Looks like this :

$ xcfit                                                                  
Tasks:
  xcfit get_cucumberish VERSION  
  xcfit get_fitnesse             
  xcfit help [TASK]             
  xcfit set_xcode7_templates     
  xcfit set_xcode_templates

Install XCFit Cocoapod and Swift Package (Covered later)

Later, we need to install XCFit from CocoaPods to enable Cucumberish and Fitnesse test. We can also get XCFit from Swift Package Manager if we need to have additional helpers for the XCUI test framework.

Setup Xcode Templates

In existing app or brand new app, we have to enable the Xcode templates for targets to speed up the things.

Xcode 8

To setup Templates for Xcode 8.

$ xcfit set_xcode_templates

Xcode 7

To setup Templates for Xcode 7.x.

$ xcfit set_xcode7_templates

• This will add a couple of templates to your Xcode for iOS and macOS apps. In your app, if you go to ‘File—>New—>Target’

You will see a new option for iOS i.e ‘XCFit’. Once Clicked on it. You will see Cucumberish UI and Fitnesse Acceptance Tests. XCUI POM, Fitnesse Acceptance Unit Test bundles. As shown

Setting Cucumberish BDD Scenarios in Xcode

Setup ‘iOS UI Cucumberish Test Bundle’ Target

• From Xcode, create a new app(Or use existing app) and select File —> New —-> Target
• Now Select ‘XCFit’ for iOS app and Click on ‘Cucumberish UI Test Bundle’
• Once Clicked on the target e.g ‘Cucumberish UI Test Bundle’ Xcode will create UI testing target with all the required files with Bridging header for Cucumberish UI Testing. It create Page Object Pattern with all required files with screens, steps definitions, and Cucumberish initialiser swift file.

What’s in the Cucumberish Template?

• YOUR_CUCUMBERISH_TARGET.swift
  • This file is at the base of the target. This initiates Cucumberish for a project. We need to register all step definitions in this file.
• Screens
  • This is groups where we can abstract logic of every screen in the app. Example file are ‘HomeScreen.swift’ and ‘BaseScreen.swift’
• Step_Definitions
  • This group has all the step definitions related to screen. Example file ‘HomeScreenSteps.swift’. Once implemented we need to register it in the initializer file mentioned above.
• Common
  • This group has common code like extensions and common steps. The example file ‘CommonStepDefinitions.swift’ has some steps that can be used in the feature file. It also has ‘Hooks.swift’ to add cucumber hooks.
• Supporting Files
  • This groups all the Objective-C headers and Bridging headers needed to get Cucumberish working with Swift.

What’s Not in the Cucumberish Template

• Features Directory
  • We don’t have ‘Features’ directory in the template because it needs to have a directory on the disk and should be added to Xcode as ‘Folder Reference’ not Group.
• Create a Directory called “Feature”
• Now Add sample Gherkin Feature File to ‘Features’ directory either by File->New->Gherkin or just add it using your favorite text editor e.g demo.feature with content

Feature: Demo App Feature   

Scenario: Demo Scenario                             
Given the app isrunning

• Now Drag and Drop ‘Features’ directory to Xcode Cucumberish target
• Select only ‘Create folder references‘ Option. ** Do Not Select ‘Create groups’ Or ‘Copy items if needed’**

Here is how to do it.

• Cucumberish Header Files
  • We still don’t have content of Cucumberish to be included in our project.

Getting Cucumberish Into Our Target

In order to get Cucumberish source content. There are few ways we can do that

• Adding XCFit CocoaPod to Project
  • Create a ‘Podfile’ if you don’t have already. In your Podfile, add following Pod entry and update/install pod

target '$_YOUR_CUCUMBERISH_TARGET' do      
  pod 'XCFit'
end

Now install Pod:

$ pod install

You can do that easily.

Now close the existing Xcode session and Xcode Workspace next time.

Note There is issue with Cocoapods when you have 'use_frameworks!', it will not import header files and build will fail. If you are not using Frameworks in th Podfile then this approach is OK.

• Manually Copy Content of Cucumberish and Drag to Xcode Preferred
  • We can manually copy the content of the Cucumberish directory and drag to target as with option “**Create groups” and “Copy items if needed”.

Here is how to set up everything in a minute !

• Use Carthage without build and drag the folder to target
  • Create a Cartfile with the following Content

github "Ahmed-Ali/Cucumberish"

Now run Carthage without build option.

$ carthage update --platform iOS --no-build

Now in the Carthage/Checkout directory has Cucumberish. Just add that to target or workspace.

Please choose one of the suitable options for you.

We now have everything we needed to run demo Cucumber demo test. Update Scheme if you don’t want to run unit tests or other types of tests. and press ‘CMD+U’

Congratulations !! You have just run your first Cucumber BDD Scenario in the Xcode. Now add your own.

Create Separate Scheme if needed

XCFit adds ‘Cucumberish’ target to existing Scheme. You can remove that target and run separate scheme to keep it independent from Unit tests. Make sure you make the new scheme executable for Running.

XCUI Page Object Pattern

Now, we have seen that it’s fairly easy to setup BDD Style tests with Cucumberish but some people don’t want that overhead of adding an extra layer of Gherkin. XCFit gives an option to use the very popular Page Object Pattern with Apple’s Xcode UI Testing framework.

Stay tuned for Part II, coming soon!