xccov: Xcode Code Coverage Report for Humans

Apple has released new command line tool, xccov, with Xcode 9.3 for inspecting the contents of Xcode code coverage reports. Unfortunately, there isn't any web documentation yet, so we have to type man xccov in the terminal to get more information about this command line tool. This utility requires Xcode 9.3 and command line tools shipped with Xcode 9.3. With xccov, we can generate Xcode code coverage reports in the human-readable format as well as machine representable format like JSON without using third-party tools. In this post, we will explore how to generate and view Xcode code coverage reports using this new command line utility with a demo iOS app.

Mind the Name

The command line tool xccov is a native Apple developer tool shipped with Xcode 9.3. However, there are a few open-source tools with similar names that might confuse you.

• It’s not xcov.

There is a Ruby library with name xcov to generate nice-looking code coverage reports, which can be used with tools like Fastlane and Danger.

• It’s not hiroakit/xccov.

There is another pure Swift library to generate Xcode code coverage reports which is also called xccov, but is written by Hiroaki Endoh.

These libraries have similar names to the new utility launched by Apple, and coincidently, they are doing the same job, i.e. generating nice code coverage reports for Xcode. With the launch of Apple’s xccov, these libraries might not be needed.

Generating Code Coverage Reports

In order to explore xccov, let’s create a new iOS app with the "Tabbed App" template with Unit and UI Test targets and name it "XCCov-Demo." This will create the Xcode project scheme "XCCov-Demo." We can explicitly enable the code coverage for the scheme by editing the scheme and ticking the box "Code Coverage" from the "Test" action. We can filter targets as well if we don’t want to include coverage for UITests, as shown below:

Now we have enabled code coverage for our scheme. Once we build and test this scheme using the CMD+U button in Xcode, this will generate code coverage reports into the default derived data directory located at~/Library/Developer/Xcode/DerivedData and you will see the code coverage reports generated in the Logs/Test directory. However, for this demo, we will generate the derived data inside our project so that we can easily look at the reports.

Let’s build and test our app using the following xcodebuild command from the root of the project:

$ xcodebuild -project XCCov-Demo.xcodeproj/ -scheme XCCov-Demo -derivedDataPath Build/ -destination 'platform=iOS Simulator,OS=11.3,name=iPhone 7' -enableCodeCoverage YES clean build test CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO

This will dump all the DerivedData inside the Build directory and generate the code coverage data at path Build/Logs/Test. We will see code coverage with an .xccovreport and .xccovarchive extension.

What’s Inside the Coverage Report

Inside the Logs/Test directory, there is a coverage report with the extension .xccovreport, and the coverage archive, with the extension .xccovarchive, respectively. As per the main page of this utility, “The coverage report contains line coverage percentages for each target, source file, and function/method that has coverage information. The coverage archive contains the raw execution counts for each file in the report.” However, they are not human-readable files; that’s the reason we need xccov to look inside these files and display the reports in a nice format.

Viewing Code Coverage Reports

Now that we have generated code coverage logs, we can use xccov to view the code coverage in a human-readable format. In order to access xccov, we have put it inside the $PATH, or we can easily access it with the xcrun command line utility. At the moment, we can achieve the following things with xccov:

• View the code coverage reports from the terminal
• Spit out the JSON from code coverage reports
• List all the files for which code coverage has been generated
• Look at the code coverage report for one specific file

Let’s explore the commands to achieve this using xccov.

View Report -default

We can view code coverage reports in the default format, which isn’t particularly great but as per Apple, it’s human-readable. In our demo project, we can generate the report using the following command:

$ xcrun xccov view Build/Logs/Test/*.xccovreport

View Report- JSON

The real power of xccov comes when it can generate code coverage reports in the JSON format. As per Apple’s documentation on the main page, it's a machine-representable format. We can hook these JSON results anywhere we like or build another tool on top of this. We can generate JSON reports using the following command:

$ xcrun xccov view Build/Logs/Test/*.xccovreport --json

We have just added the flag --json at the end of the command to get the JSON reports.

List All the Files

We can also list all the files that have code coverage data.

$ xcrun xccov view --file-list Build/Logs/Test/*.xccovarchive/

This will display all the project files with the absolute path.

Code Coverage for a Specific File

We can also see code coverage for a specific file, which displays line-by-line reports in some sort of symbols. Not sure how useful that would be, but it's there.

$ xcrun xccov view --file ~/Desktop/XCCov-Demo/XCCov-Demo/AppDelegate.swift  Build/Logs/Test/*.xccovarchive/

We have to give full path of the file and you will get reports in symbols.

Watch It in Action

Watch this GIF containing the features of xccov:

Source Code

There is source code with a fully-instructed README file available on GitHub at XCCov-Demo. Feel free to check out the project and try it yourself.

Conclusion

With Xcode 9.3, Apple shipped xccov to reduce the pain of using third-party tools to display Xcode code coverage reports in a nice format. The default format doesn’t look great or usable at the moment, but the real power comes when it generates JSON. Using the JSON format, we can hook these reports on Continuous Integration servers.