words by patrick

Good news: The Adium Time Zone Plugin is now out. I hoped to have it out by the end of the week, and (I think) I squashed the last two bugs that were preventing me from releasing, so off it goes! I made a page for it that I will keep updated with the latest version and other news. The BSD licensed source code is also there if you want to check it out.

I’m proud of the code. I’m not super proud of the model, in fact I’m sure it will become something that I will look back on one day and say “What the hell was I thinking?!”. I’ll probably refactor it in the future, it’s just that I’ve held off on releasing this for long enough, and with my finals looming I was scared that If I didn’t release by my self-imposed deadline of this week then I wouldn’t have time to work on it again in a while.

I hope you like it. I hope it doesn’t sink your Adium. Please send me some feedback if it does (or if it doesn’t). Thanks!

Last time I wrote about unit testing Adium, I was actually writing about unit testing Adium.framework - The public API that plugin developers and the like can use to tie into Adium. After talking with David Smith from Adium about some of my other SoC Ideas (such as improving plugin support) I realized that Adium’s API really shouldn’t be considered stable, and that using it as a starting point for unit testing is a bad idea.

That being said, I switched gears and started again, this time unit testing the application itself as oppose to the framework. In hindsight I guess I probably should have started here first, but being familiar with Adium.framework from my plugin development, I assumed that would come more quickly. Wrongo.

Anyways, thanks again to Chris Hanson, his short tutorial on getting unit testing up and running in cocoa apps helped me get started, and everything is now working as expected. When you build the test bundle, it launches the Adium build, executes it’s tests, quits, and reports any failures. Good stuff.

Here’s a bit of what my AIEmoticonPack unit test looks like:

- (void)setUp
{
	fileManager = [NSFileManager defaultManager];
	//NSLog(@"Current Directory is %@/", [fileManager currentDirectoryPath]);

	emoticonPack = [AIEmoticonPack emoticonPackFromPath:[[fileManager currentDirectoryPath] stringByAppendingString:EMOTICONSET_PATH1]];
	//NSLog(@"Testing Emoticon Pack: %@", emoticonPack);

	NSArray *fooarray = [emoticonPack emoticons];
	//NSLog(@"Foo: %@", fooarray);
}

- (void)tearDown
{
	// No necessary tear down.
}

- (void)testPath
{
	NSString *expectedPath = [[fileManager currentDirectoryPath] stringByAppendingString:EMOTICONSET_PATH1];

	STAssertEqualObjects(expectedPath, [emoticonPack path], @"Path wasn't right, should have been %@ but was %@", expectedPath, [emoticonPack path]);
}

- (void)testName
{
	NSString *expectedName = [[[NSString stringWithString:EMOTICONSET_PATH1] lastPathComponent] stringByDeletingPathExtension];

	STAssertEqualObjects(expectedName, [emoticonPack name], @"Name wasn't right, should have been %@ but was %@", expectedName, [emoticonPack name]);
}

- (void)testEnabled
{
	[emoticonPack setIsEnabled:YES];
	STAssertTrue([emoticonPack isEnabled], @"Emoticon Pack isn't enabled by default");
	[emoticonPack setIsEnabled:NO];
	STAssertFalse([emoticonPack isEnabled], @"Emoticon Pack is enabled when it shouldn't be");
	[emoticonPack setIsEnabled:YES];
	STAssertTrue([emoticonPack isEnabled], @"Emoticon Pack isn't enabled when it shouldn't be");
}

Hmm. I really need to write my own wordpress theme.

Adium devs look out, incoming SoC application!

With Google’s Summer of Code roaring up again this summer and me without summer job plans yet, I have dug into investigating one of the project ideas by my favourite OSS project, Adium. The project idea I’m looking into submitting a proposal for is that of unit testing much of Adium’s code. Currently Adium does no unit testing. Although my experience with Cocoa is growing to a point where I am fairly comfortable with it, my experience with unit testing doesn’t stretch as far. It’s not a difficult concept, however, so I decided to try and put it into action and see what I could come up with.

I chose to write a unit test for the emoticon classes, AIEmoticon and AIEmoticonPack. I choose these classes because they are documented, making understanding them quicker and easier, and because they aren’t ridiculously large. A good start for a unit test.

