RequireJs makes dependency management on the client mostly better.  Once it's setup, it's nice.  Getting the patterns of your paths to work correctly can be difficult to setup, depending on the constraints of your system.  Making the same paths work in a prod, test, and build environment can be even more adventuresome.  In my case, there were a few extra hoops.  My scenario might not fully match yours, but perhaps you can apply this solution to your own needs.



## Prod: Loading Modules From a Different Server

Recently, we built a portal.  It contains a bunch of widgets that are served from domains different from the host page.  The portal requested these widget js files via [RequireJs](http://requirejs.org/).  

Because the widgets live on other domains, those widgets' subdependencies needed a path that would be relative to that other widget domain and not the portal domain.  In order to accomplish this, widget dependencies were specified in this way:

```js
define(['./widgetDependency.js'], function (dep) {
  // my widget code
});
``` 

The `.js` extension tells RequireJs to load the dependency [as a URL](https://github.com/jrburke/r.js/blob/2.1.1/require.js#L1521).  The `./` makes the URL relative to the widget domain.

## Test: RequireJs Paths in Testacular

When you go to test your modules in a test environment, you may not want to load your modules as URLs.  Such was the case for me, [running Testacular](http://jaketrent.com/post/test-requirejs-testacular/), where the source code is requested into the context of the test server already.

In prod, I needed the `.js` extension.  But, in test I didn't want to load modules from URLs.  So, I need to make the test environment ignore the extension.  The solution?  Override the regular expression that checks for the extension in my test runner to be something that was never matched:

```js
require.jsExtRegExp = /^pileOTest/;
```

This allows RequireJs to load the module by module name.

#### RequireJs Adds Double .js Extension

It's getting better in the test environment, but we still haven't totally appeased RequireJs.  It turns out that when it loads a module by name, it still has to [convert that name to a path](https://github.com/jrburke/r.js/blob/2.1.1/require.js#L1526).  

Given my constraints (widgets from another domain on a portal), my name actually includes a `.js` extension.  This isn't usually the case.  RequireJs doesn't test for this again (remember, we overrode the regex that did), so it just adds a `.js` extension on the end, creating two: `.js.js`.  

But there is one final way to trick it out:  Add a '?' to the name.  This rule was meant to apply to URLs that represented dynamic scripts (and would thus take query strings) as opposed to static js files.  That's not why we'll add it, but it will help us nonetheless.

So now your module dependencies will look like this:

```js
define(['./widgetDependency.js?'], function (dep) {
  // my widget code
});
``` 

And in your test environment they will load, and you will be happy.  Until...

## Build: Module Names for Optimization

When you go to [optimize your RequireJs modules](http://requirejs.org/docs/optimization.html#basics) you'll again need RequireJs to load your modules by module name instead of url.  If you don't, you'll get nice messages like:

```
>> Tracing dependencies for: MyModule
>> Cannot optimize network URL, skipping: nls/str.js?
>> Error: ENOENT, no such file or directory
>> '/Users/.../style.css?'
>> In module tree:
>>     MyModule
``` 

You may cry a little, but we're almost there.  Remember, your module dependency paths worked just fine in prod.  You only changed them to accommodate the test environment.  So, it's time to change them back when you optimize your module into one file for production use.

The `r.js` configuration in `app.build.js` includes an function called `onBuildRead()`'.  Call it to transform the code as it goes out the door for optimization.  We want to strip out the '?' question marks from our dependency arrays.  Stripping out all '?'s might be a bit too dangerous.  So, let's make a benign adjustment that will help us identify exactly what we're trying to strip out and replace our '?' string in our dependency paths with '?test', finally:

```js
define(['./widgetDependency.js?test'], function (dep) {
  // my widget code
});
``` 

And [implement `onBuildRead`](https://github.com/jrburke/r.js/blob/2.1.1/build/example.build.js#L417) as:

```js
onBuildRead: function (moduleName, path, contents) {  
  return contents.replace(/\?test/g, '');
}
```

#### "Shut off all the garbage smashers on the detention level!"

Take a deep breath.  That was a little much to make all that work.  You have made your RequireJs paths happy in 3 contexts:

1. In production, where modules are served from domains different from the host page and must be loaded by URL.
2. In test, where your modules must be loaded by module name.
3. In the optimization build, where modules must be loaded by module name.

I fill like I've tricked out RequireJs a bit to make this work.  How could we adjust the solution to be more straightforward?

One of the hardest parts of RequireJs can be the pathing.  Making your paths work in prod and in test environments -- even more adventuresome.

RequireJs Paths in Prod, Test, and Build

[Testacular](http://vojtajina.github.com/testacular/) is a test runner for running browser tests.  Once you have it [up and running](http://jaketrent.com/post/test-requirejs-testacular/), you may want to integrate it with your [Grunt](http://gruntjs.com/) build process.  This will allow Testacular to be started and your tests to be run from Grunt.



## grunt-testacular

Lucky for us, [Friedel Ziegelmayer](https://npmjs.org/package/grunt-testacular) has created a nice little plugin, [grunt-testacular](https://npmjs.org/package/grunt-testacular).

To install:

    $ npm install grunt-testacular

Add the current version to your `package.json` for the future:

    "grunt-testacular": "0.2.x"

Import the plugin in your `grunt.js` file:

```js
grunt.loadNpmTasks('grunt-testacular');
```

And finally, in `grunt.js`, specify your tasks:

```js
testacularServer: {
  unit: {
    options: {
      keepalive: true
    },
    configFile: 'testacular.conf.js'
  }
},
testacularRun: {
  unit: {
    runnerPort: 9100
  }
}
```

#### Two Tasks

Grunt-testacular provides two tasks:

1. testacularServer - starts the Testacular server (equivalent to `testacular start`)
2. testacularRun - runs your tests against an already-started server (equivalent to `testacular run`)

#### A grunt-testacular Oddity

If you don't have `keepalive: true` set for grunt-testacular, the Testacular server will shutdown before it has a chance to capture browsers or run your tests.  I'm really not sure why this is even an option.  The false case behavior doesn't seem to be useful.  With the `singleRun` ability of Testacular, the plugin should just call start on the server and let the server configuration decide when it's appropriate to shut down.

**Update:**
I logged an [issue for grunt-testacular](https://github.com/Dignifiedquire/grunt-testacular/issues/3#issuecomment-10234529) that Grunt tasks listed after `testacularServer` weren't being run.  Friedal responded that `keepalive: true` was the problem.  If it is specified true, then it has to be the last task in the list.  So, if you have tasks after `testacularServer` specified, remove `keepalive: true` and add `watch` to the end of your task list.

## Grunt and Testacular Work Flow

Of course, your work flow is up to you, and Grunt and Testacular give you enough flexibility to decide your own, but I think you'll run your tests in two main scenarios: development and continuous integration.

#### Development

For development, I like to start up the Testacular server and keep it running.  Then, I go write tests and update source code.  Testacular will notice my changes and automatically re-run my tests.

To set this up, make sure your grunt-testacular task has this option:

    keepalive: true

This will keep the server up even after the tests have completed.

And make sure your `testacular.conf.js` file includes:

    autoWatch = true;

This will force Testacular to re-run your tests if anything in your source or tests change (specifically, if anything in testacular.conf.js's `files` array changes).

#### Continuous Integration

For continuous integration, you just want your automated build to be able to verify the source code integrity prior to deploying.

We don't want tests to re-run automatically based on our changes, so we turn off `autoWatch` in `testacular.conf.js`:

    autoWatch = false;

And we set one more value in `testacular.conf.js` to:

    singleRun = true;

This will allow the `testacularServer` task to be run once, have Testacular run all the tests, and then make the server shut down.

Finally, remember to keep `keepalive: true` set in `grunt.js`.  Odd, right?

## Multiple Testacular Configurations

To manage the options that are distinct to these two work flows, one could just create two separate `testacular.conf.js` files.  But, that would be overkill, because there'd be a lot of overlap between the two files.

Instead, the grunt-testacular plugin gives you override ability on a per-variable basis.  To support the development and integration scenario, the grunt multiTask might look like this:

```js
testacularServer: {
  unit: {
    options: {
      keepalive: true
    },
    configFile: 'testacular.conf.js'
  },
  integration: {
    options: {
      keepalive: true
    },
    configFile: 'testacular.conf.js',
    autoWatch: false,
    singleRun: true
  }
}
```

Following this same pattern, you could create a separate config for automated functional or end-to-end tests as well.

Note that the `options` object is strictly for the plugin.  The other variables at that level feed straight into Testacular as overrides.

## Integrated Testing

Process and product maturity are increased as tests are integrated into the build process.  Grunt and Testacular make integrating your browser tests a snap.

Grunt and Testacular

Did you write your source code as JavaScript AMD modules in [RequireJs](http://requirejs.org/)?  Do you want to test them in real browsers?  Do you want the flexibility of using [Mocha](http://visionmedia.github.com/mocha/) or [Jasmine](http://pivotal.github.com/jasmine/)?  This is the moment you've been waiting for.

[Testacular is a "spetacular test runner for JavaScript"](http://vojtajina.github.com/testacular/) that was written to support the [AngularJs](http://angularjs.org/) project.  It is valuable because it will run your tests in real browsers.  This is important for front-end code that relies on browser globals such as `window` (eg, if you use jQuery) or that manipulates the DOM (which could vary browser to browser).

Client-side JavaScript testing is a somewhat crazy space.  Some have even called it ["insane"](http://rzrsharp.net/2012/08/01/client-side-testing-insanity.html) and taken drastically different routes than what follows.  But we're gonna see if we can power through, and Testacular will help us get the job done.



## RequireJs Modules

We wrote our source code using RequireJs-implemented AMD modules.  This gives us:

- Clean code organization
- Namespaced code (not global)
- Explicit dependency management
- Source optimized via the RequireJs build

Unfortunately, it also makes our source a bit more tricky to test.

## Testacular RequireJs Support

[RequireJs support was just barely added](https://groups.google.com/forum/?fromgroups=#!topic/testacular/CRsf8Ig4bgE) to Testacular, so it only lives in the canary channel (master).  To install with npm:

    npm install -g testacular@canary

This will currently install version <del datetime="2012-11-05T14:38:54+00:00">0.5.1</del> 0.5.2.  This is the first version of Testacular with RequireJs support.  So your `package.json` should include an entry like:

    "testacular": ">=0.5.2"

If [Testacular](https://npmjs.org/package/testacular) has moved to >=0.6.0, you can use the stable channel.

## Configure Testacular For RequireJs

#### Directory Setup

For clarity in the example configuration files and test below, the directory structure upon which these are based looks like this:

    project/
        lib/
            jquery.js #etc
        node_modules/
            chai/ #etc
        src/
            MyModule.js
        test/
            MyModule.test.js
            test-main.js
    testacular.conf.js


#### Initialize Testacular

Testacular comes with a nice utility for generating a config file (default name: 'testacular.conf.js') that it needs in order to run.  In your terminal, type:

    testacular init

This will give you a series of prompts for things such as paths to source and tests and which browsers to capture.  <del datetime="2012-11-05T14:38:54+00:00">These prompts do not include the option to add RequireJs support automatically, so you'll need to add those lines manually to your `testacular.conf.js` (see below).</del>  As of testacular 0.5.2, `testacular init` will prompt for usage of the RequireJs adapter.

#### Testacular Include

Testacular 0.5.1, while adding RequireJs support, has added a new concept of "included" to the files listed in your config.  This is because RequireJs will balk about a the module not being loaded correctly (ie, loaded synchronously in the `<head/>` tag of the runner).  From the [RequireJs docs](http://requirejs.org/docs/errors.html#mismatch):

> "Be sure to load all scripts that call define() via the RequireJS API. Do not manually code script tags in HTML to load scripts that have define() calls in them."

#### RequireJs Shim

Not immediately apparent is the fact that the 'shim' config from RequireJs 2.x does not work from within Testacular.  I haven't yet figured out why.  For instance, I was constantly getting "'Backbone' is not defined" messages even though it was specified in the 'shim' config and required in the test.  I could have been doing something wrong.  My solution thus far has been to list each of the non-RequireJs modules and their dependencies in the 'files' attribute of `testacular.conf.js`.

#### testacular.conf.js

The final point is that the RequireJs main module for your test runner should be the last file listed.

So, finally, here is the 'file' excerpt of `testacular.conf.js`:

```js
files = [
  MOCHA,
  MOCHA_ADAPTER,
  REQUIRE,
  REQUIRE_ADAPTER,

  // !! libs required for test framework
  {pattern: 'node_modules/chai/chai.js', included: false},

  // !! put what used to be in your requirejs 'shim' config here
  'lib/jquery.js',
  'lib/underscore.js',
  'lib/backbone.js',
  'lib/handlebars.js',

  // !! put all libs in requirejs 'paths' config here (included: false)
  {pattern: 'lib/**/*.js', included: false},

  // !! all src and test modules (included: false)
  {pattern: 'src/**/*', included: false},
  {pattern: 'test/**/*.test.js', included: false},

  // !! test main require module last
  'test/test-main.js'
];
```

This config is awesome.  It replaces an html test runner that you would otherwise have to build.

## RequireJs Main Module

Just like any RequireJs project, you need a main module to bootstrap your tests.  In the main module, you setup the [`require.config`](http://requirejs.org/docs/api.html#config).

#### Testacular '/base' Directory

Testacular serves files under the '/base' directory.  So, on the server, requests to files will be served up under 'http://localhost:9876/base/*'.  The RequireJs config for `baseUrl` gives a starting context for modules that load with relative paths.  When setting this value for the Testacular server, it will need to start with '/base'.  I want my baseUrl to be at the root of my '/src' directory so relative requires in the source won't need to change.  My baseUrl has the value of '/base/src'.

#### Require Each Test File

One of the things I hate is having to update a master list of all tests to run every time I add a test.  Unfortunately, that's what I currently have.  The test main module has to specifically require each of the test modules.  I would love it if I could add a `*.test.js` file to the test directory and just have it run the next time the tests run.

#### Asynchronously Run Testacular

Because the RequireJs require statements are asynchronous, Testacular needs to wait until they're done (the code is loaded and ready) before it starts the tests.

The `main-test.js` file ends up looking like this:

```js
require({

  // !! Testacular serves files from '/base'
  baseUrl: '/base/src',
  paths: {
    require: '../lib/require',
    text: '../lib/text'
  },
}, ['../test/MyModule.test'], function() {
  window.__testacular__.start();
});
```

## RequireJs Test in Testacular

All the setup thus far has been in preparation for the code to follow.  The test can now be setup as a RequireJs module.  It can require the source code under test.  It can use [Mocha](http://visionmedia.github.com/mocha/) (or whatever framework there is a Testacular adapter for).

I will also use [Chai](http://chaijs.com/) in order to get the ['should' BDD-style assertions](http://chaijs.com/guide/styles/).  Note that by using RequireJs and running in the browser, we can't just `require('chai')`.  It has to be required using the asynchronous callback to avoid [this error](http://requirejs.org/docs/errors.html#notloaded):

> Uncaught Error: Module name "../node_modules/chai/chai" has not been loaded yet for context: _. Use require([])

And finally, `should()` must be invoked to be available in the test.

So, a simple test will look like:

```js
define(['../node_modules/chai/chai', 'MyModule'],
  function(chai, MyModule) {

  var assert = chai.assert,
    expect = chai.expect,
    should = chai.should();

  describe('MyModule', function () {
    describe('#initialize()', function () {
      it('should be a stinkin object', function () {
        var yippee = new MyModule();
        yippee.should.be.an('object');
      });
    });
  });
});
```

## Run the Tests in Testacular

There are a couple options set in `testacular.conf.js` that will describe how your tests can be run:

- **singleRun** - Start Testacular server, capture browsers, run all tests, shutdown server
- **autoWatch** - Have the server run tests every time a source or test file changes (and requires you to turn off singleRun)

To start the Testacular server:

    testacular start

Finally, if your Testacular server is already running and you want to kick off the tests, type:

    testacular run

## Now to Test

Thank you to [Vojta Jina](https://github.com/vojtajina) and the rest of the AngularJs crew and other contributors for making an awesome test runner.  I'm very happy that RequireJs support was added.  Vojta has also provided an [end-to-end example](https://github.com/vojtajina/testacular/tree/master/test/e2e/requirejs) with code on Github.

How do you see that we could improve this configuration or testing process?

Now to test some sweet code!