Also, keep in mind that this post is only discussing "JavaScript that runs in browsers". It's not at all concerned with Node.js or npm or anything having to do with dependency management of JavaScript in that ecosystem.

ground rule

Because lots of people use Require and report back that they're getting a lot of value out of it, I think it's important to lay down a quick ground rule before I dive into this post:

There are are many ways to write working software.

Arguments about some tool X that follow "X saved my life!", "I didn't have a need for X", or "X is bad and people who like it should feel bad" are generally not constructive, because—since there are so many ways to write working software—they're all unfalsifiable claims. That is to say, without knowing every detail of one's situation and experience, there's usually no reasonable way to disprove such a statement.

If you're using Require and it's helping you deliver great software, then rock on! That's fantastic. Please keep diving deeper into whatever you do that's working, and keep searching wider for even better methods.

Require is not required

Given that there are many ways to write working software, it should be obvious that working JavaScript-heavy web applications can and are being written without adopting a 3rd-party dependency management system. In fact, I've written some of them!

Because Require seems to have gained so much mindshare this year, I want to spend a few paragraphs exploring my (Require-free) experience to help establish context, then ask some open questions about what value people see in Require, and finally spin a few of my own crackpot conspiracy theories about what's driving Require's success.

my own experience

For some context before talking about Require, I'll talk about the basic structure of most of the JavaScript code I write. The punchline is that in spite of not using Require, I really love almost every aspect of my client-side application development. I simply don't find myself yearning for a third-party dependency management tool.

tiny units