Creating a new test bundle target and the test classes were easy thanks to the fact that OCUnit is bundled with Xcode. As soon as I added the necessary frameworks though, I ran into a problem.

Adium.framework references FriBidi.framework, but because the unit test actually runs from /Developer/Tools/otest, the FriBidi.framework isn’t found in the @executable_path (where dyld is looking for it). Copying it to the build products Frameworks directory is no help since it doesn’t look there either. You could create a symlink to the build products directory but that’s rather messy and Xcode provides us with a much easier way of doing this: In the Run Script phase of the build process for your Test Bundle target, define DYLD_FRAMEWORK_PATH to the directory containing your referenced frameworks before the tests are run. Mine looks like this:

export DYLD_FRAMEWORK_PATH="${PROJECT_DIR}/Frameworks"


I spent several hours figuring this little detail out. Big thanks to both Peter Hosey and chanson of #macdev for helping me nail this down and explaining it to me.

I now have the beginnings of a working unit test of AIEmoticonPack. I’ve run into a new problem where certain methods cannot be tested since they require a running instance of Adium. I plan to address this by defining a base test class which instantiates such an Adium instance then changing my test case to inherit from that class. We’ll see how it goes.

Creating a Plugin for Adium is actually really easy. Here’s a quick guide through the proper set up to help get you started. There is even a skeleton project at the end.

1. Create a new Xcode project, choose Bundle -> Cocoa Bundle.
2. Add the following frameworks to your project:
   • Adium.framework
   • AIUtilities.framework
   • FriBidi.framework

   These are necessary if you plan on using or changing any part of Adium, which you will likely be doing.

3. Create your main class. It should be named something like ABMyTestPlugin. Your class should inherit from AIPlugin, found in Adium/AIPlugin. So you will need to import that.
4. Override the -installPlugin and (if necessary) -uninstallPlugin methods. The meat of your code goes there.
5. Override -pluginAuthor, -pluginVersion, -pluginDescription, and -pluginURL as well, to all return appropriate NSStrings. This isn’t required, but is good practice, so do it anyways.
6. Get info on the build target (your bundle). Change the build settings to add the following:
   • Other Linker Flags: -undefined dynamic_lookup
   • Wrapper Extension: AdiumPlugin

   Also, under the Properties tab change the Creator to “AdiM” and the set the Principal class to the name of your main class (ABMyTestPlugin).

7. Build your bundle, drag and drop it onto the Adium icon and test it out.

That’s pretty much all there is to it. More information on what you can do once you hook into adium can be found at the Map of Adium. It’s not really complete, but if you poke around inside the Adium.framework headers you will find that most of the methods are “self-documenting” and not to difficult to figure out. I’d also suggest looking at some existing plugins, like my Time Zone Plugin and the ones included within Adium itself.

If you’d like a skeleton of the Xcode project, grab it right here: AdiumTestPlugin.zip

You might want to also grab the Adium Source and compile your own frameworks since the ones included may be out of date.

Update: luapffuh pointed me to Toby’s guide to creating an Adium Plugin. Although mostly the same, his has bit more detail and is definitely worth checking out.

UPDATE: This is now out of date! Get the latest version by clicking on the Adium Time Zone Plugin page in the sidebar.

Today I’m announcing the preview release of my Adium Time Zone Plug-in. This plug-in adds functionality to Adium by letting you set time zones for each individual contact. Once set, you can view the local time of the contact in their tooltip.

It looks something like this:

It’s a preview release because I’m interested in soliciting feedback as to it’s implementation before I make it totally public and tell all my friends to download it. Please try it out and let me know what you think and how it can be improved.

Note of interest:

• The city names are all taken from Apple’s NSTimeZone class. I assume I could add more, but it might be hectic/ugly to manage two separate lists; a real one and one that just maps it’s contents to the real one.
• I tried to follow the implementation of ESAuthorizationWindowController, if you were wondering why I did some of the things I did in the controller class.
• I plan on writing out a How-to on writing your own Adium plug-ins soon, so watch for that.

The plug-in can be downloaded here: Adium Time Zone Plug-in

The source (GPL Licensed) can be downloaded here: Adium Time Zone Plug-in Source

Enjoy and please let me know what you think!