I didn’t start unit-testing for a long time because I didn’t really know where to begin. Especially with an existing codebase. I’ve been working on a project and part of the project includes a file upload that needs to be parsed. I couldn’t stomach the thought of clicking, browsing, submitting and waiting each time just to test a few changes.

Problem

Testing uploaded file parsing in a manual fashion is very time consuming and takes a long time. If the parsing breaks, we won’t know unless we upload each test file after every change. We can do better than this.

We need to utilize the testing framework in Django to help us automate this process a bit more.

Solution

The first thing we want to do is make an example file that a user may upload in our fixtures directory. Keeping the test upload files in our fixtures has a number of advantages. It allows us to keep them in our version control and lets all of our testing be portable.

For the example let’s pretend we are parsing an excel file of some kind.

The next step is to prepare our test. While we are only testing a single file upload, you may want to add in corrupted files or perhaps expand to different versions. So, lets setup our test with a single test “runner” test that will run the tests.

Also note that by keeping the import statements using a localized path instead of a full package sitename.app.file, we can further improve portability.

from django.test import TestCase
from utils import parse_excel_upload
import os

class ExcelParseTest(TestCase):
    
    test_upload_path = 'fixtures/test_upload.xls'
    
    def test_parse(self):
      self.parse(self.test_upload_path)

The above is straight forward, we have our excel test parse class, and a method named test_parse that will call a method named parse that takes a filename and will run all the actual tests.

Next, let’s setup our actual parse method:

 def parse(self,file_location):
        """
        Tests that we can parse our excel files
        """
        
        #setup
        path = os.path.join(os.path.split(__file__)[0],file_location)

        elements = parse_excel_upload(path)
        
        #Assert that we have something returned as expected
        self.assertNotEqual(elements,None)
        # continue doing more specific tests here

Note that I am using self.assertNotEqual. If you are running Python 2.7 or later, you can use self.assertNotNone(elements) for the same functionality. Using assertNotEqual simply allows us to run a older versions of python as well.

If we wanted to test our method with more files, perhaps some corrupted files, we simply need to add another test file in our fixture and then modify our runner to include parse the new file.

Conclusion

Testing requires a small initial time investment to get started. If it’s your first time testing, there are a few mental gymnastics to get used to for writing code that is testable.

After the initial investment, which becomes less and less each time do it, we can vastly improve the reliability of our code and catch subtle bugs that may crop up during development or future releases.

Problem

Traditionally, web developers have had to create graphics for every non-standard button they used on their site. This is expensive in terms of time, money, and usability. It takes extra work for our buttons to be assessable, increases load times, and if we ever want to change the wording of our button, we have to start all over again.

Using various features afforded in css3, we can remove the need for images altogether, lower load times (and save bandwidth) while gaining scalability of our user interface, full accessibility, and never have something that is completely reusable throughout our site without any extra work.

We are going to go from the one on the left to the one on the right.

Solution

First, we need to begin with our basic markup.

<a href="#">My Button</a>

Because we want to style it and reuse said styles more than once on a page (potentially), we’re going to want to add a css class name.

<a href="#" class="gradient_button">My Button</a>

That’s all the html markup we will use. From here on out, we will just be adding styles to our stylesheet. The first thing we need to do is decide which color our button needs to be. We need a minimum of 2 colors: one lighter color for the top of the button and one darker color (of the same shade) for the button of the button.

I used the CSS3 Gradient Generator to select my colors and generate the rules. I’ve picked a grey color for this tutorial. Feel free to pick anything you like. Let’s set it as the background for our button. Let’s create our gradient_button selector and add our gradient background

a.gradient_button {
	background-image: -webkit-gradient(linear,left top,left bottom,color-stop(0.43, rgb(237,234,237)),color-stop(0.72, rgb(176,176,176)));
	background-image: -moz-linear-gradient(center top,rgb(237,234,237) 43%,rgb(176,176,176) 72%);
}

It’s ugly, but we’re getting closer. Next, let’s add some padding around our button, create a border, and give it rounded corners. Add the following to the gradient_button selector.

border:solid 1px #111;
-webkit-border-radius:3px;
-moz-border-radius:3px;
padding:5px;

Already we are looking much better and more realistic. However, the text completely throws the button off. It looks like it’s just pasted on there. We want our text to be a part of the button. We can do that by insetting the text with a shadow. So, next, let’s remove the text decoration, change the color, and inset that text.

