Writing a first XCUI test from the scratch - my-swift-lab/firefox-ios GitHub Wiki

Configure the repo

Firstly, get the repo: git clone https://github.com/mozilla-mobile/firefox-ios.git

And follow the instructions in the README to get the project working.

The correct origin has to be configured:

git remote -v , should look like:

origin    [email protected]:mozilla-mobile/firefox-ios.git (fetch)
origin    [email protected]:mozilla-mobile/firefox-ios.git (push)

If not, the origin has to be set:

git remote add origin [email protected]:mozilla-mobile/firefox-ios.git

If there is an error telling that origin already exists then remove it first:

git remote remove origin 
git remote add origin [email protected]:mozilla-mobile/firefox-ios.git

Set you ssh keys up

In order to be able to push to the repo, your ssh keys have to be correctly set up and configured. To do that follow the instructions here: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#generating-a-new-ssh-key

Once created on your laptop, upload them to your github account: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/

Pick the test to write

To keep track of the work and know in which test is working each one if any, there is a backlog for the test(s) or work related to tests that can be picked to work on: https://github.com/mozilla-mobile/firefox-ios/projects/2

Once one is chosen, assign it to yourself. If there is a new test or test suite for a new feature or feature not covered and there is not a bug for it, open it. On Github, create a new issue if it does not exists already. When the PR is ready, it should mention the issue.

Create a new branch for the test

As seen above the new test has a bug associated. Its number is always used for creating the branch. But, before creating the branch is a good practice to be sure you are in master and that it is updated. git branch will show you where you are.

And to have it updated:

git pull origin master

git log

Once the latest commit is shown in the log, we can create the new branch: git checkout -b "Issue####-IssueTitle"

Write the test

Please read the good practices for creating automated tests here before starting. Also a reading about the XCUITest environment would be helpful

New test on existing test suite

Go to the test suite folder and add a new test like:

func testNameOfTest() {
     // Add your test here
}

New test on a new test suite

Go to XCUITests folder, click on right button, New file, then choose Swift option and choose the test suite name.

A new file will be created with that name. It has to have this structure:

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

import XCTest

class NameofTestSuiteTest: BaseTestCase {
      func testNameofTest() {
          // Add your test here
       }
     func testNameOfTest2() {
          // Add your test here
     }
}

Once the test(s) is(are) created it is necessary to check that they run correctly locally on Xcode before creating the PR. Be sure you run them for both platform iPhone and iPad and several times to be sure the test is stable.

Guidelines to create the PR

Once the changes are done it's time to create the PR. First, the files in which there had been changes have to be added. To be sure in which files there had been changes type this to get the list: git status

To be sure about the changes: git diff

To add the files(checking the list given by git status): git add nameOfFile

Once the files are added it's necessary to commit the changes: git commit -m "commit message"

It’s desired to call the first commit as "Issue ##### - Title of the issue"

Then the changes can be pushed with: git push origin branchName

Github

Once the PR is pushed, it will appear on Github. Go to Code tab in the repo:

It is necessary to tap on Compare & PR to create it. Add a small description about what the PR does, add the issue it is fixing, like Fixes #1111 then and tap on Open. Ask for review on github. Reviewer will leave comments that will have to be addressed in future commits.

Check the PR test results on BB

Once the PR is created BB runs the build for it. By default it runs the Fennec schema. That means that the XCUITests do not run. Before merging it would be good to assure that the tests also work on BB. To be able to check it the schema has to be changed. Please follow these steps for that.

-On BB look for your branch and tap on the Gear icon

-Select the XCUITests schema to run the tests

-Then go to Test Settings on the left side of the screen and select the device where tests will run in Configure menu, close the window and tap on Build Now

Guidelines to merge

In theory merging is simply. When all checks (BuddyBuild and Github) are green and there is only one commit, just pressing the Squash & Merge button will be enough.

But usually there are more than one commit. It is a good practice to leave only one before merging. For doing that is necessary to squash the commits.

Squashing commits

Firstly check how many commits there are in github, in case all commits are already there, then do:

git rebase -i HEAD~CommitsNumber

For example,

git rebase -i HEAD~2

If there is one more commit still pending to push (check with git log), push it or add it to the count above before the rebase.

A vi editor will be open. Like:

pick a6b652022 Bug 1492496 - XCUITests: Re-enable Drag&Drop tests
pick 1c44d5033 Fixing a typo in the tests

# Rebase 800098850..3b75a52ba onto 800098850 (4 commands)
#
# Commands:
# p, pick = use commit
….

Tap on esc and then i to start editing. The pick word has to be changed by squash for all those commits we want to rebase. Usually the first one is kept and the other changed:

pick a6b652022 Bug 1492496 - XCUITests: Re-enable Drag&Drop tests
squash 1c44d5033 Fixing a typo in the tests

Then tap on esc again and type :wq to save the changes

Another vi editor will be open, this time is to change or not the comments added. Similarly to edit the file tap on esc and then i to start if you want to change/remove any line. Usually if there are too many comments it is good to remove them and leave only the important ones. Only uncommented lines (not starting with # will be shown)

Again when finished tap esc and :wq. To exit without changes type :q!

When doing this, in order to push the changes is necessary to add --force git push origin branchName --force

Be careful with --force since it can remove work from other people, be sure to be in your branch and the correct branch to push the changes.

Once there is only one commit and all the checks are green, it can be merged by tapping on Squash & Merge button.

Although it does not look complicated is frequent to screw things up when squashing commits. In that case use: git rebase --abort

Usually there is always a solution that depends on how the things were screwed up but as a general fix the better option is to copy the changes and create a new PR.

Update the Issue

When the PR is merged, if it had the Fix #Issue number, the issue should be automatically closed. If not, go to it and closed it by adding the PR info that fixes it