magic_lamp 0.9.9 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34dc16bf3efdeacd3b5b274d3aae3397b92c9245
-  data.tar.gz: bdf8b8529ece4f4148d3ed6f0ddb32f6dca4c9be
+  metadata.gz: b2f6a80fc4bb9835603fed87f0d08b6fad8e6564
+  data.tar.gz: 6b90fee38734efbb331d547e3514edb9ff200d8a
 SHA512:
-  metadata.gz: 849734d6efead9d19a73bb6e08b41437de7c13d93da14e348e74296f3695f7c8a2a93e9eafdddfc496e991378ee6a999825c5368ab0b60455b9dc3880cb3c892
-  data.tar.gz: 712c6fd03a75c35f9b74ac746d96f15734437fdda425dd33921590a70a0ee43e30d82f359735f66f68f9c35678e60040e87dbc5b7bab9fbc7188bcc267ad5b69
+  metadata.gz: 46143b9947260d1da0c7e45a9cd26c16aa569e682cd1be085b91a4fcbf1714225b0232b1fbf5aa077fdbc17c0379e1c95caa12bbb68e57ffb10385077dca2719
+  data.tar.gz: a0fbd5f0fe9c80ddfb99ff86f90133a2c4faadd30ac6ae45ccf2bb44228dd592f047e3b34615b7b96d0c5af8b8a974cd735e669304ba1a12186ef6a3547474ae

data/README.md

@@ -1,23 +1,40 @@
-# MagicLamp
+Magic Lamp
+=========
+Magic Lamp helps you get your Rails templates into your JavaScript tests. This means that way your JavaScript tests break
+if you change your templates _and_ you don't have to create so many fixtures. Plus, it lets you test your views in JavaScript.
+All you have to do is set up your data just like you would in a controller.
 
-MagicLamp makes sure that your JavaScript tests break when you change a template your code depends on.
+It's not required that you use [Teaspoon](https://github.com/modeset/teaspoon) as your JavaScript test runner, but you should.
 
