Automated iOS App Documentation via Quick Unit Tests
Why do we need documentation?
At Trendyol, we always try to find different ways and approaches to improve our processes and there are lots of them. As the mobile software development team (both iOS & Android) we do monthly retrospective meetings and discuss the problems we have and how to solve them. One of that meetings, we saw that we were not good enough when it comes to onboarding new members to our team.
As the mobile team lead, my most important job is coming up with different approaches and solutions to these kind of process problems. But before coming up with the solution, I had to divide the problem into pieces.
Android
- Lack of unit tests / unproper unit tests
- High learning curve because of Rx, there are a lot of developers in Turkey who are unfamiliar with the concept
- Lack of documentation
iOS
- Lack of unit tests
- High learning curve because of VIPER architecture
- Lack of documentation
Lack of documentation
This one is especially important. The company grows as fast as a rocket, so does our apps. There are always new features to build, new business models to try, new a/b test ideas to integrate. Because of this really fast development process, sometimes even our product managers are having hard time tracking what our apps do. As our app grows, the case count in each screen exponentially grows.
When I wrote this, only code and I knew what it does, now only code knows.
Everyone was complaining about the lack of documentation as well. So we needed a way for creating one without too much human resource. Our team also wanted to write unit tests with a good and readable structure. We decided to start with iOS and needed to evaluate our options first.
XCTest vs Quick
XCTest is the standard framework on the iOS platform when it comes to unit tests. Quick is an open source unit test framework built on top of XCTest which makes tests more readable/understandable. So we had to decide between these and we picked the brand following module of our app where users can follow/unfollow the brands they want to hear news from. It was a relatively small module, so it would be a good start for our POC.
XCTest
- Setup
- Example Tests
Quick
- Setup
- Example tests
We decided to go with Quick. Why?
- Quick comes with a matcher framework called Nimble. It is more readable than XCTest’s XCTAssert and it also provides failure messages for failed tests which comes really handy while debugging. With XCTest, you must write your own failure message.
- If you want to make test names human readable with XCTest, you have to write very long function names and things get really ugly after a while. Quick has context, describe and it where you can just write sentences and make it as readable as possible.
- If you haven’t guessed already, we are kind of a structure freak.
Quick has alphabetical execution system. So for instance, it reads “describes” and executes those alphabetically. We used “1-Listing” for documentation purposes however it helps when you know exact execution order when you write tests.
Everyone says that tests are your code’s/app’s documentation. Yes, we get it but we “really” want to see that in action. Like in a markdown file or as a pdf export.
Shell Script to the Rescue
We needed a shell script to do the parsing of our spec files and extract the words from “context”s “describe”s and “it”s and write them to a file with markdown syntax. We named the script “doq”.
Shell Script Explained
What it basically does is it looks for our spec files and it starts with the “describe” scopes and seperate them to get their own “context”s and “it”s. Then it digs in to “context”s and gets the the “it”s within them. You can write a Quick test in different ways but the script expects the curly bracket and parenthesis exactly in the format below.
Adding as a Run Script
We can also add scripts to Xcode as run scripts. That way, each time we build our code base, the document renews itself. We added the doq in UnitTests root folder and how we added the run script shown below.
Configurations and Limitations of the Script
We wrote doq specifically for Quick, so the regexes we use in the script especially searches for “*Spec.swift” files and “context”s, “describe”s and “it”s in them.
Result
Doq converted our spec files from this:
To this:
What’s Next?
- We will improve the markdown syntax the doq uses.
- Define some annotations for Android in doq so our Android team will be able to use it as well.
- PDF export from markdown within doq
- Connect our unit tests with UI tests and show the video of connected UI test under unit tests in our documentation, we are very excited about this one.
Feedback
We are open to all kinds of feedbacks and want to improve the app documentation systems together. You can find the doq here and you can open PRs, fork it, edit it however you like.