color:#111;
font-weight: bold;
text-shadow:#ffe 0px 1px 0, #333 0 -1px 0;
text-decoration: none;

Already, you can see our button finally looks like a button. We could stop there, but we should go the extra mile for that last bit of polish. Especially considering how much time we can save because we never have to visit photoshop to make a button again.

First, we need to recognize that objects are never flat. Everything casts a shadow. Our buttons are no different. Remember to try and keep a consistent light source when implementing shadows on your website, my light source is directly above, so I only want to cast a shadow below my button. Add the following to the selector:

-moz-box-shadow:  0px 2px 5px #999;
-webkit-box-shadow:  0px 2px 5px #999;
box-shadow: 0px 2px 5px #999;

Our button now looks great. Try clicking on it. Notice that? It maybe look like a button, but it surely doesn’t behave like a button. We can fix that by adding one more selector. We need to style the :active state of the link, which is displayed when a button is pressed.

When picturing a physical button pressed, what sort of changes we see? I imagine that the shadow would disappear, as the button is now becoming flat with the surface from which it protrudes. Also, I imagine that the shine of our gradient would change. I think that it would become almost a solid color, but not quite. Let’s one last style to make our button behave a lot more naturally when clicked.

a:active.gradient_button {
	-webkit-box-shadow: none;
	-moz-box-shadow: none;
	box-shadow:none;
	background-image: -webkit-gradient(linear,left bottom,left top,color-stop(0.18, rgb(237,234,237)),color-stop(0.59, rgb(176,176,176)),color-stop(0.8, rgb(237,234,237)));
	background-image: -moz-linear-gradient(center bottom, rgb(237,234,237) 18%,rgb(176,176,176) 59%,rgb(237,234,237) 80%);
	}

There we have it. A completely realistic button using nothing but CSS3 and a hyperlink.

Conclusion

CSS3 buttons allows us to save time (and therefore money) when developing a modern web application. Moreover, we get fringe benefits such as being able to make our website more accessible and fully scalable for free.

View Realistic CSS3 Button

Update:

This doesn’t work in IE. If you’d like to use a similar effect for the gradient, you can use the IE filter styles. The major caveat is that IE only seems to render these with a div wrapper or an absolute position. The div wrapper really kills the elegance of being able to have any link suddenly look and behave like a regular button with a single style. I recommend a graceful-degradation in IE, and just set the background color to a be solid.