I write really tiny units (whether the unit being considered is a framework's pseudo-class, an anonymous object, or a bag of functions). Usually every method is less than five lines, every file is less than forty lines, and every unit has at most three or four dependencies on other units.

namespaces

I build a namespace as I grow my code and attach it to the window. I usually use my little extend.js library to build namespaces as I go. I pick some brief top-level namespace based on the app name (like "ou" for an app called "Oh, You!") and then I drill-down from there.

For instance, if I was going to declare a new calculator for an invoice report, I might do this:

extend('ou.reports.invoices.CalculatesTotals', function(){
  // imagine an awesome constructor function here
  // ...
})

When extend.js is invoked with a namespace, it will ensure that window.ou.reports.invoices is a JavaScript object, then it will set onto it a property named CalculatesTotals with the supplied function (which could just as well be an object, or CoffeeScript class, or arbitrary value). The important part is that it won't matter what order this file appears in the concatenated source; it should work so long as it's loaded after any 3rd-party vendor libs.

As a result, in a typical large application, the order that scripts are loaded in will usually only matter to two or three (non-third party) files.

Aside from defusing a lot of the risk that load order might otherwise pose, this (very simple and hardly novel) approach to namespacing has a few advantages:

• It's eminently greppable. If I want to access the CalculatesTotals function in the future, I'm probably going to use its fully-qualified name, and I'm certainly going to refer to it as CalculatesTotals. This means I'll always be able to find all references to it in my codebase. (I mention this because I've seen Require used to greatly decrease the greppability of code references because one could write totalCalculator = require('path/to/calculates_totals'), which would make refactoring more error-prone.)
• Files can be split up in a more granular fashion than individual objects. If I were to have one file add some functions to an object with extend('uo.util.sigh', {add: function(){}}), I could add more functions to the same namespace from some other file by calling extend('uo.util.sigh', {subtract: function(){}}) (extend.js will just merge the objects). This is only of moderate utility, but can be really handy during extract & contract refactor operations where needing to keep units & files in lock-step is inconvenient.

feedback-driven code design

I'm really mindful of how each unit depends on each other unit in the systems I write. Out-of-the-blue references to an object property-chain as lengthy as uo.reports.invoices.CalculatesTotal feel weird when they're littered all over a file listing. I appreciate that discomfort, because it forces me to be more thoughtful about my design (whether my reaction will be to decrease the unit's collaborator-count or to inject dependencies as opposed to always explicitly referencing them).

When a load-order bug arises that's above-and-beyond the namespacing strategy above, I know that means I have a code design problem, and I use that bug as feedback that I need to clean up how my units relate to one another at runtime. I'm very confident that this particular design pressure has resulted in better-factored code, particularly code concerned with application initialization that runs as the page finishes loading.

minimal 3rd party dependencies

As I've grown more skilled with JavaScript, the number of tools I keep in my toolbox has gotten smaller, not bigger. I have a handful of libraries I typically reach for, but I've written large applications having only accumulated five or six 3rd party libraries over the course of months.

Not surprisingly, folks who are less proficient with JavaScript tend to grasp eagerly to third party libraries to solve the problems that they encounter, for lack of any alternative. If my app had dozens of uncontrolled third-party libraries all trampling on the global namespace, then a formal module system would probably appeal more to me. As it is, I actually consider as healthy the pressure to hesitate before adding third party libraries. (Besides, the best libraries have a no-conflict mode that yields the namespace control back to the user.)

lots of tests

I love test-driving all those tiny JavaScript units. I personally use Jasmine and a concoction of Jasmine helpers I've written. I'm not even sure why this should be relevant to the discussion of Require, but for the fact I seem to get a lot of e-mail and Github Issues from people trying (and struggling) to use various testing and build tools in the context of apps that use Require.

great build tools

At test double, we wrote Lineman to be a hassle-free way to write fat-client JavaScript apps. It finds and concatenates all of my source files, so I don't have to. I typically don't configure a thing, I just create files and keep working. Whenever I veer off the beaten path, I might have to configure a change in the load order, but it's usually only something I encounter once or twice a month (and hardly a big enough pain to warrant orienting my entire application around Require).

open questions

I'm curious why so many folks adopt Require, especially when they do so on their first JavaScript rodeo.

what value does it add for you?

Given everything I've said above, I'm really curious to know:

What value does Require provide that isn't also met by the (pretty minimal) safeguards I put in place for myself, which I detailed above?

I'd love to see a response post that specifically addresses what someone like me would get out of using Require that I'm currently not getting some other way. Whatever that benefit is, I've so far failed to find it.

why break from the default?

A whole bunch of testing, productivity, build, and deploy tools don't work out-of-the-box with Require. I know, because I maintain a few of them! I feel nothing but sympathy for novice JavaScript developers that open issues while trying to figure out how to use a tool in conjunction with Require, but my more immediate impulse is to ask why?

Why adopt a not-yet-standard approach to developing client-side apps, when every tool and morsel of information you seek will need to be framed within the constraints that Require places on you? Especially if you're new enough to JavaScript that you're not capable of working around the corner cases on your own, why make life more difficult for yourself?

I think about this a lot, because I've found the easiest way to write great code in any given ecosystem is to choose my battles carefully. In general, going with the flow and following defaults & conventions frees me up to spend my intelligence capital on harder, more worthwhile questions.

As a result, if a true AMD standard were to emerge and browsers all incorporated it, I'd absolutely adopt it—even if it was crap! I've convinced myself to love JavaScript (well, CoffeeScript) in spite of its myriad flaws, because I know it's the only show in town if I want to build great experiences on the web. I'd do the same if a standard packaging & dependency management system were to emerge for the browser. (And I hope one does, because having a ubiquitous system for packaging, discovering, and resolving dependencies could drastically improve the infrastructure of the web.)

conspiracy theories

All of my conspiracy theories as to why Require has become popular are rooted in a suspicion that folks are cargo-culting the dependency management systems from languages with which they're more familiar.

The reason I bring up cargo-culting is that most of the developers I see embracing Require are actually novice JavaScript developers coming from another programming ecosystem. This realization was the impetus of my concern that what Require actually addresses is a gap in the understanding of many inexperienced JavaScript developers.

misunderstood weirdness

Everyone knows that JavaScript is weird in relation to other languages, but few can articulate clearly how it is weird. Without clearly understanding what makes JavaScript unusual, it's not surprising that folks exert a lot of effort to attempt to normalize it to meet their expectations.

In this instance, the oddity that Require attempts to normalize is that a JavaScript application is equivalent to the concatenation of its source files.

If you aren't fully cognizant of this aspect of JavaScript's relationship with the browser, then the prospect of going back to a more familiar code organization mechanism would certainly be appealing! That said, I've found this very simple rule to be a liberating constraint. I'm able to visualize front-end JavaScript applications much more efficiently from this frame of mind than I can of the import/require schemes made possible by Java's classpath and Ruby's load paths.

tool envy

Another conspiracy theory of mine is that Require doesn't solve any "real" problem that can't also be solved with a better understanding of JavaScript, and that in general the masses would far prefer to be handed a tool than to be asked to think harder. In this case, that problem being how to design code that's load-order agnostic and doesn't abuse the global namespace.

In software, we see convenience beat simplicity in mindshare all the time, so it's valuable to be mindful of which is being offered by any given tool or method.

In my own experience, any time I've been faced with solving a problem through either (a) "greater understanding" or (b) "adoption of a tool", the increased time investment required by the former has always paid off, whereas the initial convenience of the latter has always cost me down the road. As a result, unless Require solves a problem that's not also solved by "thinking harder about the design of my code", I wouldn't feel an urgency to adopt it.

unabashed cargo-culting

While the previous two examples are derived from the impulse to carry our practices from one ecosystem to another (even if they don't jive with the standards and conventions of the target ecosystem), I think there's a nontrivial number of people who just hate JavaScript and will adopt anything that makes it feel less like JavaScript. I hereby dub this "unabashed" cargo-culting.

That is to say that such people are entirely aware that they're trying to impose their will on a foreign ecosystem and have made up their mind as to the appropriateness and effectiveness of such a strategy. Require definitely makes JavaScript feel more like (most) other environments, and if that's someone's chief consideration, they won't mind paying the price of either a higher cognitive load or tool compatibility issues.

There's really not much more to say about or to this group, as I doubt I'm going to convince them to spend time soaking in JavaScript and learning to love working in the browser.

conclusion

One of the reasons this issue doesn't sit well with me is that I see a lot of people advocating Require to others, but for their own benefit and not for the benefit of the listener. It often feels like Require's fans push for greater adoption in hopes of more first-class support among third-party libraries or more AMD-awareness to be built-into front-end tooling. That wouldn't bother me so much if Require's value proposition was overwhelming and clear, but it really isn't for me.

All of the above said, I'm very much open to persuasion. Consider this post an open invitation to try to sway me on this issue. Feel free to shoot me an e-mail, tweet at me, or author a response post and send me a link. If you do, I'll have been super grateful for your time and thoughts!

Folks have been asking me to share a screencast of how I write Jasmine tests for a few years, so I recorded the session and am providing it online, completely unedited:

This screencast (YouTube) is merely a conversation to provide an answer to the question, "Hey Justin, how would you write a test for __ JavaScript code?" where that blank might be filled with "interacting with the DOM", or "binding user events", or "making AJAX requests". I cover each of those in a way that's similar to how I do it today; I trust that in six months, I'll have evolved and changed my tastes somewhat, but this reflects where I'm at right now.

It's a pretty thorough stream of consciousness—in fact, it's nearly feature-length. That's pretty long for a web video, but if you've struggled to figure out how to write tests for real-world JavaScript (or, if you're just interested in getting inside the head of someone else on the topic), then perhaps 75 minutes will be a reasonable investment of your time.

overview

Now, a few brief notes on the presentation itself.

First, the sample code is hosted on Github at searls/refactor-to-backbone-example. The anonymous jQuery and the Backbone specs can be found on the master-specs and backbone-specs branches, respectively. The application is a Lineman app, and you can find out how to install and run it on Lineman's README.

Second, the presentation is not intended to discuss the values and virtues of either the broader topic of unit testing or these particular tests. Instead, my primary goal was to convey specific testing tactics that can be employed to write unit tests for common JavaScript patterns. It's absolutely the case that some of these tests aren't particularly valuable, but the skill to be able to write them absolutely is.

Finally, there's a logical division that isn't apparent as the video begins, so I'll provide some overview. The first half focuses on going through the admittedly arduous process of characterizing a big ball of anonymous JavaScript with Jasmine tests. The code under test is crufty, so the tests are naturally painful to write—even to me, with several years of daily experience writing Jasmine.

The second half of the presentation is intended to serve as a contrast, because here it's spent characterizing code that's at least been broken up into small(er) units with a named, usable API. In what should shock no one, slightly simpler units lead to slightly simpler tests. This codebase could use even more refactoring, but that's beyond the scope of this discussion.

libraries

I used and described several libraries during the presentation, you can find them here:

• jasmine-fixture
• jasmine-given
• jasmine-stealth
• Lineman
• included with Lineman, testem

Please forgive me for the length of this post, because this is a surprisingly subtle problem. As with most subtle problems, the context and relevant background knowledge are necessary to arrive at a clear understanding of both the problem itself and the causes.

rails background

Ruby on Rails' applications are well-known for being addled with implicit knowledge. The framework itself aims to increase productivity and developer happiness by moving many pieces of knowledge out of the application's source code and into our collective consciousness. Much of this was made possible by Ruby's flexibility, by way of its introspection capabilities (like define_method and method_missing). Even more of this was made possible by establishing a conventional approach to most common tasks. Put another way, to most frameworks, writing no code results in no behavior; in frameworks like Rails, writing no code results in default behavior.

This high-implicit-knowledge environment becomes comfortable with time, and genuinely helps increase productivity (especially at the outset) by helping you to focus on how your application is unique, as opposed to rotely defining how it is not.

It's really quite delightful to become accustomed to the "magical" sensation of the power that negative space has in a Rails application. One becomes used to making significant changes to the appliction by invoking only a single method or adding just one extra entry to an options hash.

falling into the trap

I'm hardly an ActiveRecord expert. I'm not terrifically familiar with its (most recent incarnation's) internals, so I often find myself stumbling around a bit to find a working solution.

This week we found a bug in a very complex chain of Arel scopes. We added a new scope to the chain and in some very narrow situation, we found that our scope wasn't successfully narrowing down the results.

Explaining the entire chain of scopes isn't worth your time, so I'll only give an example of the sort of scope we added. It originally looked like this:

def self.with_unpaid_invoices
  joins(:invoices).
    where('invoices.paid = ?', false)
end

But since that wasn't working in our case, we toyed around a bit and we found a quite easy fix. We just changed "joins" to "includes", like so:

def self.with_unpaid_invoices
  includes(:invoices).
    where('invoices.paid = ?', false)
end

This change fixed the immediate problem we were dealing with. It also turned out to be a bad idea, in no small part because we didn't understand the documented purpose of includes before we put it to use.

joins vs. includes

I'm going to refer to the Rails guide on ActiveRecord querying to shed a little light on the background of joins and includes.

• joins is provided for the purpose of adding JOIN clauses to the SQL that AR generates. This is most often used to narrow results based on some condition(s) of its associated models.
• includes is provided as a solution to the classic "N + 1" query problem that plagues most ORM libraries. Per the guide, "Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the includes method of the Model.find call."

As is patently obvious by juxtaposing the purpose of these two methods, it's clear that their motivations are entirely unrelated. The former seeks to improve the expressiveness of your queries, the latter seeks to improve the performance of your queries.

There's a lurking danger that users might conflate the two (as we did), in that these two features are both used in the same context (when finding records) and both use similar tools to accomplish their task (SQL's INNER JOIN and LEFT OUTER JOIN, respectively).

As is often the case, Rails provides us just enough rope with which to hang ourselves, as is suggested in this section of the guide that immediate follows its descriptions of joins and includes:

12.2 Specifying Conditions on Eager Loaded Associations

Even though Active Record lets you specify conditions on the eager loaded associations just like joins, the recommended way is to use joins instead.

However if you must do this, you may use where as you would normally.

It warns against specifying conditions when using includes, but it doesn't go on to give a compelling reason. Let's continue, and discover why the guide warns us of specifying conditions when using includes.

the includes() side effect

The two methods' apparent similarity begged the question "why, after all, did switching a joins to an includes fix our scope? That smells wrong."

It turned out that the pre-existing lengthy chain of scopes had been using includes and where for their side effect.

You see, because includes uses outer joins to grab your models' associated records in one big query, any conditions that you place on those associations will filter them down, too.

Here's our example domain: Clients have many Invoices which may or may not be paid. Pretend as well that our system has two clients: one with an unpaid invoice and one with no unpaid invoices.

To illustrate, here are some example queries:

> Client.all
=> [#<Client id: 1>, #<Client id: 2>]
> Client.joins(:invoices).where('invoices.paid = ?', false)
=> [#<Client id: 2>]
> Client.includes(:invoices).where('invoices.paid = ?', false)
=> [#<Client id: 2>]

So, as we can see, joins and includes both filter the results as we would expect.

But there is an interesting, subtle difference between the nature of those Client instances.

First, here is what the invoices relationship looks like if we use joins, the recommended means of querying based on associations' criteria:

> clients = Client.joins(:invoices).where('invoices.paid = ?', false)
> clients.first.invoices
=> [#<Invoice id: 2, paid: true, client_id: 2>,
    #<Invoice id: 3, paid: false, client_id: 2>]

As you can see, we searched for "clients with unpaid invoices", and when we actually go look at the invoices of such a client, we get back both its paid and unpaid invoices. This makes sense because the client object is presented to us completely and accurately.

Second, let's look at how this differs when using includes:

> clients = Client.includes(:invoices).where('invoices.paid = ?', false)
=> [#<Client id: 2>]
> clients.first.invoices
=> [#<Invoice id: 3, paid: false, client_id: 2>]

When we use includes, we not only get the "clients with unpaid invoices", we also receive "only the unpaid invoices for each client". At first blush, that can seem pretty cool! If our true intent was to present a list of all of the unpaid invoices of all of our clients, this could actually be quite convenient. We'd fetch everything up front in one big query and the hydrated objects would allow us to present the results just as we wished without further modification.

Obviously, leveraging this side effect intentionally would bear with it a little extra implicit knowledge: the clients returned by such a query wouldn't be "real" clients per se, because their associations won't reflect reality. If we were to pass those clients to another object (or another developer) that was unaware of the nature of these filtered associations, difficult-to-discern bugs might emerge.

And apart from that caveat, there's a catch.

the catch

If one decides to (or merely happens to) take advantage of this side effect, there's a worrisome catch: if the filtered association is subsequently scoped, all of the original filtering disappears.

Take the above example:

> clients = Client.includes(:invoices).where('invoices.paid = ?', false)
=> [#<Client id: 2>]
> invoices = clients.first.invoices
=> [#<Invoice id: 3, paid: false, client_id: 2>]

Next, suppose we want to filter invoices down just a little bit more, in this case we decide to exclude the invoices less than $50:

> invoices.where('amount > ?', 50)
=> [#<Invoice id: 2, paid: true, amount: 100.0, client_id: 2>,
    #<Invoice id: 3, paid: false, amount: 100.0, client_id: 2>]

Woah, woah, woah. That paid invoice came back! That's not what we wanted at all!

As it turns out, by scoping on the filtered association we've lost any filtering-as-side-effect that we attained from includes. And it's not because of how we searched, either; invoking scoped or count on the associated array will have the same effect:

> invoices.count
=> 2
> invoices.scoped
=> [#<Invoice id: 2, paid: true, amount: 100.0, client_id: 2>,
    #<Invoice id: 3, paid: false, amount: 100.0, client_id: 2>]

Huh.

conclusion

Obviously, there's nothing expressly evil about specifying conditions on an included assocation, but I now understand why the Rails Guides might recommend against it. As it turns out, relying on the filtering side effect of includes is quite fragile and error-prone.

As for the situation that led me to this realization, we decided to rework the existing code to eliminate its reliance on this filtering side effect. We went through each of the existing scopes and switched them from includes to joins, then we added (duplicatively) similar scopes to be used on the associated arrays of the results. The approach we landed on will result in more queries at runtime—if a performance problem emerges as a result, we'll tackle it then.

Huge thanks to Angelo Lakra, Jason Rush, and Mr. Todd Kaufman for working with me (and in most cases, teaching me) what was going on in this case. I also pushed the repo that I used to work out this post's example to github.

code comments

Inline comments in code are often maligned for two reasons: (1) well-factored code can be so expressive that additional comments shouldn't be too valuable, and (2) comments often fall out of sync with reality, as only the code must change to implement new behavior.

For example, we can probably all agree that there's a way to obviate the following comment:

#go to the next candidate prime divisor
n += 1

The problem above is that the meaning of n is nearly implicit, and certainly would be if the comment had existed only outside the code listing (or worse, only inside someone's brain). In this case, there's an obviously better place to store that knowledge, in this case, with a better name for the identifier.

candidate_prime_divisor += 1

Now the knowledge and the function are one and the same. I would call this example's knowledge of a number tracking of a candidate prime divisor explicit, because it literally states it.

arguments lacking context

The first example was quite contrived, but here's a method similar to one I ran into today. I struggled mightily to recall some of its intent:

def report_on_payment(recipient, month, regions = [], types = [], save = true)
  save = false if month.current? || regions.any? || types.any?

  report = calculate_report(recipient, month, regions, types)
  save_report(report) if save
  report
end

Regardless of any other issues, it's clear what the thrust of this method is: it generates a report for payments to a recipient for a given month, and sometimes it persists that report.

But upon reading it, two questions fluttered in my mind:

1. Why do regions and types default to blank? Shouldn't default behavior include all possible regions and types?
2. Why is the save flag tripped to false in the presence of any regions or types?

And try as I might, there is nothing explicitly written in that method that can be used to answer those questions. In fact, the only way I managed to figure it out was on account of the fact that I had a part in writing it.

So, what's the missing meaning behind these questions? The answer: there was a bit of implied knowledge floating in the brain of the author: regions and types are used to filter the contents of the report, with an empty array meaning "don't filter".

Prior to the introduction of those filter fields, the meaning of the method was more straightforward:

def report_on_payment(recipient, month, save = true)
  save = false if month.current?

  report = calculate_report(recipient, month)
  save_report(report) if save
  report
end

The basic logic is clearly "each report is calculated for a (recipient, month) tuple and is generally persisted, but never for reports on the current month". This isn't a perfectly simple method, but at least its motives are mostly clear.

Now, knowing that regions and types are meant as fields to filter the contents of the report, we might consider adding that knowledge to the method more explicitly, like so:

def report_on_payment(recipient, month, filters = {:regions => [], :types => []}, save = true)
  save = false if month.current? || filters.values.flatten.any?

  report = calculate_report(recipient, month, filters)
  save_report(report) if save
  report
end

This new implementation is certainly a tad longer, but at least it's now abundantly clear (a) that regions & types are fields by which a user may filter a report's contents, and (b) saving should be disallowed whenever there are any filter options provided.

In this example, it turns out that both of my points of confusion could be assuaged by making our intention more explicit with a single new identifier.

more broadly

This is not to say that implicit knowledge is bad, but that—lest it impede the understanding of others—implicit knowledge carries the hidden cost that it must be spread somehow. Rails, for example, is full of implicit knowledge in the form of conventions and methods missing that we share through documentation and tribal knowledge. Similarly, the design of most business applications is aided by a small lexicon of deeply meaningful nouns—even if that meaning is only shared by a small internal group.

I suppose we must be mindful of balancing knowledge conveyed explicitly in code with knowledge our code relies on implicitly and which must be conveyed by some other means.

introducing a new dependency

It starts when we add a new 3rd party library to our project. Everything is new and exciting!

$ git add jasmine-stealth.js
$ git commit -m 'Adding jasmine-stealth, a cool library I found!'

hacking that dependency

Over time, we add some custom hacks to our dependency to suit the needs of our project. We know it's poor form to directly edit a dependency like this, but in the interest of expediency we did it anyway.

To see what our history after our hacks:

$ git log --oneline jasmine-stealth.js

Which will summarize our commits like this:

3be7a1c hack! add a default stubbing if none is given
36df5a6 hack! in our project, every object responds to
e19149f Adding jasmine-stealth, a cool library I found!

And we can see what the diff looks like, too:

$ git diff e19149f..HEAD jasmine-stealth.js

Our diff looks like:

diff --git a/jasmine-stealth.js b/jasmine-stealth.js
index 31e7956..4216889 100644
--- a/jasmine-stealth.js
+++ b/jasmine-stealth.js
@@ -37,7 +37,7 @@ site: https://github.com/searls/jasmine-stealth
   root.spyOnConstructor = function(owner, classToFake, methodsToSpy) {
     var fakeClass, spies;
     if (methodsToSpy == null) {
-      methodsToSpy = [];
+      methodsToSpy = ['render'];
     }
     if (_(methodsToSpy).isString()) {
       methodsToSpy = [methodsToSpy];
@@ -86,14 +86,14 @@ site: https://github.com/searls/jasmine-stealth

   jasmine.createStub = jasmine.createSpy;

-  jasmine.createStubObj = function(baseName, stubbings) {
+  jasmine.createStubObj = function(baseName, stubbings, defaultStubbing) {
     var name, obj, stubbing;
     if (stubbings.constructor === Array) {
       return jasmine.createSpyObj(baseName, stubbings);
     } else {
       obj = {};
       for (name in stubbings) {
-        stubbing = stubbings[name];
+        stubbing = stubbings[name] || defaultStubbing;
         obj[name] = jasmine.createSpy(baseName + "." + name);
         if (_(stubbing).isFunction()) {
           obj[name].andCallFake(stubbing);

An upgrade appears!

Just when we were enjoying our hacked-up dependency, a new version is released with critical bug fixes! We want to upgrade it, but neither do we want to lose our hacks nor do we want to imagine hand-merging the two.

To start, let's save off our customizations to a patch file:

$ git diff --no-prefix e19149f..HEAD jasmine-stealth.js > hacks.patch

You may have noted that we also add the --no-prefix flag to make the diff easier to apply with the patch tool.

Next, commit the new (and yet-unmodified) upgrade.

$ mv new-jasmine-stealth.js jasmine-stealth.js
$ git add jasmine-stealth.js
$ gc -am 'upgraded jasmine-stealth.js to 0.0.12'

Now, we want to apply our fixes from our saved patch:

$ patch -p0 < hacks.patch

Which yields the happy output:

patching file jasmine-stealth.js

And we can commit those hacks anew:

$ git add jasmine-stealth.js
$ git commit -m 'reapplied hacks'

yay!

This isn't the only way to do this, and it's not the best (in many cases, rebase could be used to preserve the history of the hack commits), but it worked for me today and maybe this example will help you!

Tonight I recorded an 8-minute screencast to show you the ropes:

As time goes on, I'll go into more detail on both our motivations in writing Lineman as well as more advanced usage like overriding configuration defaults.

In the meantime, please give Lineman a spin and tell us what you think!

Working on gimme with Mr. Karns made me realize I'd painted myself into a corner on gimme's API design. I thought I'd share here, for hope that either (a) someone will respond with an approach I like better, or (b) the topic might prove independently useful, and some good will come of this after all.

background

Gimme is a test double library, which is a fancy way to say it makes fake objects for your tests.

Let's imagine an object we want to fake, like:

class Police
  def radar(car)
  end

  def taze!(bro)
  end
end

First, we'd need to ask gimme for a test double:

cop = gimme(Police)

If we wanted to rig the radar reading to be a certain number, we could:

give(cop).radar(my_car) { 90 }

And if we wanted to make sure our cop tazed my bro, we could:

verify(cop).taze!(my_bro)

the initial solution

But what if we don't care about my_car? What if we want the radar to only read 90? (This would be a very sensible desire if the radar was only loosely related to our test and a lot of cars needed to be scanned)

Well, Jason and I landed at an API like this one:

give(cop).radar { 90 }.inarguably

That inarguably flag would basically set up an additional stubbing for the method that would always be satisfied, whether in the presence or absence of arguments.

Verification could work (sort of) similarly.

verify(cop).inarguably.taze!

bad

See the change in ordering? When stubbing, the inarguably configuration comes at the very end of the statement, but when verifying, inarguably is sandwiched in the beginning. That's bound to confuse people., I thought.

Why was it done that way? Primarily, it was because a failed verification will immediate raise an error. Why not do this?

verify(cop).taze!.inarguably

But, alas, a verify can't return an optional configuration object to be invoked after the command, simply because it needs to know whether to raise an error, and there's no way of immediately knowing whether someone will ever call inarguably later.

So we settled for the previous solution. But I still really hate that mismatch; that's exactly the kind of test double design that confuses and frustrates people already confused and frustrated by test doubles!

worse

Then it gets worse! By adding an API like inarguably directly on the object returned by a verify() call, it means that users could not longer verify a method that's actually named "inarguably". That's not cool.

I mean, sure, it's a goofy name. But rubyists love goofy names. And besides, Gimme is likely to accrue other configuration options in the future. I'd hate to set a precedent now that leads to a dozen "magical method names" that, upon being verified, for some reason silently pass. That'd surprise and confuse every user that might run into them.

worst

In my finite wisdom, I decided to tweak give to work just like verify, anyway. So at the moment, you can do either of these things:

give(cop).inarguably.radar { 90 }

Or

verify(cop).inarguably.taze!

And now I have two problems! Users can now neither stub nor verify a method called "inarguably", and any remedy I can think to provide as the library's author (assuming this design stands) would require a user to first realize this limitation.

halp?

So what would you do? I've thought of a couple silly ideas.

a new arg

give(cop, :inarguably).radar { 90 }

and

verify(cop, :inarguably).taze!

Which would require a somewhat-cute implementation, since verify already supports a syntax like verify(cop, 4.times).taze!(bro)

a catch-all config method

I've also thought about future-proofing the concern that we'd one day have a bunch of one-off configuration methods that don't work, by creating just one configuration method to which you'd supply an options hash:

give(cop).configure(:inarguable => true).radar {90}

or

verify(cop).configure(:inarguable => true).taze!

And perhaps both give & verify could simply remove that configuration method as soon as it is used, that way if someone wanted to stub or verify a method with the same name, they could, with something like verify(cop).configure.configure(:foo). Alas, the user would still have to realize what's going on, which makes it a deal breaker.

in conclusion

In conclusion, there is no conclusion. I'm not sure what I want to do. The safest way would be the "a new arg" approach, adding an arg to give and verify, but it's also the one my eyes and fingers like least.

Any feedback on this issue? I'd greatly appreciate it.

All of this reflection has helped me draw this conclusion: the best test suites serve exactly one purpose.

the word "test"

In the beginning of my career, I didn't write any automated tests. Nevertheless, "testing" held several important meanings to me, even when performed manually:

• I'd "test" that each bit of code was working as I wrote
• I'd "test" that I didn't obviously break major functionality before every deploy
• I'd "test" that my boss/customer/peers liked whatever I was building

The fact I could get away with using the word "test" just now to describe the above activities says more about the English language than it does about writing software.

And yet, even though now I leverage automation in the above activities, I still call them all "tests". Tests like the above often fall into buckets labeled something like "unit", "integration", and "end-to-end", respectively.

But "unit", "integration", and "end-to-end" don't really capture the essence of the above activities. At best, they describe the types of interactions those tests are allowed to encounter. (That is, a unit test should be relatively isolated; an end-to-end test should be relatively realistic.) The ratio of isolation-to-realism is a very important thing to understand and think about, certainly, but it's tangential to the purpose of each test.

problems!

So slicing test suites by "degree of realism" has practical justifications. Each level-of-realism brings different automation tools into play. As realism increases, test execution slows down (as do our feedback loops), so cordoning fast tests into a separate suite can improve situations where the entire suite would be too slow to run locally.

But defining our tests by their integrated-ness has raised some problems, too. Problems I don't think we've done a good job addressing.

arbitrariness

Learning automated testing is hard for most developers, but learning the initially-arbitrary-seeming distinctions between tests of one level of integration vs. another is even harder (perhaps because it seems so arbitrary at first).

This arbitrary feeling, I think, is the primary reason why people are so unsure about when using test doubles is appropriate; why teams allow fixtures & factories to become tragedies of the commons; and why so many cycles get wasted on the question "at what level-of-integration should I write this test?"

lack of prompting

This method of test organization doesn't prompt developers at all with any information about why a test exists. Depending on the time of day, my mindset when I sit down to write a test can vary dramatically:

• I'm excited, because I'm writing brand new, unknown code

• I'm cautious, because I don't want future code changes to break this feature

• I'm a nervous wreck, because a bug I'm responsible for just exploded in production

Directory names like faster_specs/, spec/, and features/ don't push me towards putting similarly-motivated tests nearby each other. As a result, some other factor will decide which directory the test goes in—sometimes it's convenience, sometimes it's habit, and sometimes it's even organizational culture.

It's worth noting that my app/ directory doesn't have this problem. Every time I sit down to write code in app, my motivation is "write working code that works well."

test conflation

The above issue, that of arbitrarily lumping differently-motivated tests together, leads to another problem: individual tests that represent numerous purposes.

Remember how terrible it was to see PHP/ASP/JSP/ERB templates like this?

<html>
  <%= javascript_tag do %>
    $(function(){
      $(".<%= my_class_name %>").show()
    });
  <% end %>
  <stylesheet>
    .<%= my_class_name %> { background-color: red; }
  </stylesheet>
</html>

The above example doesn't separate concerns. We've got numerous execution contexts all lumped in a single file. But considering that, a great many tests approached at different times with varying motivations will invariably end up looking similarly!

For example, say I start a test for a new class called TakesOrder. To figure out a design, I might use isolation testing to discover TakesOrder's dependencies:

describe TakesOrder do
  Given(:notifier) { gimme(NotifiesUser) }
  subject { TakesOrder.new(notifier) }
  When { subject.take }
  Then { verify(notifier).notify }
end

Later on, we find a bug in this class and we yell, "Stupid mock! That test didn't give me any assurance at all!". So then we write a test for the bug with a dash of added realism:

describe TakesOrder do
  Given(:notifier) { gimme(NotifiesUser) }
  Given(:user) { FactoryGirl.create(:user) }
  Given { give(notifier).user { user } }
  subject { TakesOrder.new(notifier) }
  When { subject.take }
  Then { verify(notifier).notify }
  Then { user.notifications.size.should == 1 }
end

And now we have a test that both uses test doubles (to aid in design) and also integrates with the database (to guard against regression).

That sucks.

Now every time anyone cracks open the test, they're going to have to waste time deciding whether or not every additional collaborator should be fake or real.

purpose-orientation

Okay, so slicing tests by degree-of-realism isn't perfect. Is there any other way?

Let's return to the various mindsets we adopt when we're writing tests. I'll rattle off off a handful for the sake of discussion:

• We write tests to demonstrate to others (and ourselves) that our software does roughly what we agreed it should do. Maybe we write these on a feature-by-feature basis to gain the approval of a product owner
• We write tests to gain confidence in the design of our code, and (particularly with TDD) we respond to pain caused by these tests by asking ourselves, "can we obviate this pain by improving the design of our production code?"
• We write tests in response to being burned by bugs. In order to ensure a bug doesn't return, we write an automated test that replicates the buggy behavior in order to protect us from future regressions
• We write tests that ensure the overall application is basically in a working state, either to increase our confidence that a build is stable or that our production environment is healthy.

The above motivations are really valuable and interesting, but nearly every application does little-to-nothing to promote the distinction.

What if we sliced our tests into suites based on their purpose instead? Maybe we'd end up with a directory structure like this?

    .
    ├── app
    │   └── app_stuff...
    └── test
        ├── acceptance
        ├── design
        ├── regression
        └── smoke

interesting consequences

If we were to actually do this, it would raise all sorts of interesting questions:

• Would it suck for a single unit to be covered to some degree by three or four different tests? What does it mean when that happens?
• Which of these are most important to run before check-in?
• Which of these are most important to run in CI?
• Would being forced to decide on the most appropriate level-of-integration for a given purposeful test be liberating or paralyzing, I wonder?

conclusion

In any case, I wanted to raise the above issues, because I don't think we've yet arrived at the best way to organize our code in such a way that respects the myriad of reasons we write (and don't write) tests. How about you?

This complaint is commonly levied when—on account of test double setup—you have spec code that looks a lot like the subject's ("SUT's") implementation code. I hear this complaint most often in cases where the subject has little responsibility beyond passing a value from dependency A to dependency B and returning it.

Because isolation tests specify not only the externally observable behavior of the subject, but also the subject's contracts with its collaborators, it should be obvious that isolation testing is going to bring complex interactions with collaborators to the forefront in a way that an integrated test would not.

Before immediately jumping to the conclusion that the use of test doubles is to blame for tests made painful by this fact, it's always helpful to remember that it's just as likely the production code is the root cause of the pain, and that the painful test is merely a symptom. That is to say, instead of responding to that pain in the test by changing how you test, one could use it as an opportunity to change the design so that the code is doing more than manually passing some value from dependency A to B (to C to D).

Say we have this code:

Invoice =
  build: ->
    count = CountCalculator.calculate()
    price = PriceCalculator.calculate(count)
    withTax = TaxCalculator.calculate(price)
    withShipping = ShippingCaclulator.calculate(withTax)

The above code was demanded by this spec:

describe "Invoice", ->
  Given -> window.CountCalculator = calculate: jasmine.createSpy().andReturn(1)
  Given -> window.PriceCalculator = calculate: jasmine.createSpy().when(1).thenReturn(2)
  Given -> window.TaxCalculator = calculate: jasmine.createSpy().when(2).thenReturn(3)
  Given -> window.ShippingCaclulator = calculate: jasmine.createSpy().when(3).thenReturn(4)

  When -> @result = Invoice.build()

  Then -> expect(@result).toEqual(4)

Ouch. Painful test. But it does assert the behavior that we want (even the order we want!). And it does so without any backdoor manipulation of the SUT; it may feel like backdoor manipulation because of the spec's intimate arrangement of everything the SUT will be doing, but this is more of an indictment of the SUT for not doing anything interesting or useful than an indication of wrongdoing on the test's part. [Note: in this contrived example, that nuance might be lost because we're effectively spying on global functions instead of using dependency injection, but I didn't want to risk confusion by making the code snippet any longer than necessary.]

A reaction I often hear from seeing a test like this focuses squarely on the use of test doubles, and the argument goes something like, "because the test resembles the implementation so closely, test doubles shouldn't be used." Usually, the person forwarding the argument will advocate for a coarser, less-isolated test in response to this pain. And, of course, that would probably work fine, and it would probably result in a more readable spec than the one above, but unfortunately it would not take advantage of the greatest strength of isolation testing: alerting you to design problems by inflicting acute pain.

Instead, I'd prefer to address the pain by searching for a way to make the implementation less rote, since it doesn't have any behavior of its own other than to call its collaborators in a series. Once that responsibility has been generalized, new isolation tests will emerge and hopefully be simpler (and, as a side effect, less resemble their production code).

For example, the code above can be refactored like this (the spec still passes):

ChainsCalls =
  chain: (dependencies, method) ->
    _(dependencies).inject((memo, dependency) ->
      dependency[method](memo)
    , undefined)

Invoice =
  build: ->
    ChainsCalls.chain([CountCalculator, PriceCalculator, TaxCalculator, ShippingCaclulator], "calculate")

And after this refactor, we can tidy up our tests so that they mirror the production units:

describe "ChainsCalls", ->
  Given -> @a = go: jasmine.createSpy().andReturn("foo")
  Given -> @b = go: jasmine.createSpy().when("foo").thenReturn("bar")
  When -> @result = ChainsCalls.chain([@a,@b], "go")
  Then -> expect(@result).toBe("bar")

describe "Invoice", ->
  Given -> window.ChainsCalls = chain: jasmine.createSpy()
  Given -> @dependencies = [CountCalculator, PriceCalculator, TaxCalculator, ShippingCaclulator]
  Given -> ChainsCalls.chain.when(@dependencies, "calculate").thenReturn("yay")
  When -> @result = Invoice.build()
  Then -> expect(@result).toEqual("yay")

Obviously the above example is more contrived than most similar situations you'll run into. The point is that when you experience pain while using test doubles, it doesn't necessarily mean that the test doubles or the practice of using them is to blame.

One thing I've learned after several years of trying to become competent at isolation testing: when your tests inflict pain, if you're unwilling or unable to change the design of your production code, then the extra effort to perform rigorous isolation testing (as opposed to relying on fewer, less granular tests that exercise more of your code) is wasted.

This sentiment is often at mind when building an application hand-in-hand with a framework. When your code serves a framework (say, Rails) and the framework causes pain in your isolation tests (like ActiveRecord might), you're often stuck in a bind. You can't reasonably respond to your application's tests' pain by dramatically refactoring the frameworks on which you depend. As a result, the prudent thing to do is often to try to isolate as much of your application code from the framework as you can and to forfeit isolation testing where it's too painful (say, where your objects must extend from framework classes).

If, like me, you're disinclined towards frameworks that rely on users extending framework classes, you can add this justification to your list of reasons why.

And yet, big, rigid companies are everywhere! And they're brimming with employees! Why?

After a few years of trying to change my own big company employer, I realized that I was never going to succeed—so I quit. As my friend Leon says, "you can change where you work, or you can change where you work."

But I was not content to free myself from the shackles of a big company and immediately embrace the liberation I could attain by joining a small company. That seemed like a cop-out; first, I needed to understand why changing even small aspects of a large organization was disproportionately difficult. Surely, thought I, changing large organizations isn't impossible?

To answer that question for myself, I spent about two years consulting with increasingly large, increasingly change-averse companies. Each organization was tremendously well-adapted to succeed, optimized for their own competitive environment. The only problem: over the course of their growth and evolution, they had each built software development organizations that were failing to deliver consistent results over longer periods of time and at larger scales.

In most cases, these companies had begun building an IT organization when the industrial (read: waterfall) metaphor was prominent. Because command-and-control waterfall software management is so demonstrably ineffective, I was confident that helping a company "transform" into a self-organizing, autonomy-granting agile organization would yield everyone great benefits.

We introduced companies to agile principles, values, and practices. We educated and sold agile to executives. We helped train their developers, who were always highly engaged and excited to learn. At the outset, it always seemed that everyone in the company both recognized which things weren't working and agreed that the changes prescribed would—if implemented—drastically improve their organization's effectiveness.

During each engagement, a pilot project that reflected a clean break from the past would succeed wildly. Meanwhile, incremental changes would begin to successfully cascade through the rest of the organization. The first throes of an organizational transformation are highly rewarding (if grueling) work.

But each transformation failed to take hold. Sometimes, they failed spectacularly and all of the change agents within the organization were purged. Sometimes, practices would be retained, but the broader organizational systems would remain soundly intact. And never did I witness a genuine acknowledgement of individual autonomy take root in an organization that had previously been described as "command-and-control".

And these failures were not for lack of trying hard enough! On every project, everyone always brought their "A"-game. But soon after after the initial successes, it was as if the direction of the wind changed. It was like the organization anthropomorphically woke from its slumber and—upon detecting the presence of a foreign body—quickly excised the changes before uneventfully returning to its dormant state.

I've had plenty of time to ponder this and ask myself why this pattern kept repeating.

Over the years, I've adopted (and subsequently discarded) numerous metaphors for organizational change. The only metaphor that I still consider apt is evolution. Consider Richard Dawkins' seminal work, The Selfish Gene. In it, Dawkins demonstrates that not only organisms but even individual genes undergo competition to survive via natural selection. He masterfully extrapolated this discovery: so too do ideas ("memes") and organizations fight for survival as if by natural selection.

Take dinosaurs, for example. As best I understand it, the world saw such large dinosaurs because of the parameters of their competitive environment. In order to survive and reproduce, many species got caught in a sort of arms race with others; this produced ever-larger, ever-more-powerful dinos. But when the environment changed in a fundamental way, dinosaurs' adaptations were ill-equipped to compete and they died off. The top of the food chain was (and is always), comprised of species that are highly optimized for success in the context of their environment.

But whether we're speaking of organizations or organisms, there are two catches with all optimizations:

• Optimizations are contextual. In a fundamentally different environment, a given optimization will most likely be detrimental to success.
• Optimizations are specializations. Switching from one optimization to another requires backtracking to some unoptimized point in order to find a new beginning and a fresh start.

When the competitive landscape requires an organism to change those optimizations, the path to success is typically slow and counter-intuitive. For species, the outmoded adaptations might become (evolutionarily expensive) vestigial traits. For organizations, the recovery often requires starting a brand new subordinate organization that's free from the constraints and assumptions the existing organization acquired while attaining their previous success.

There can be no agility for the highly-optimized

Big companies aren't worse than small companies, they're just more likely to be well-adapted to succeed within their environment. For an organization to undertake operating in a fundamentally different environment, the transformation will always be more costly than it would have been to start a new venture. I believe large software companies are helping us understand this phenomenon, because of software's distinctly low—and ever-decreasing—barrier of entry (in terms of capital). In my mind, this is why RIM is doomed, why Google will take years to grok social product development, why Facebook will flounder in trying to make money from mobile devices, and why Netflix will be years behind schedule when they finally discard DVD rentals.

To prospective employees of big companies: if everything about the company is a great fit for you, then go for it! But, a warning: view any dissonance between you and the company through a very broad lens: that organization became successful by expressly not doing things the way that you wish they did.