Test driving Catalyst/DBIx::Class development: Introduction

Right now, I’m really big on test driven development. However, I always found it difficult to really apply TDD to my work – my work is not isolated enough to be easily approachable, not to mention I normally make use of a ton of modules that weren’t always designed with the test driven developer in mind. To push myself to learn more about overcoming these challenges, I decided to start work on a hobby project and be as religiously test driven as possible. And as if that wasn’t useful enough, I thought I’d share it all with you in blog form!

---

So, an introduction about the project and motivation first. My text editor of choice is Emacs – it’s hugely extendable with vast amounts of user contributed scripts and plenty of new things to learn about. However, these scripts and this knowledge is very loosely distributed. The best resource at the moment is the Emacs Wiki project, but I have a general distaste for wikis as a main source of information. Contrast this with Vim (a similarly well-extended text editor) and the homepage itself has a repository of scripts and tips.

I’ve decided to start a site my self – M-x customize. M-x customize will hold a repository of scripts and tips, and present them in a structured manor with searching, reviews and ratings. Hopefully in the long run I’ll actually integrate a package manager such as ELPA (I’ve contacted the author, but yet to get a reply).

---

A quick word on technology… because if you’re like me… the cooler the tech the more likely I am to read the blog posts! We’re going to be using Test::Mock – a mocking framework I’m working on in parallel with this project, Catalyst & Moose (of course), and templating with HTML::Zoom.

Next article we’ll get started with finishing the first user story for viewing scripts. Hold tight and watch this space!

I have a home!

I finally got round to setting myself up a little home page – it’s at ocharles.org.uk and styled to look like a Moose class. Eventually, it will actually compile properly and I’ll have it autogenerate my CV (and more!) but for now it’ll do 🙂

Rocket powered rollerskates templating with HTML::Zoom & Catalyst

Matt Trout has produced yet more Perl magic with a new templating system – HTML::Zoom. I’d accuse him of committing a cardinal sin, but I guess we can let him off seeing as it’s badass.

A templating engine isn’t much use unless we’ve got something to drive it – and what’s a more natural choice than Catalyst? As always, Catalyst makes gluing things together trivial – so I’ve adopted some prior art from t0m and released Catalyst::View::HTML::Zoom. Now, this is version 0.001 so it wouldn’t be complete without a big fat blinking disclaimer: we might have done this wrong. I chatted about it briefly in #catalyst before starting work, but I still could have got it wrong! So the API could change and everything might blow up in your face… but that’s the fun, right?

Anyway, here’s a brief look at how we’ve got it structured at the moment (shamelessly plagiarized from my own CPAN synopsis):

package MyApp::View::HTML;
use Moose;
extends 'Catalyst::View::HTML::Zoom';

package MyApp::Controller::Wobble;
use Moose; BEGIN { extends 'Catalyst::Controller' }
sub dance : Local {
    my ($self, $c) = @_;
    $c->stash( shaking => 'hips' );
}

package MyApp::View::HTML::Controller;
use Moose;
sub dance {
    my ($self, $stash) = @_;
    $_->select('#shake')->replace_content($stash->{shaking});
}

#root/wobble/dance
<p>Shake those <span id="shake" />!</p>

/wobble/dance => "<p>Shake those <span id="shake">hips!</span></p>";

The key class here is MyApp::View::HTML::Wobble which does the HTML::Zoom substitutions. $_ is locally aliased to the HTML::Zoom object for convenience and the first parameter is the stash object.

Happy hacking – let’s see where this ends up!

Marketing & CPAN – follow up and an example of changes

If you read my last post, you will have heard me complaining about search.cpan.org’s interface about providing documentation. I argued that the quality of documentation was mixed, though the big projects (where it’s important to get as much wow factor as possible) had some great writing. However, the presentation is thoroughly lacking.

I don’t like complaining without trying to actually help, so I spent a bit of my free time today by making something that tries to incorporate the changes I mentioned.

A Catalyst documentation landing page

It’s probably lacking a little in the punch visually, but just look at that structure. As a new user I’ve got plenty of documentation about getting started – as a developer I’ve got easy access to the important APIs, and if I’m getting really geeky, there’s material for me to geek out with.

Now I should emphasize. None of this content is new – every single one of this pages mirrors something in the Catalyst::Manual. But I think that added structuring and a few explanatory paragraphs has made a world of difference. This change carries over nicely to the documentation pages themselves:

Viewing some Catalyst documentation

A readable structure, and I can jump straight into the content. If you think these arguments still hold for Catalyst, clearly you seen some of the pages…

I should stress that this is nothing more than an idea in my head at the moment. The above aren’t lockups, they are brain dumps. But I’m really keen to try and make this reality – I just don’t know enough about the Perl community to know who to talk to in order to get it done. So, if you want to talk about this – leave some comments and we’ll work something out 🙂 Even advice on who to talk too is much appreciated!

Marketing & CPAN – mutually exclusive?

One of the big efforts in the Perl community at the moment is to address the dreaded “m” word. No, not our mothers – marketing. For some reason, there seems to be 2 distinct camps – those who hate marketing and think it’s evil, and those who understand it’s necessity. Luckily, those in the latter camp are doing a great job of recruiting people who previously disliked this whole marketing thing. I’m blogging from bed right now as I’ve had some thoughts about marketing and the initial impression Perl gives to users.

