Writing a first XCUI test from the scratch

Configure the repository

From the Firefox iOS’s repository, you should fork the repository and work from your own fork.

Then you can get the source from your own forked repository:

git clone https://github.com/<username>/firefox-ios.git

The remote setting given by git remote -v should be the following:

origin    https://github.com/<username>/firefox-ios.git (fetch)
origin    https://github.com/<username>/firefox-ios.git (push)
upstream    https://github.com/mozilla-mobile/firefox-ios.git (fetch)
upstream    https://github.com/mozilla-mobile/firefox-ios.git (push)

If the origin and the upstream is not set as above, they could be set manually. If both origin and upstream are set properly, please skip the rest of this section and proceed to the next step.

Setting Github repository’s origin and upstream

The origin and remote can be added via the command line:

git remote remove origin 
git remote remove upstream
git remote add origin https://github.com/<username>/firefox-ios.git
git remote add upstream https://github.com/mozilla-mobile/firefox-ios.git

Compile the code

Follow the instructions in the README to download XCode, install the software tools and get the project running.

Set up ssh keys

All commits must be verified. In order to be able to push to the repo, your ssh keys have to be correctly set up and configured. You have to generate an ssh key and upload the ssh key to Github.

Create a new branch for the test

The branch name always contains the Jira ticket number. It should be created after the main branch is updated.

git pull origin main
git branch MTE-xxx-my-new-test
git checkout MTE-xxx-my-new-test

Write the test

We use XCode for writing and executing tests.

We always use the Fennec scheme for the Smoke Tests and Fennec_Enterprise_XCUITests scheme for the Full Functional Tests.

New test on existing test suite

Open an existing file and add a new test. All test names start with “test”.

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

New test on a new test suite

Right click the XCUITest folder, select New file from the menu, choose Swift option from the modal and enter 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 iPhone and iPad and several times to be sure the test is stable.

Create the pull request

Once the changes are done, it's time to commit the changes and create the PR.

First, examine the changes. Ensure that the new files are added and the changes only exist in the files intended:

git diff
git add <new file>
git status

Commit and push the changes:

git commit -m “<commit message>”
git push

Open Firefox iOS Github repository. Push Compare & pull request button from the yellow banner near the top of the page.

The Compare Changes screen should appear. Fill in the title and a description for the pull request. Note that the title must follow the Pull Request Naming Guide. The description of the pull request should use the template.

Ensure that at least fxios automation is listed as one of the reviewers. This is the group of developers owning the XCUITests. Push the “Create pull request” button below the pull request’s description.

Check the pull request’s result on Bitrise

Once the pull request is created, open Bitrise’s firefox-ios project’s page. Under the PR builds are waiting for approval section, find your newly created pull request. Push the “Approve and run build” button to start the pipeline.

When the pipeline is finished, you can find the result from firefox-ios project’s page on Bitrise as well as from the pull request’s page on Github.

Merge the pull request

The pull request could be merged when all checks on Github and Bitrise passed. Push the Squash and Merge button from the Github pull request’s page.

If one or more checks failed, please investigate the cause. Both Github and Bitrise provide logs.

Update the Issue

When the pull request is merged, put the Jira ticket’s status to “Done”.