The css for getting the same gradient effect in IE is as follows:

	/* For Internet Explorer 5.5 - 7 */
	filter: progid:DXImageTransform.Microsoft.gradient(startColorstr=#EDEAED, endColorstr=#B0B0B0);
	/* For Internet Explorer 8 */
	-ms-filter: "progid:DXImageTransform.Microsoft.gradient(startColorstr=#EDEAED, endColorstr=#B0B0B0)";
	/* graceful-degradation when the filter doesn't work */
	background:#EDEAED;

I was looking for some way to display a Title as regular, then right under it some kind of subtitle. Naturally, NSMenuItems are designed to handle just a single title. It seemed like if I wanted to display anything other than a single title, I was going to have to take advantage of NSMenuItem’s new ability to host a generic NSView.

Problem

Getting your custom NSView in to a NSMenuItem is easy. I actually got it displaying rather nicely. The problems came when I wanted my NSView and NSMenuItem to behave like they would as per regular.

1. Passing clicks from my NSView to the NSPopupButton proved to be rather difficult. Moreover, it felt like a huge kludge as it tied these items to a single control. I also wanted to reuse these in the menu up top.

2. Even with the kludge, I decided to proceed on. Next up was displaying the checkbox (NSOnState) image. For some reason, the checkbox image returned by [NSImage imageNamed:NSOnStateImage] is different from the checkbox image used in the rest of the system. It was skinner and looked out of place.

Overall, making a custom view with this much kludge and not quite feeling right grated on me. I wasted 2 days to get this far, but it doesn’t live up to the user experience that I want to give users and expect from software on the Mac.

Solution

In my rush to get my NSMenuItem running, I overlooked a a critical feature: NSMenuItem titles can take an NSAttributedString.

When initializing your NSMenuItem we can use an attributed string to set our colors. \n also works for creating new lines.

// assume we have an NSMenuItem alloc'ed/init'ed named item.
// we also have a model objected that responds to the "title" and "subtitle" messages 
// named myObject

NSString *title = [NSString stringWithFormat:@"%@\n%@",[myObject title],[myObject subtitle]];
NSMutableAttributedString *attributed_title = [[NSMutableAttributedString alloc] initWithString:title];
        
// This is the system default for controls. anything else and it looks off
NSDictionary *title_options = [NSDictionary dictionaryWithObjectsAndKeys:[NSFont fontWithName:@"Lucida Grande" size:13.0f],NSFontAttributeName,nil];

//make our subtitle a different color as it is just auxillary information 
NSDictionary *sub_title_options = [NSDictionary dictionaryWithObjectsAndKeys:[NSColor disabledControlTextColor],NSForegroundColorAttributeName,nil];

// apply our color attributes to the ranges of the string they are applicable to...
[attributed_title addAttributes:title_options range:[title rangeOfString:[myObject title]]];
[attributed_title addAttributes:sub_title_options range:[title rangeOfString:[myObject subtitle]]];

// finally set our attributed to the menu item
[item setAttributedTitle:attributed_title];
[item setRepresentedObject:myObject];

// clean up
[attributed_title release];

With the above in place we are halfway there. Our new shiny menu item looks great and it fits in. Most importantly there is zero kludge. Actions go where we want them when we want them. The NSOnState image looks like it does in the rest of the system. Life is hunky-dory.

Until we highlight it.

Our title and state images turn white when highlighted as expected. However, our subtitle…not so much.

Luckily we can fix this without too much trouble. NSMenu’s has a lovely delegate that tells us when it is about to highlight something with it’s menu:willHighlightItem: call. “Will” is the keyword that we tips us of we can use this. It means that our currently highlighted item is still selected, so we can revert any changes made.

*Update: * I had left a huge block of code that smelled bad and left it as an exercise to the reader to clean it up. I decided to remove some of the smell myself. If you have ideas on how the code below could be refactored even better, please let a comment below.

// set our controller to be the delegate of our NSMenu. In the case of a NSPopupButton, 
// you can access it with the [myButton menu] method.

- (void)setForegroundColor:(NSColor *)foregroundColor 
    onAttributedString:(NSMutableAttributedString *)attributedString 
    forRangeOfString:(NSString *)string {

    NSRange range = [[attributedString mutableString] rangeOfString:string];
    NSDictionary *attributes = [NSDictionary dictionaryWithObjectsAndKeys:foregroundColor,NSForegroundColorAttributeName,nil];
    
    [attributedString setAttributes:attributes range:range];
    
}

- (void)willHighlightItem:(NSMenuItem *)item currentlyHighlightedItem:(NSMenuItem *)currentItem {
    
    if (currentItem != nil) {
        NSString *subtitle = [(MyModelObject *)[currentItem representedObject] subtitle];
        NSMutableAttributedString *attributedString = [[currentItem attributedTitle] mutableCopy];

        [self setForegroundColor:[NSColor disabledControlTextColor] onAttributedString:attributedString forRangeOfString:subtitle];
                
        [currentItem setAttributedTitle:attributedString];
        [attributedString release];
    }
    
    NSString *subtitle = [(MyModelObject *)[item representedObject] subtitle];
    NSMutableAttributedString *attributedString = [[item attributedTitle] mutableCopy];
    
    [self setForegroundColor:[NSColor selectedMenuItemTextColor] onAttributedString:attributedString forRangeOfString:subtitle];

    [item setAttributedTitle:attributedString];
    [attributedString release];
}

Conclusion

With just the few lines of code above, we can create a custom looking NSMenuItem that behaves exactly as we would expect it to. What’s more by using an NSAttributedString isntead of a custom view, our “custom control” get accessibility for free. This means users with impaired sight get the same first-class experience as everyone else. Talk about a win-win-win.

When I first started writing Jisho, my hammer of choice was Objective-C. All projects, no matter their suitability, were developed in Objective-C. I even wished that Apple would have continued NeXT’s support for WebObjects in Objective-C. Afterall, everything is nail.

This meant that things that probably should have never been written in Objective-C were written in Objective-C. That’s not to say that the things I wrote couldn’t be written in Objective-C, indeed, they could, but that it would have been better to pick a different tool. A rock can break a piece of wood in two, which is great if you just need two random lengths of wood, but if you need any more precision, you should use a saw. Objective-C and Python can both parse xml, but the former takes a lot more effort than the later.

I eventually came to my senses and realized that my supporting application was not scaling the way I had hoped. It needed to be rewritten. What did I do? I picked the same hammer again, foolishly expecting different results.

It worked great for a while – until it didn’t. Features only came after great reluctance if at all. I knew it needed to be rewritten, again.

This time around, I have a wider skillset than I did when I first started Jisho. I know a few more scripting languages reasonably well. Some I like a lot more than others.

While I am still in the process of writing the parser, it’s coming together much quicker than the old versions ever did. More importantly, it doesn’t read like a bunch of voodoo magic. These tools excel for things like this. We should use them.

Today, Objective-C is still one of the most important hammers in my toolbox – perhaps even my favourite. But sometimes you need a saw.

As a software developer if you think something would be easier with a different tool, try it and find out. Best case scenerio you’re right and you’ve learned a new tool. Worst case scenario is you’ve learned a new tool and expanded your skillset. You can’t lose.

After a scrapped interface and a few delays, I forced myself stop adding new features and move the “nice to haves” into a future release. Jisho 4.0 was shipped in December 2009.

Soon after the 4.0 release I began work on Jisho 4.1 to take care of these issues. Jisho 4.1 was released in January 2011. The development time was quite long, but most of it was not spent writing code. Below are some lessons I learned while developing Jisho 4.1.

Define the scope of the release

Define features or fixes in a given release and stick to it. With a proper scope written there will be no second guessing if your program is ready to ship. Have you implemented the planned changes? Yes? Ship.

Keep it limited

If it sounds like it could be broken into multiple releases, it probably should be. Try to keep releases small. I made the mistake of trying to refactor the backend to improve search and add in some new UI features for a single release. The end result was looking 3 major undertakings directly after a major release was paralyzing.

Fully plan an interface before committing to development of a feature

Fully plan how a feature is going to work and integrate with the rest of the application before committing to develop it for a particular release.

With Jisho 4.1, I wanted to refine the interface so the user could see kanji in a larger view. I hadn’t planned the interaction properly and a clean design was not forth coming.

I spent the majority of development time trying various interactions that inevitably felt unnatural. Simply planning this refinement more completely would have told me it’s enough for it’s own release.

Push features to if it means you can release

If you have a feature that is sapping development time and holding up bug fixes or already completed features, push it. There’s no shame in pushing a feature to a future release so your users can get better software today.

Users tend to get upset if you promise a feature for a given release and then pull it. So, this lesson is most applicable if you don’t promise particular features while they are still in development or even before they are released.

Git (or your scm of choice) is a good thing

Creating a branch for development of a new feature is a great way to make it easy to revert to a prior version so you can release. If you only merge branches once the fix or feature is stable and complete, you will always have a stable version ready.

I just started using Git before the development of 4.0. Before that I was coding dangerously with random zip archives of the code, usually at each point release, and a changelog that only mentioned the changes the end-user would see.

Lower the barrier

The more steps required when releasing a piece of software has the same effect as adding steps during checkout. You’re going to lose a lot of people (or in our case inertia) towards making an actual release. Simply your release process as much as possible.

Until 4.1, Jisho was distributed as a dmg for new users. This dmg had a custom background, readme, shortcut to the applications folder. Each release was built by hand. I would spend a good hour crafting this dmg for each release.

Now Jisho 4.1 is simply distributed as a zip file of the application. I still have to zip / upload it manually at this point, which takes 2 minutes, but that’s still an extra step. Future plans include automating the entire process from within Xcode.

Release something

Releasing is like software food. Software lives by releasing new versions. The quickest way to kill a software project is to get weighed down by a single non-critical feature of fix.

The guilt associated with keeping fixes out of the hands of your users in the name of an unannounced feature will only grow with time. Assuming you haven’t pre-announced the feature, users won’t know what they’re missing. If you have, they might complain a bit, but most users would rather have something new rather than nothing.

It’s not too late

If you find yourself agreeing with any of this, stop reading this and figure out the fastest way to get a release out the door. It’s not to late to release something.

Jisho was well on it’s way to death by starvation. By reverting to the latest stable version and cutting the features that were holding up release I was able to breath life back into Jisho.

Was the release technically what one would consider a release worthy of a new sub-number version release? By itself – probably not*. However, the principal still stands – if your software looks like it’s starving, cut whatever you need to and feed it now. Failing to do so may inadvertently cause the death of your project.

* There were other factors at play with the version number, which I written about on the Sugoi Software blog.