-## Installation
+Table of Contents
+-----------------
+1. [Installation](#installation)
+2. [Basic Usage](#basic-usage)
+3. [Where the files go](#where-the-files-go)
+4. [Tasks](#tasks)
+5. [Ruby API](#ruby-api)
+6. [JavaScript API](#javascript-api)
+7. [Errors](#errors)
+8. [Sweet Aliases](#sweet-aliases)
+9. [Contributing](#contributing)
 
-Add this line to your application's Gemfile:
-
-    gem "magic_lamp"
+Installation
+------------
 
+Add this line to your application's `Gemfile`:
+```ruby
+  gem "magic_lamp"
+```
 And then execute:
 
-    $ bundle
+    $ bundle install
 
-Or install it yourself as:
+Or install it yourself with:
 
     $ gem install magic_lamp
-## Setup
-### Ruby side
-Fixtures can be registered in any file that ends with `_lamp.rb` anywhere in your `spec` or `test` directory. You'll also need to mount MagicLamp in your `config/routes.rb` like so:
+
+Then paste `mount MagicLamp::Genie, at: "/magic_lamp" if defined?(MagicLamp)` into your `config/routes.rb`
+like so:
 ```ruby
 Rails.application.routes.draw do
   # ...
@@ -25,84 +42,294 @@ Rails.application.routes.draw do
   # ...
 end
 ```
-### JavaScript side
-You can use any rails JavaScript spec runner that runs your application's server. If you're using [Teaspoon](https://github.com/modeset/teaspoon), simply add `//= require magic_lamp` to your `spec_helper.js`.
+This mounts the Magic Lamp engine in your app.
+
+Then drop this:
+```js
+//= require magic_lamp
+```
+at the top of your `spec_helper.js` (assuming your using [Teaspoon](https://github.com/modeset/teaspoon) or another JavaScript spec runner for Rails that
+allows for the use of Sprockets directives).
+
+Now you've got the basic setup.
 
-## Usage
-A fixture can be registered like so:
+In case you need it, [here's an example app](https://github.com/crismali/magic_lamp/tree/master/example).
+
+Note: I highly recommend that you use [Teaspoon](https://github.com/modeset/teaspoon) as your JavaScript spec runner.
+
+### With Database Cleaner
+
+You don't need [Database Cleaner](https://github.com/DatabaseCleaner/database_cleaner) to use this gem, but this is probably the setup most people want.
+
+First make sure you have Database Cleaner installed, then you'll want to do something like this:
+```ruby
+require "database_cleaner"
+
+MagicLamp.configure do |config|
+
+  DatabaseCleaner.strategy = :transaction
+
+  config.before_each do
+    DatabaseCleaner.start
+  end
+
+  config.after_each do
+    DatabaseCleaner.clean
+  end
+end
+```
+in a file called `magic_lamp_config.rb` which you can place anywhere in your `spec` or `test` directories. You could
+ configure Magic Lamp in your `teaspoon_env.rb` file as well.
+
+This way you can take advantage of `after_create` callbacks for your fixture setup without polluting
+your database every time you run your JavaScript specs.
+
+Basic Usage
+-----------
+Magic Lamp will load all files in your `spec` or `test` directory that end with `_lamp.rb` (your app's
+"lamp files). I'd recommend starting with a single `magic_lamp.rb` file and breaking it into smaller
+files once it gets unwieldy (one for each controller would be a good approach).
+
+In your lamp files you just call [`MagicLamp.register_fixture`](#register_fixture) like so:
 ```ruby
 MagicLamp.register_fixture do
   @order = Order.new
-  render "orders/new"
+  render partial: "orders/form"
 end
 ```
-Then in your JavaScript specs you can do this:
+Inside the block you pass to `register_fixture` you're in the scope of a controller so you
+can set up any instance variables your templates depend on. In this case we're using the
+default controller which is your `ApplicationController`. We're also using the default
+name for the fixture which is whatever `render` receives to identify the template (ie
+the symbol or string argument to `render` or whatever is at the `:template` or `:partial`
+key in the argument hash).
+
+`render` here also works normally except that it won't render the layout by default.
+
+Then in your JavaScript you can call [`load`](#load):
 ```js
-MagicLamp.load('orders/new');
+beforeEach(function() {
+  MagicLamp.load("orders/form");
+});
 ```
-which will load the `"orders/new"` template into a `div` with an id of `magic-lamp`.
+which will put the `orders/form` partial in a div with a class of `magic-lamp`. Then you
+can go nuts testing your JavaScript against your actual template. If you'd like to only make
+one request for your templates, simply call [`MagicLamp.preload();`](#preload) in your `spec_helper.js` to
+populate Magic Lamp's cache.
 
-### `MagicLamp#register_fixture`
+### A few more examples
+Here we're specifying which controller should render the template via the arguments hash
+to `register_fixture`. This gives us access to helper methods in the `register_fixture` block
+and in the template. It also means we don't need a fully qualified path to the rendered template
+or partial.
 
-`MagicLamp#register_fixture` requires a block. In this block you are scoped to a controller instance, so you have access to private and public controller methods and that any instance variables set in this block will be available
-to the rendered template.
+Since we didn't specify the name of our fixture and we're not using the `ApplicationController`
+to render the template the fixture will be named "orders/order".
 
-Optionally, `register_fixture` accepts a controller class and the name of the fixture. By default the controller class is `ApplicationController` and the name is what is passed to `render` (either the string, symbol passed in, or the value of the `partial` or `template` key if it's a hash). Here's a more explicit version of the example above:
+We're also taking advantage of `render`'s `:collection` option.
 ```ruby
-MagicLamp.register_fixture(ApplicationController, "orders/new") do
-  @orders = [Order.new, Order.new, Order.new]
-  render "orders/new"
+MagicLamp.register_fixture(controller: OrdersController) do
+  orders = 3.times.map { Order.new }
+  render partial: "order", collection: orders
 end
 ```
-Specifying the controller class gives you access to private methods in the block and helper methods in the template as well as not having to provide the full path to the template or partial.
+
+Here we're specifying a name with the `:name` option that's passed to `register_fixture`.
+This way we can load the fixture in our JavaScript with `MagicLamp.load("custom/name")` instead
+of the default `MagicLamp.load("orders/foo")`. Custom names for fixtures must be url safe strings.
 ```ruby
-MagicLamp.register_fixture(OrdersController) do
-  @order = some_private_method(Order.new)
-  render :index # index contains some special helper method
+MagicLamp.register_fixture(name: "custom/name") do
+  render "orders/foo"
 end
 ```
-In this example, the template will be registered as `"orders/index"`. The default name for a fixture is the controller's name followed by the template (unless it's the `ApplicationController`). If you have name collisions (or if you just want a more informative fixture name), simply specify the name as the second
-argument to `register_fixture`.
+
+Here we're specifying both a controller and custom name. We're also setting the `params[:foo]`
+mostly to demonstrate that we have access to all of the usual controller methods.
+```ruby
+MagicLamp.register_fixture(controller: OrdersController, name: "other_custom_name") do
+  params[:foo] = "test"
+  render :foo
+end
+```
+If you're interested, [here's an example app](https://github.com/crismali/magic_lamp/tree/master/example).
+Where the files go
+------------------------
+### Config File
+Magic Lamp first loads the `magic_lamp_config.rb` file. It can be anywhere in your `spec` or `test`
+directory but it's not required.
+### Lamp files
+Magic Lamp will load any files in your `spec` or `test` directory that end with `_lamp.rb`.
+
+Tasks
+-----
+### fixture_names
+Call `rake magic_lamp:fixture_names` to see a list of all of your app's fixture names.
+### lint
+Call `rake magic_lamp:lint` to see if there are any errors when registering or rendering your fixtures.
+
+Ruby API
+--------
+### register_fixture
+It requires a block that invokes `render` which is invoked in the context of a controller.
+It also takes an optional hash of arguments. The arguments hash recognizes:
+* `:controller`
+  * specifies any controller class that you'd like to have render the template or partial.
+  * if specified it removes the need to pass fully qualified paths to templates to `render`
+* `:name`
+  * whatever you'd like name the fixture.
+  * Specifying this option also prevents the block from being executed twice which could be a performance win. See [configure](#configure) for more.
+Also note that only symbol keys are recognized.
+
+`register_fixture` will also execute any callbacks you've specified. See [configure](#configure) for more.
+
+Example:
 ```ruby
-MagicLamp.register_fixture(ApplicationController, "orders/new/with/errors") do
+MagicLamp.register_fixture(name: "foo", controller: OrdersController) do
   @order = Order.new
-  @errors = true
-  render :new
+  render partial: :form
 end
 ```
-Note: Only name your fixtures with characters that are the same in the url bar of a browser as they are everywhere else.
+### configure
+It requires a block to which it yields the configuration object. Here you can set:
+* `before_each`
+  * takes a block
+  * defaults to `nil`
+  * called before each block you pass to `register_fixture` is executed
+  * note: if you call it a second time with a second block, only the second block will be executed
+* `after_each`
+  * takes a block
+  * defaults to `nil`
+  * called after each block you pass to `register_fixture` is executed
+  * note: if you call it a second time with a second block, only the second block will be executed
+* `infer_names`
+  * defaults to `true`
+  * if set to true, Magic Lamp will try to infer the name of the fixture when not provided with a name parameter.
+  * if set to false, the name parameter becomes required for `MagicLamp.register_fixture` (this can be done to improve performance or force your team to be more explicit)
 
-Also note: blocks using the default name will be executed twice (that's part of the magic required to get sweet defaults). If you don't want that to happen, just name your fixture.
+Example:
 
-### controller#render
-Everything in the block you pass to `register_fixture` is scoped to an instance of the specified controller or the `ApplicationController`. `render` behaves normally for the most part. The only magic here is to set the `layout` option to default to `false`. Aside from that though, it's normal:
 ```ruby
-MagicLamp.register_fixture(OrdersController) do
-  render partial: "order",
-    locals: { foo: "bar" },
-    collection: [Order.new, Order.new, Order.new]
-    # etc.
+MagicLamp.configure do |config|
+
+  # if you want to require the name parameter for `MagicLamp.register_fixture`
+  config.infer_names = false
+
+  config.before_each do
+    puts "I appear before the block passed to register fixture executes!"
+  end
+
+  config.after_each do
+    puts "I appear after the block passed to register fixture executes!"
+  end
 end
 ```
-### MagicLamp JS
-To load a fixture simply call `MagicLamp.load('fixture/name');`. To clear out the fixture `div`, call `MagicLamp.clean();`. If you call `MagicLamp.globalize();`, you be able to call `load` and `clean` right on `window`. If you'd like to preload all of your fixtures so you can stub network requests or something, just call `MagicLamp.preload();`.
 
-The `id` of the `div` MagicLamp creates to hold the fixtures can be specified by setting `MagicLamp.id`.
+JavaScript API
+--------------
+### clean
+Calling `MagicLamp.clean()` will remove the Magic Lamp fixture container from the page.
+
+If you don't want any dom elements from a fixture hanging around between specs, throw it
+in a global `afterEach` block. Calling it with nothing to clean won't result in an error.
+
+Example:
+```js
+  afterEach(function() {
+    MagicLamp.clean();
+  });
+```
+### load
+Call `MagicLamp.load` to load a fixture. It requires the name of the fixture and the fixture
+will be loaded into a `div` with a class of `magic-lamp`. It will destroy the previous fixture
+container if present so you never end up with duplicate fixture containers or end up with
+dom elements from previous loads. It will hit the network only on the first request for a given
+fixture. If you never want `load` to hit the network, call `MagicLamp.preload()` before your specs.
+
+Example:
+```js
+  beforeEach(function() {
+    MagicLamp.load("orders/foo");
+  });
+```
+### preload
+Call `MagicLamp.preload` to load all of your templates into MagicLamp's cache. This means you'll
+only hit the network once, so the rest of your specs will be quicker and you can go wild stubbing the
+network.
 
-### Errors
-If there are any errors rendering your templates, MagicLamp will log them to the server log and throw an error in JavaScript. If the error in the JavaScript doesn't make the source of the problem clear, please check the server log. If that doesn't help, open up a `rails console` and enter `MagicLamp.load_lamp_files` and see if there are any errors. If not, try calling `MagicLamp.generate_all_fixtures` and seeing if the error shows up then.
+Example:
+```js
+// Probably should be in your `spec_helper.js`
+MagicLamp.preload();
+```
+### fixtureNames
+`MagicLamp.fixtureNames()` will return an array of all of the fixture names available in the cache
+(which is all of them if you've called [`preload`](#preload)). It will also `console.log` them out.
 
-### Sweet aliases
-`MagicLamp#register_fixture` is aliased as `rub` and `wish`. On the JavaScript side of things, `load` is `rub` and `wish`. `preload` is `massage` and `wishForMoreWishes`. `clean` is `polish`.
+Example
+```js
+MagicLamp.preload();
+MagicLamp.fixtureNames(); // => ['orders/foo', 'orders/bar', 'orders/baz']
+// logs 'orders/foo'
+// logs 'orders/bar'
+// logs 'orders/baz'
+```
 
-## Contributing
+### globalize
+`MagicLamp.globalize()` will put `MagicLamp.clean` and `MagicLamp.load` onto `window` for convenience.
+
+Example:
+```js
+MagicLamp.globalize();
+
+describe("Foo", function() {
+  beforeEach(function() {
+    load("orders/foo");
+  });
+
+  afterEach(function() {
+    clean();
+  });
+
+  // ...
+});
+```
+Errors
+------
+If there are errors rendering any of your templates, Magic Lamp will often throw a JavaScript
+error. Errors will also appear in your server log (if you're running the in-browser specs).
+
+To see errors outside of the server log (which may be noisy), you can run [`rake magic_lamp:lint`](#tasks)
+which will attempt to render all of your templates. If there are any errors they'll show up there in a
+somewhat less noisy environment.
+
+If you get an `ActionView::MissingTemplate` error, try specifying the controller. This error is caused by a template that renders a partial
+without using the fully qualified path to the partial. Specifying the controller should help Rails find the template.
+
+Sweet aliases
+-------------
+### Ruby
+
+```ruby
+MagicLamp.rub => register_fixture
+MagicLamp.wish => register_fixture
+```
+
+### JavaScript
+```js
+MagicLamp.rub => load
+MagicLamp.wish => load
+MagicLamp.massage => preload
+MagicLamp.wishForMoreWishes => preload
+MagicLamp.polish => clean
+```
 
+Contributing
+------------
 1. Fork it
 2. Clone it locally
-3. `bundle install`
-4. Run the `./bootstrap` script
-5. Run the specs with `rake`
-6. Create your feature branch (`git checkout -b my-new-feature`)
-7. Commit your changes (`git commit -am 'Add some feature'`)
-8. Push to the branch (`git push origin my-new-feature`)
-9. Create new Pull Request
+3. Run the `./bootstrap` script
+4. Run the specs with `rake`
+5. Create your feature branch (`git checkout -b my-new-feature`)
+6. Commit your changes (`git commit -am 'Add some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create new Pull Request

data/app/assets/javascripts/magic_lamp/genie.js

@@ -9,11 +9,12 @@
   Genie.prototype = {
 
     load: function(path) {
+      this.removeFixtureContainer();
       var fixture = this.cache[path];
       this.createFixtureContainer();
 
       if (!fixture && this.cacheOnly) {
-        throw new Error('The fixture "' + path + '" was not preloaded. Is the fixture registered? Such a bummer.');
+        throw new Error('The fixture "' + path + '" was not preloaded. Is the fixture registered? Call `MagicLamp.fixtureNames()` to see what is registered.');
       } else if (!fixture) {
         var xhr = this.xhrRequest(getPath() + '/' + path);
         this.cache[path] = fixture = xhr.responseText;
@@ -24,15 +25,30 @@
     },
 
     preload: function() {
-      this.cacheOnly = true;
       var xhr = this.xhrRequest(getPath());
       var json = JSON.parse(xhr.responseText);
       this.cache = json;
+      this.cacheOnly = true;
+    },
+
+    fixtureNames: function() {
+      var names = [];
+      for (fixtureName in this.cache) {
+        if (this.cache.hasOwnProperty(fixtureName)) {
+          names.push(fixtureName);
+        }
+      }
+      var sortedNames = names.sort();
+      for (var i = 0; i < sortedNames.length; i++) {
+        console.log(sortedNames[i]);
+      };
+
+      return sortedNames;
     },
 
     createFixtureContainer: function() {
       var div = document.createElement('div');
-      div.setAttribute('id', this.namespace.id || 'magic-lamp');
+      div.setAttribute('class', this.namespace.class || 'magic-lamp');
       this.fixtureContainer = div;
     },
 
@@ -41,8 +57,10 @@
     },
 
     removeFixtureContainer: function() {
-      remove(this.fixtureContainer);
-      this.fixtureContainer = undefined;
+      if (this.fixtureContainer) {
+        remove(this.fixtureContainer);
+        this.fixtureContainer = undefined;
+      }
     },
 
     handleError: function(errorMessage) {
@@ -55,10 +73,16 @@
       xhr.open('GET', path, false);
       xhr.send();
 
-      if (xhr.status !== 200) {
+      if (this.xhrStatus(xhr) === 400) {
         this.handleError(xhr.responseText);
+      } else if (this.xhrStatus(xhr) === 500) {
+        this.handleError('Something went wrong while generating the fixture, please check the server log or run `rake magic_lamp:lint` for more information');
       }
       return xhr;
+    },
+
+    xhrStatus: function(xhr) {
+      return xhr.status;
     }
   };
 
@@ -69,7 +93,8 @@
   }
 
   function remove(node) {
-    node.parentNode.removeChild(node);
+    var parentNode = node.parentNode;
+    parentNode && parentNode.removeChild(node);
   }
 
   function newXhr() {