Returning to An Old Project: Part 2

Returning to An Old Project: Part 2
The logical place to start reviewing and fixing up my Devonian app is in the area of managing the database.  I have one class that works on both iOS and MacOS that handles this job.   Reviewing the class… it’s quite a bit of code: well over 800 lines.  Individual classes with high line counts are not that unusual, especially for things like view controllers (if you stick to the classic Model-View-Controller, MVC, design pattern).  However, I’m not happy about that.  I want it to be smaller, leaner, easier to manage, and finally make it easier to transition to another file format or web service for the database.
There were a few tests.  Most failed.  After perusing the tests I discovered a major problem: I didn’t understand what the class actually did.  Tests serve as a way not only make sure your code works, but to do things like ensure contracts with the rest of your code are respected, and, quite importantly, they document the code.  The tests failed in this regard.
Part of the problem with the tests is that I didn’t understand how to write them effectively.  I probably still don’t always write them effectively, but I’m better 2 years on.  Furthermore, since I really didn’t understand how to mock code in Swift, the class was almost impossible to test anyway – mocks would be required to do unit tests.  So, what kind of tests did I have in the end?  Integration tests.  These tests had to use real data and real database in order to work and the database was likely to change over time.
So, chuck the tests and start over.
Now, what to test.  Generally, I want to exercise  all the code in my class.  But, since I wrote this for myself, I made no distinction between public and private methods and variables.  Anything that should be private should not be tested directly, since those things should impact other calls.  In addition, it was worth eliminating any dead code (if I really needed it back, I use version control like any sane developer).   I found a bit more of this stuff as testing went on, so it’s okay to eliminate stuff later.
Finally, it was time to slog through backfilling the tests.  Keep in mind, at this stage I’m only testing to suss out the contract this class is using to interface with the rest of the app, and not make meaningful rewrites or refactors.  So, the goal is to be minimally invasive.   The main exceptions (other than dead  code removal and public/private) include making the code easier to understand and easier to test.
As far as understanding, I had a number of values that were essentially magic numbers: i.e. numbers that seemingly come from nowhere.  Fortunately, I knew what the numbers meant, so I could assign them as variables or enums.  I would have trouble understanding what 832 might be, but if I passed the value around as “George”, it can make more sense.  If the code makes more sense, it will be easier to test.
Going through the testing process quickly brought up the need for mock classes.  In particular, mocks for FileManager and NotificationCenter.  Both of these standard Apple classes are commonly using on Apple platforms.  Most apps will use these somehow.  However, they are both essentially singletons: they both are single objects in your app that you can call from almost anywhere.  Very  convenient, but very hard to test when you do so.
First, the FileManager handles files: creates, deletes, verifies it’s there, etc.  Makes sense to use.   However, all sorts of things can happen while doing these operations.  For example, your code might do X if a file exists or do Y if it doesn’t.  Imagine for a moment your app will ..usually.. successfully create a file.  It almost never fails.  Maybe once in a blue moon something happens but it’s fairly consistent.  How do you test the failure state?  Your file is always created, right?  What if you could get the FileManager to say, “sorry, there’s no file there?”  You need a mock for that.
I’m going something bad and refer to anything that isn’t a real object as a mock: so I’m going to conflate mocks, fakes, and stubs.  Mock are objects that stand in for real objects and track what’s been called on them.  You can these assert that what you expect was called, was indeed called.  However, these objects are essentially non-functioning.   Fakes on the other hand are functioning objects that typically function similarly to the real object but how it works is simplified.  Stubs are similar to mocks but can respond with data.   So if you call a method on a real object that returns a value, a stub can do the same thing with canned responses.  Of the three, mocks and stubs are very similar and, in my usage, are best mixed.  You want to see what’s called, and if I response is required, then  do so.
So, we need a mock(with stubs) FileManager.  But how?  Swift makes it tricky given that it’s type safe.  Indeed, how to we deal  with those singleton calls?  How are those replaced with mocks?  It’s easier than it sounds.
Step 1.  Create a protocol in you app for the FileManager, say “MyFileManagerProtocol”.  In Swift, it will look a bit like this:
protocol MyFileManagerProtocol {
}
Then all you need is to make FileManager conform to that protocol with an extension:
@objc extension FileManager: PTFileManager {
}
Now, Apple’s FileManager conforms to MyFileManagerProtocol.  We’re not quite done yet.  Take a look at the FileManager calls you use.  Simply add those function signatures to your own protocol:
protocol MyFileManagerProtocol {
func urls(for directory: FileManager.SearchPathDirectory, in domainMask: FileManager.SearchPathDomainMask) -> [URL]
func fileExists(atPath path: String) -> Bool
func createDirectory(at url: URL, withIntermediateDirectories createIntermediates: Bool, attributes: [FileAttributeKey : Any]?) throws
func copyItem(at srcURL: URL, to dstURL: URL) throws
}
Since FIleManager already has these methods, it already conforms to your protocol.
Now, let’s change how we call the file manager.   Instead of calling the singleton version we want to inject our protocol version.  So, on init of the class, let’s inject it:
init(fileManager: MyFileManager = FileManager.default {
self.fileManager = fileManager
}
In the class, replace every occurrence of FileManager.default with fileManager (except for the init).  Notice in this using the standard FileManager by default.  This may not be desirable in some cases, but this should be fine.
Now, make a mock (and it will also be a stub).  Be sure to only include the mock in the unit test target, not the app.  Don’t forget to do a “@testable import” as well.
class MockFileManager: MyFileManager {
}
Of course, now you have to make it conform to the protocol.  In this case, we want to make some of these calls to be both mocks and stubs.  I’ll show one:
var fileExistsCalled = false
var returnFileExistsPath: Bool = false
var capturedPath: String = “”
func fileExists(atPath path: String) -> Bool {
fileExistsCalled = true
capturedPath = capturedPath
return returnFileExistsPath
}
What does the above do?  It allows us to verify that the method was called (if called, it sets fileExistsCalled to true).   It allows us to capture what path was used in the call (capturedPath).  Finally, it allows us to return whether or not the file exists.
So a test might look something like (pseudo code):
func test_doMyThing_givenFileDoesNotExist_ThenDoMyOtherThing() {_
// Given
let mockFileManager = MockFileManager() //create the mock manager
mockFileManager.returnFIleExistsPath = false //make sure we know it won’t find the file
let testObject = TestObject(fileManager: mockFileManager)
let expectedResultIfDoesntFileExist = failedResult
let expectedResultIfFileExists = successResult
let expectedFilePath = “/path/to/file”
// When
let result = testObject.doMyThing()
// Then
XCTAssertTrue(mockFileManager.fileExistsCalled) //make sure we called it
XCTAssertEqual(mockFileManager.capturedPath, expectedFile) //make sure we called the correct path
XCTAssertEqual(result, expectedResultIfDoesntFileExist)
}
The notification center is similar, except that you are capturing calls to the notification center.
More next time

Returning to An Old Project: Brining the Power of Unit Testing and Refactoring (and rewriting) To Resurrect the Dead

I have a project that stalled.

The project is an iOS app. A fairly simple, really. The app is, more or less, a graphical interface for database (I suppose most apps are some form of this). The app has been around in one form or another for many years, but doesn’t need to be update that often. The truth of the matter the database that i’m using hasn’t been updated in a while because I’ve never gotten around to write an editor. So, the last major release was around 2015.

In late 2015 or so, I had the brilliant idea of porting the app to MacOS. After all, I eventually need an editor. A twist in that idea was the app would be 100% written in Swift, if possible. The iOS version was written in Objective-C.

It turned out the transition went well. I released the MacOS version in 2016.

It went wrong when I decided it was time to unify the code base of the apps as much as possible. In other words, the iOS app had to move to Swift too. Why? Well, I got a job and this particular app was a relatively low priority.

Fast forward to 2018. I decided that it was time to expand the things I do at work. Thus, I decided to become a Test-Driven Development (TDD) instructor (in training at least). So naturally, I decided to find a relatively small project that I can apply my (limited) TDD chops.

It is time to revisit my Devonian Database iOS and MacOS apps. These apps are available for free on the different App Stores.

The iOS app been in the app store for many years, and I managed to get the last version out in 2015 or 2016. I fixed it up and released as part of a job hunt: have a good working app in the store to prove I can do the work. As part of that effort, though, I decided to release the Mac version of the same app. Cleaver me decided to make this new version entirely swift: no Objective-C code at all. That app was successfully released too.

What got me was the next decision: make my iOS app Swift only as well. The decision made sense, and still does. Minimize the code base and both apps are easier to maintain. While Objective-C is still a powerful language, Swift is an easier language to use (with the exceptions of occasional major changes to the languages and the difficulties in testing and Objective-C interoperability). But it takes time and energy. I got the job and the app fell by the wayside.

I started looking at the app again and it’s a mess. For most developers, looking at your old code is a cringe-worthy experience. Now that I work on a team, I find my old code has one fatal flaw: it was written for me… The problem with “written for me” that that the me of today has no idea what the me of 2015 was thinking. I wrote things quickly. I wrote things using simple and convenient design patterns instead of something that would be more appropriate. I did write a few unit tests (or in many cases integration tests pretending to be unit tests), but they were few and far between and written at a time where I really didn’t understand how to write good Swift tests. Not to mention many didn’t work at all.

So, my first few hours will be spent looking at the core of the app – the database management code. I’ll blog the results of this work.

iOS Size Classes, Navigation Bar Titles, UI Testing

I’m working on a particularly difficult part of my user interface and I ran into an interesting and confusing problem.  UI Testing is a new feature in Xcode.  Despite its newness, it has already helped save time in development.  However, I started using it with an app I’ve been trying to update for a while when I ran into this problem.

UI Testing depends on accessibility: a mode for those with disabilities.  As it turns out, it is highly dependent on titles or names you give different user interface items.  So, the names you give things are key to getting UI Testing in Xcode right.

In some cases, however, this can cause a problem.

I have a navigation bar that has enough elements that a title looks too stuffed into the bar when the device has a compact horizontal size class.  When regular, it looks fine.  So, I simply added a title when the display was regular, and did not add the title when compact.  This causes UI Testing problems.

The navigation item must always have the same name in the testing environment or you have to use a NSPredicate to search for the title or the class name (if you don’t set the title, then the UI Test record will record the class name).  This seems quite fragile and quite annoying since I don’t want duplicate tests for different devices unless there is a major difference in layout.

The apparent solution at this stage is to go ahead and name the navigation item to the title I want.  However, to prevent the title from appearing, I simply sent an empty UILabel to the “titleView” property of the navigation item.  This appears to work at this stage…

 

 

Why you need the hardware to develop for mobile…

Probably the second biggest roadblock for developing mobile apps is the cost of hardware (the first, of course, is the time).  Devices are expensive and it’s tough to keep up.  My current testing livery of devices is actually quite limited.  Indeed, some of my devices are not longer supported by their manufacturers or myself.

Despite the difficulty of maintaining an adequate device livery, you need the devices for testing. In a previous post, I mentioned that I’m migrating my app from OpenGL ES 1.1 to OpenGL ES 2.0.  All of my currently-supported devices support 2.0 (and in some cases 3.0).   That sounds like things should be just fine.   Well, they don’t have the exact same graphics card or OS – which will lead to horrible surprises.

I have one older iPod Touch which on iOS 6.  Having this particular device saved my bacon for the last release of one of my apps.  It turns out that the software ran just find on all of my devices except that iPod Touch.  Talk about panic!  It wasn’t an easy fix either; it required a rewrite of a major portion of my code to work correctly.

Well, in my testing for parts of my OpenGL ES transition code, I decided to try the old iPod again… and wouldn’t you know, code I thought was working fine rendered completely wrong!  It turns out there was a bug in the OpenGL code that apparently  didn’t manifest in the newer devices or on the simulator.

Realistically, you can get away with a smaller livery of devices under some conditions.  For example, if you don’t use any low-level code and stick with the high-level user interface APIs you’re more  likely to still have a stable app on many devices.  Getting into the lower-level stuff will likely cause more problems particularly in the short run as you develop, and in the long run when devices you didn’t test start reporting issues.

Just to add to the above, I don’t count the xCode simulator as a device.  I have code that works perfectly in the simulator and does not run correctly AT ALL on any device.  After all, the simulator is actually MacOS X OS and hardware, not mobile.  As a consequence, successful rendering in the simulator will not always translate to a device.  The first time you encounter this issue it is a rude awakening.  However, it shouldn’t be a surprise since all of Apple’s OpenGL  ES debugging tools only work on devices, not the simulator.

This gets back around to why my apps have yet to be ported to Android.  I only have a couple devices that use that platform for testing out of the many MANY devices out there… it’s a tad scary…

 

 

Working on migrating AE to OpenGL ES 2.0

Now that I have a break from other duties, I’ve been working on improving AE for iOS.  One of my early design decisions I made in AE is to go with OpenGL ES 1.1.  At the time, my only iOS device did not support OpenGL 2.0, so for practicality sake, 1.1 made sense.  Furthermore, I needed some basic functionality that was stripped from OpenGL ES 2.0.  ES 2.0 was clearly unattractive… at the time…

Today, the story is different.  All of my “supported” iOS devices support OpenGL ES 2.0 and in some cases 3.0.  Yes, they still support 1.1, and it’s arguable that the practical decision is to remain on 1.1.  However, it’s only practical if I don’t add new features that call on the graphics card.  I’m also considering the path to porting the application to other platforms, such as Android and Desktops.  From this perspective, ES 1.1 looks increasingly problematic.

The kicker that’s forcing the transition is the time scale control on the bottom of the screen.  It turns out that feature is quite a difficult to display.  The time scale tends to be a memory hog and requires a great deal of code to provide full functionality.  I’ve long known that the control should be moved to OpenGL rather than using higher-level functions.  Originally, the time scale was created using simple bezier-path draw calls. In the last version, I moved the system to Apple’s layers.  That transition was meant to make the code easier to maintain.  However, it turned out, on older devices in particular, the app became crash prone because the layers took up an unexpected amount of memory.  I managed to work through this problem for a stable release, but I wasn’t happy with the situation.

Enter OpenGL ES 2.0.  Now, the time scale is not done by any means, so these comments are initial impressions.  Now that I’ve worked with it, I do regret not going with ES 2.0 from the beginning (it still wouldn’t have been possible to release the original app with ES 2.0 support since I had no hardware at the time).  ES 2.0 is clearly superior to ES 1.1.  Surprisingly, I found that while in some areas ES 2.0 requires more code, the transition from layers to ES 2.0 appears, at least in some areas, is thinning out my code.  That’s exciting!  Since the code for the layers was extremely complex, it’s hard to improve or add features.  With the code simplifying, I feel I can consider, at least, adding functionality I wouldn’t have been too keen on adding before.

Now, back to work on the code.  We’ll see how this turns out…

Unexpected problem with the App Store – App icons

Migrating to XCode 5 has largely been very helpful.  I’ve used many of the new features and I’m quite happy how things are working out.

One thing caught me by surprise.

Submitting apps to the store is usually a painful experience.  One the goals of XCode 5 is to lessen the pain, at least a bit.  So, imaging my surprise when submitting my latests updates was painful!  Neither of my apps would pass the verification step in the approval process.  Basically, the problem was that the app icons couldn’t be found.

Huh?

I’m using XCode’s latest feature called image assets.  They are great for managing all of the icon and launch images required for the app.  It was supposed to make all this painless.  For example, to manage your app icon, you made an app icon image set, load in all of the images, and the rest is magic.

But, it wasn’t quite magic.

It turns out, that when you build an app using image assets, XCode will modify the app’s info.plist file to list all of the app icons to be included in your app.  However, if you’re like me and your project is older, you might have references to icons already in your info.plist files.  I suspect in most cases, this wont be a problem.  In my case, however, when I looked at the info.plist file for a compiled version of the app, all of those old icon references were still there.  Thus, the verification process could not find those images and the app gets rejected.

Fortunately, it didn’t take TOO long to figure this out.  So, I deleted all existing app icon references out of my plist file and after that, things verified normally.

Now that I knew the problem, I fixed it in my other app and the process really because much less painful.

Redesigning my OpenGL engine for Ancient Earth

In case you were wondering about any updates to Ancient Earth, I’m working on them.  Right now, I’m spending a good deal of time trying to modernize my OpenGL engine to take advantage of Apple’s updates in iOS 5 (yes, that means, I’m dropping support for iOS4).  It turns out that Ancient Earth really pushes the limits for iOS, and for us to be able to add more data and map types, we need not only a more efficient rendering system, but a more flexible rendering system.

Ancient Earth Released for iOS!

Last month, I released by iOS app “Ancient Earth: Breakup of Pangea”. Working with C.R. Scotese, we've brought his maps to the iOS platform! In this app, you can explore his continental plate reconstructions for the last 200 million years of Earth history.

You can see our home page for Ancient Earth here: Ancient Earth. Alternatively, you can simply visit our page on iTunes:
Ancient Earth: Breakup of Pangea - Thomas L. Moore

Reading SQL with PySqlite

About a year or so ago, I wrote a special script to run the FOAM climate model. The primary goal of this script, besides running the model, was to store a wide variety of information about the run, including settings, system information (like CPU temperature), and the timing and duration of the run. The storing process stored some of the information before the model starts and after the model ends. It's a great log of my model run and system performance history.

The drawback to this data was the database itself. Up until today, I've been using a single database to store all of the run data. However, I've been wanting a separate database for each model.

I didn't develop this approach in the first version of the script because I didn't know how to read the template SQL and directly insert it into the database. In the command line with Sqlite, you simply enter “.read mysqlfile.sql” or something similar. In python, that's not possible. Nor is it possible for PySqlite to accept more than one SQL command at a time. Without this ability, I couldn't automatically create a complete Sqlite file with all of the required tables.

The solution turned out to be remarkably easy. The SQL file was a straightforward text file. Reading a text file into python is very easy:


data_file = open("path_to_my_SQL_,'r')
theSQL = data_file.read()

Since pysqlite only handles one statement at a time, the commands need to be split into separate statments:


theStatements = theSQL.split(";")

The file can be split into discrete statements because the semicolon always marks the end of a statement.

At this point, you simply need to loop through each of the statements and execute in the sqlite file:


for statement in theStatements:
sqlite_cursor.execute(statement + ";")

Keep in mind, you have to reattach the trailing semicolon at the end of each statement.

There's probably even an easier way to do this, but it's good enough for me.

Finishing up DLD 2.0

It’s been a long time coming, but I’m finishing up DLD 2.0 for iOS. I hope to submit next week.

What’s new? Everything. Depending on whether it gets through the approval process, here’s a summary:

1. An entirely new map interface! Now, the map is actually useful and will make use of Google map data as well!

2. A custom Time Scale controller! Now you can change the age range of the data displayed on the map without leaving the map view!

3. An entirely new database back-end. Now, this isn’t exciting for the user in general, but the nasty torture I’ve been inflicting on the database is improving the overall quality of the data.

Do you have any other wants for future versions? Let me know.

As always, contact me if you want a copy of the raw database file.

Tom