adevintaspain / sencha

A library to facilitate UI tests using EarlGrey, with a more developer-friendly API.

ℹ️ Sencha was originally intended to work with EarlGrey under the hood, since they released EarlGrey 2.0, white box testing is no longer supported. This is why EarlGrey has been replaced by KIF. Regardless of that, Sencha API is still the same and it works without modification.

EarlGrey is a great tool to test our iOS apps via instrumental tests. With them, we can mimic user actions like tapping a button, scrolling, or typing. Then, we can assert that a text appears in the screen, a view is visible or invisible, or a button is enabled or not.

On the other hand, if you tried EarlGrey, you’ll agree that its API is not discoverable or friendly.

Sencha introduces a discoverable API for the EarlGrey features. So, you and all the iOS team will write instrumental tests with no effort.

Benefits of using EarlGrey (via Sencha) over other UI testing libraries:

• From EarlGrey's own README:

EarlGrey’s synchronization features help to ensure that the UI is in a steady state before actions are performed. This greatly increases test stability and makes tests highly repeatable.

• Thanks to the strict behaviour of EarlGrey's matchers, you may discover some retain cycles in the UI code of your application. Eg: if your application is leaking a view that is being tested, EarlGrey will launch a "multiple elements found" exception (kGREYMultipleElementsFoundException) as soon as more than one instance of the same view is found in memory.

• Unlike with Apple's own XCUITest framework you will be able to interact with your application's code in order to mock/stub any dependency.

Installation

Cocoapods

EarlGrey installation instructions are unconventional to say the least. They require you to install a gem that, in turn, monkey patches your local cocoapods gem (!) to perform some changes every time a pod install is invoked in your system.

We have found that there is no need to do that, and that's why in order to install Sencha (and with it, EarlGrey) you only need to create a unit test target and add the following line to your Podfile under the dependencies of your new target:

pod 'Sencha'

That's it!

Sencha's assertions

For elements in regular UIs:

assertVisible(.text("EmptyStateText"))
assertVisible(.accessibilityID("EmptyStateID"))
assertVisible(.class(UIActivityIndicator.class))

assertNotVisible(.text("EmptyStateText"))

Note: The previous assertions won't work for elements inside a ScrollView, for that you'll need the ones in the next section.

For elements inside a ScrollView(also TableView & CollectionView):

assertVisible(.text("EmptyStateText"), inScrollableElementWith: .accessibilityID("TableViewID"))
assertVisible(.text("EmptyStateText"), inScrollableElementWith: .accessibilityID("RegularScrollViewID"))

assertNotVisible(.text("EmptyStateText"), inScrollableElementWith: .accessibilityID("TableViewID"))

Verifying TableView content

assert(tableViewWith: .accessibilityID("TableViewID"), hasRowCount: 30)
assert(tableViewWith: .accessibilityID("TableViewID"), hasRowCount: 30, inSection: 1)
assert(tableViewWith: .accessibilityID("TableViewID"), hasSectionCount: 2)
assertTableViewIsEmpty(with: .accessibilityID("TableViewID"))
assertTableViewIsNotEmpty(with: .accessibilityID("TableViewID"))

Verifying CollectionView content

assert(collectionViewWith: .accessibilityID("CollectionViewID"), hasCellCount: 30)
assert(collectionViewWith: .accessibilityID("CollectionViewID"), hasCellCount: 30, inSection: 1)
assert(collectionViewWith: .accessibilityID("CollectionViewID"), hasSectionCount: 2)
assertCollectionViewIsEmpty(with: .accessibilityID("CollectionViewID"))
assertCollectionViewIsNotEmpty(with: .accessibilityID("CollectionViewID"))

Verifying Switch state

assertSwitchIsOn(.accessibilityID("SwitchID"))
assertSwitchIsOff(.accessibilityID("SwitchID"))
 

Verifying Slider value

assertSlider(.accessibilityID("SliderID"), hasValue: .equalTo(0.5))
assertSlider(.accessibilityID("SliderID"), hasValue: .greaterThan(0.0))
assertSlider(.accessibilityID("SliderID"), hasValue: .lessThan(1.0))

Verifying Picker value

assertPicker(.accessibilityID("pickerID"), hasValue: Date())
assertPicker(.accessibilityID("pickerID"), hasValue: "10", inColumn: 1)

Sencha's actions

You can also use actions to move the content where it is visible, note that these are not assertions, and thus, don't consititute a test, they are just modifiers to the state of the UI.

Tapping

tap(.accessibilityID("AnythingTappableID"))
tap(.text("ButtonTitle"))

tap(.text("CellTitle"), inScrollableElementWith: .accessibilityID("TableViewID"))

//Tapping the back button contained in a UINavigationBar when using push navigation mode
tapBackButton()

Scrolling

scrollTo(.accessibilityID("AnythingTappableID"), inElementWith: .accessibilityID("TableViewID"))
scrollToBottom(in: .accessibilityID("TableViewID"))
scrollToTop(in: .accessibilityID("TableViewID"))
scrollToLeft(in: .accessibilityID("TableViewID"))
scrollToRight(in: .accessibilityID("TableViewID"))

Text actions

⚠️ Use this method if you need the delegate methods of the text input to be triggered (otherwise use insertText below) This method uses the simulator's keyboard to type, and depending on the text it might fail.

type("Username", inElementWith: .accessibilityID("UsernameTextFieldID"))

⚠️ Use this method if you don't need the delegate methods of the text input to be triggered.

insertText("Username", inElementWith: .accessibilityID("UsernameTextFieldID"))

clearTextInElement(.accessibilityID("UsernameTextFieldID"))

Interacting with the keyboard

tapKeyboardReturnKey()

Interacting with sliders

moveSlider(.accessibilityID("SliderID"), to: 0.5)

Interacting with pickers

movePicker(.accessibilityID("PickerID"), to: Date())
movePicker(.accessibilityID("PickerID"), column: 1, to: "10")

Sencha's matchers

In order to find interface elements and perform actions on them, we need some matchers. In other libraries this is achieved by finding an element via the accessibilityLabel property of a view, but this property is meant for VoiceOver, and shouldn't be used for testing. Or yes, it's completely up to you, but at least you can choose :)

The most important matchers are:

Matcher.text(String)
Matcher.accessibilityID(String)
Matcher.accessibilityLabel(String)
Matcher.class(AnyClass)

Using the .accessibilityLabel(String) matcher is not recommended. It can interfere with the user experience when using VoiceOver i.e.; if you put internal element identifiers, VoiceOver will read them.

sencha's Issues

Use KIF instead of EarlGrey so that we can keep the current API

Since EarlGrey doesn't provide support for white-box testing on iOS 14. In order to keep API and not have to re-write all tests that depend on Sencha, a possible solution is using KIF instead of EarlGrey since it allows for white-box tests in the same way as the previous versions of EarlGrey did.

add pull to refresh action

Just added a new PR to get pull to refresh actions on tableviews.
You can checkout the PR here

As an improvement maybe speed could be added as a paremeter for the action? What do yout think? 🤔

iOS 13 Broke some tests

@achernoprudov fixed an issue with tests running on iOS 13 #20, but we are still having some problems with test failing due to: "Failed to execute block because idling resources below are busy."
I am opening this issue to have somewhere to follow up on any progress made towards fixing it.