I started off by considering some massive non-Perl projects – Ruby on Rails, Django and Pylons, to name but a few. All of these projects have their own websites with some pretty nice designs. However, when I think about Perl and the latest and greatest work, only a handful of them have sites. Catalyst has a website that hasn’t changed for years and that does little more to link to search.cpan and a few other places. Moose has a single page with far too many links on, but it’s a step the right direction. DBix::Class doesn’t have a page at all (other than CPAN), though I think it definitely should.

The big problem I have with these 2 examples though is that the are fairly hostile to a new user. I look at Django’s documentation page and it’s nicely structured into some getting started documents, then moving down into some API stuff. Ruby on Rails documentation page is a portal giving me links to guides, or API reference materials. Catalyst’s documentation link gives me… this

What the hell is this? At least, I’d initially think that as a new user. There is extremely little structure, and the only structure there is designed for the machine (Perl namespaces) rather than the reader. A documentation landing page for such an influential project should give clear structures and suck in new users so they are immediately going “Wow, that’s neat!” and of course providing easy navigation for more advanced users to find the exact API documentation they need

Away from the portal itself, I don’t think viewing documentation on CPAN is particularly pretty either. For some things it works nicely (the catalyst tutorials feel like a good start, but there’s still too much cruft at the top of pages). But it could be better – we have no syntax highlighting, we have a very top-to-bottom format (where we could benefit from sidebars) and there is very little room for some other nicities like a “Careful!” or “Pro-tip” style hint boxes

As for API documentation, I think CPAN does a mixed job, which is really a problem with POD not CPAN itself. POD is excellent because it’s so free form, and it sucks because it’s so free form. Documentation is extremely inconsistent when it comes to formatting method calls – there are a variety of different formats. Some people just use the sub name, some people write the parameters in Perl style, some people use a weird DSL that’s not really anything (yes, that’s me!).

So, where am I going with this? In conclusion I think the content that is on CPAN is mixed – but for the big projects it is significantly good. But it is not accessible. There is not enough structure to it for new people to easily orientate themselves. And as we all love CPAN, I think we immediately drop our stuff there and call it a day. The other languages who don’t have tools as big as CPAN can’t have this problem – so people go and make their own site for cool shit and they usually manage to focus on getting some WHAM in there before just plonking out API docs

And where can we go now? This one is hard to say. Search.cpan.org’s layout could do with some improvements and a bit of a refresher for one – cleaner ToCs, syntax highlighting and minor typographic tweaks could all go a long way. I think something that could be excellent is CPAN to provide a different landing page for modules – Github pages comes to mind. If users could create pages inside CPAN, we could do a lot of nice stuff like structuring the documentation better while still leveraging the powerful infrastructure that’s already in place

I give up with Test::Aggregate

I really want to like Test::Aggregate, I really do. But it’s just too damn fragile to get in a decent development environment. I’m really interested in getting our test suite running fast and when Test::Aggregate works, it really does this. Shaving that 1 second off each test adds up pretty fast, and I like that.

However, I do not like this.

That’s the result of the second test in all these aggregates failing, but if I hadn’t told you that, would you have easily known that? The error messages are cryptic as hell. If we do run the second test on its own, TAP does provide the error message (“DBD::Pg::st execute failed: ERROR: column “locale” of relation “artist_alias” does not exist” for the curious).

Until Test::Aggregate can reliably produce these error messages I just can’t bring it into a work environment without risking slowing my colleagues down, which is a real shame as aggregating our tests drops the time down from 248 seconds to just 70. So, the solution?

I see 2 real solutions – the nearest is to use prove -j, which I mentioned earlier, and the second is to help rafl et al work on a forking test harness. I’m really hoping to start work helping in a fortnight. A forking test harness has the benefits of test::aggregate (you can load Catalyst::Test to start a server once, for example), but it doesn’t end up fucking itself quite so hard when things go wrong (the fork might die, at worst). However… (there’s always a but), both of these mean that tests will run in parallel, not in sequence as Test::Aggregate does. The problem with this? Your tests cannot, absolute must, modify the world, and our slow tests are slow partly because they do that – they modify a test database.

What I’d like to press for now, at work at least, is to get all our tests that do not need to test database interactions directly (over half) to talk to mocks, and for our other tests to be run in sequence. Every other test can at least run with prove -j.

App::Prove 3.06 brings some great productivity improvements!

I don’t know how I overlooked this, but App::Prove 3.06 brings some excellent changes that are a massive help to productivity. At work, our test suite can take up to 10 minutes to run (on bad days) which isn’t huge, but when I’m trying to use TDD I find that this is just too slow to be usable. I was discussing this in #catalyst last night, and amongst other great information (some future blog posts lined up, stay tuned!), ijw mentioned that prove --state might be something of interest to me

However, my man entry for prove doesn’t even have a –state option, but looking at App::Prove on CPAN shows that this is a killer feature. Here’s how it works

–state allows you to log the status of App::Prove between runs, and do some interesting things with them. Essentially, state tracking captures the order that tests are ran, and the result of running them. The “failed” state is of most interesting to me, which runs only the tests that failed in the last run. So, in the cases that we introduce a bug somewhere, I can run all the tests, then repeatedly run the failing tests until they all pass.

Another option I’ve just noticed now is the -j option, which allows you to run multiple tests in parallel. Me and rafl have been talking about a forking test harness, which is just a little bit beyond what -j does. -j, like make -j, allows you to specify parallel test execution. If you’re sensible, and your tests don’t interact with the world, this should allow you to run lots of tests together. Sadly, our tests do touch the world, so we can’t do this just yet.