magic_lamp 0.9.0 → 0.9.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b6f5af7627ea40d33860f5a482bbe73568eccd7
-  data.tar.gz: 719bca7fe3bf9ff43b9281bcab340ab067e25610
+  metadata.gz: 34dc16bf3efdeacd3b5b274d3aae3397b92c9245
+  data.tar.gz: bdf8b8529ece4f4148d3ed6f0ddb32f6dca4c9be
 SHA512:
-  metadata.gz: 864494e38172878be15a56df14285d1f9704c6d7c4cdb7084a963614371ce5f43a06920f7ae11ad6a658cedc4d70574b26b89f6db5463699457aeed403d2d54d
-  data.tar.gz: 28e5256c6730b96de2fd74c6ec94114f27878a97366c5b4e98cd011e10ad6e7c3f612c0aa9866c22c5bb4e3c2d82a5983c2ce8e48d4abf53ef2ac3f2764ce554
+  metadata.gz: 849734d6efead9d19a73bb6e08b41437de7c13d93da14e348e74296f3695f7c8a2a93e9eafdddfc496e991378ee6a999825c5368ab0b60455b9dc3880cb3c892
+  data.tar.gz: 712c6fd03a75c35f9b74ac746d96f15734437fdda425dd33921590a70a0ee43e30d82f359735f66f68f9c35678e60040e87dbc5b7bab9fbc7188bcc267ad5b69

data/README.md

@@ -1,7 +1,6 @@
 # MagicLamp
 
-MagicLamp ensures that if you change some markup in your templates that your JavaScript depends on that
-your tests will break. This is accomplished by generating fixture files from your actual templates just before running your JavaScript specs.
+MagicLamp makes sure that your JavaScript tests break when you change a template your code depends on.
 
 ## Installation
 
@@ -16,89 +15,94 @@ And then execute:
 Or install it yourself as:
 
     $ 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:
+```ruby
+Rails.application.routes.draw do
+  # ...
+  mount MagicLamp::Genie, at: "/magic_lamp" if defined?(MagicLamp)
+  # ...
+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`.
+
 ## Usage
-### Basic usage
-In any file that ends in `_lamp.rb` in your `spec` or `test` directory:
+A fixture can be registered like so:
 ```ruby
-MagicLamp.create_fixture("fixture_name", SomeController) do
-
-  @instance_variable_your_template_depends_on = true
-  # instance variables set in this block will be available to
-  # the template you render. You also have access to the usual
-  # controller methods and helpers here
-  params[:foo] = "some param that's rendered for some reason"
-
-  render :template_to_be_rendered
-  # or
-  # render partial: :partial_to_be_rendered
-  # or
-  # render partial: :foo, collection: [Foo.new, Foo.new, Foo.new]
-  # or
-  # pretty much anything you can normall do with render
+MagicLamp.register_fixture do
+  @order = Order.new
+  render "orders/new"
 end
 ```
-Then if you ran:
-
-    $ rake magic_lamp
-There would be a file called `fixture_name.html` containing the rendered template in `tmp/magic_lamp`.
-A more in depth example can be found below.
-
-### Rake tasks
-The basic tasks are:
-* `rake magic_lamp:create_fixtures` - generates fixtures from `_lamp` files
-* `rake magic_lamp:clean` - deletes fixtures (by removing `tmp/magic_lamp`)
-* `rake magic_lamp` - alias for `rake magic_lamp:create_fixtures`
-
-Since you'll probably always want to run the create fixtures task before you run your JavaScript specs, MagicLamp comes with some convenience tasks that create your fixtures and then immediately run your JavaScript specs:
-* `rake magic_lamp:evergreen` - [Evergreen](https://github.com/abepetrillo/evergreen) integration (you'll need `gem "evergreen", require: "evergreen/rails"` for this to work)
-* `rake magic_lamp:jasmine` - [Jasmine Gem](https://github.com/pivotal/jasmine-gem) integration
-* `rake magic_lamp:jasmine_rails` - [JasmineRails](https://github.com/searls/jasmine-rails) integration
-* `rake magic_lamp:konacha` - [Konacha](https://github.com/jfirebaugh/konacha) integration
-* `rake magic_lamp:teaspoon` - [Teaspoon](https://github.com/modeset/teaspoon) integration
-
-### In depth example
-Let"s assume we have `Order` model and `OrdersController` and that we want to test our JavaScript against the `views/orders/index.html.erb` that looks like this:
-```html
-<ul class="orders">
-<% @orders.each do |order| %>
-  <li>
-    <%= order_name(order) %>
-  </li>
-<% end %>
-</ul>
+Then in your JavaScript specs you can do this:
+```js
+MagicLamp.load('orders/new');
 ```
-The only dependencies in this template are `@orders` and the `order_name` helper method. So anywhere in `spec` or `test` we make a file that ends in `_lamp.rb` and write:
+which will load the `"orders/new"` template into a `div` with an id of `magic-lamp`.
+
+### `MagicLamp#register_fixture`
 
+`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.
+
+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:
+```ruby
+MagicLamp.register_fixture(ApplicationController, "orders/new") do
+  @orders = [Order.new, Order.new, Order.new]
+  render "orders/new"
+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.
+```ruby
+MagicLamp.register_fixture(OrdersController) do
+  @order = some_private_method(Order.new)
+  render :index # index contains some special helper method
+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`.
 ```ruby
-MagicLamp.create_fixture("orders_index", OrdersController) do
-  @orders = [
-    Order.new(name: "foo", id: 1),
-    Order.new(name: "bar", id: 2),
-    Order.new(name: "baz", id: 3)
-  ]
-  render :index
+MagicLamp.register_fixture(ApplicationController, "orders/new/with/errors") do
+  @order = Order.new
+  @errors = true
+  render :new
 end
 ```
-We want our fixture file to be named `orders_index.html`, so we pass in `"orders_index"` as the first argument. We pass in `OrdersController as the second argument because it's the only controller that knows about the `order_name` helper.
-
-So after we run `rake magic_lamp` we end up with a `orders_index.html` file in `tmp/magic_lamp` that looks like this:
-```html
-<ul class="orders">
-  <li>
-    foo: 1
-  </li>
-  <li>
-    bar: 2
-  </li>
-  <li>
-    baz: 3
-  </li>
-</ul>
+Note: Only name your fixtures with characters that are the same in the url bar of a browser as they are everywhere else.
+
+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.
+
+### 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.
+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`.
+
+### 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.
+
+### 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`.
+
 ## Contributing
 
 1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+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

data/app/assets/javascripts/magic_lamp.js

@@ -0,0 +1,2 @@
+//= require magic_lamp/application
+//= require magic_lamp/boot

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

@@ -0,0 +1,14 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require magic_lamp/magic_lamp
+//= require magic_lamp/genie

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

@@ -0,0 +1 @@
+MagicLamp.initialize();

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

@@ -0,0 +1,97 @@
+(function(global) {
+
+  function Genie() {
+    this.cache = {};
+    this.cacheOnly = false;
+    this.namespace = MagicLamp;
+  }
+
+  Genie.prototype = {
+
+    load: function(path) {
+      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.');
+      } else if (!fixture) {
+        var xhr = this.xhrRequest(getPath() + '/' + path);
+        this.cache[path] = fixture = xhr.responseText;
+      }
+
+      this.fixtureContainer.innerHTML = fixture;
+      this.appendFixtureContainer();
+    },
+
+    preload: function() {
+      this.cacheOnly = true;
+      var xhr = this.xhrRequest(getPath());
+      var json = JSON.parse(xhr.responseText);
+      this.cache = json;
+    },
+
+    createFixtureContainer: function() {
+      var div = document.createElement('div');
+      div.setAttribute('id', this.namespace.id || 'magic-lamp');
+      this.fixtureContainer = div;
+    },
+
+    appendFixtureContainer: function() {
+      document.body.appendChild(this.fixtureContainer);
+    },
+
+    removeFixtureContainer: function() {
+      remove(this.fixtureContainer);
+      this.fixtureContainer = undefined;
+    },
+
+    handleError: function(errorMessage) {
+      throw new Error(errorMessage);
+    },
+
+    xhrRequest: function(path) {
+      var xhr = newXhr();
+
+      xhr.open('GET', path, false);
+      xhr.send();
+
+      if (xhr.status !== 200) {
+        this.handleError(xhr.responseText);
+      }
+      return xhr;
+    }
+  };
+
+  // private
+
+  function getPath() {
+    return MagicLamp.path || '/magic_lamp';
+  }
+
+  function remove(node) {
+    node.parentNode.removeChild(node);
+  }
+
+  function newXhr() {
+    var xhr;
+    if (window.XMLHttpRequest) { // Mozilla, Safari, ...
+      xhr = new XMLHttpRequest();
+    } else if (window.ActiveXObject) { // IE
+      try {
+        xhr = new ActiveXObject('Msxml2.XMLHTTP');
+      } catch (error) {
+        try {
+          xhr = new ActiveXObject('Microsoft.XMLHTTP');
+        } catch (e) {
+          // let it go
+        }
+      }
+    }
+    if (!xhr) {
+      throw('Unable to make request');
+    }
+    return xhr;
+  }
+
+  MagicLamp.Genie = Genie;
+})(this);

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

@@ -0,0 +1,35 @@
+var MagicLamp = {
+
+  initialize: function() {
+    this.genie = new this.Genie();
+  },
+
+  globalize: function() {
+    var context = this;
+    window.load = function(path) {
+      context.load(path);
+    };
+    window.clean = function() {
+      context.clean();
+    };
+  },
+
+  load: function() {
+    this.genie.load.apply(this.genie, arguments);
+  },
+
+  preload: function() {
+    this.genie.preload.apply(this.genie, arguments);
+  },
+
+  clean: function() {
+    this.genie.removeFixtureContainer();
+  }
+};
+
+// aliases
+MagicLamp.rub = MagicLamp.load;
+MagicLamp.wish = MagicLamp.load;
+MagicLamp.massage = MagicLamp.preload;
+MagicLamp.wishForMoreWishes = MagicLamp.preload;
+MagicLamp.polish = MagicLamp.clean;

data/app/assets/stylesheets/magic_lamp/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/magic_lamp/application_controller.rb

@@ -0,0 +1,4 @@
+module MagicLamp
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/magic_lamp/fixtures_controller.rb

@@ -0,0 +1,35 @@
+module MagicLamp
+  class FixturesController < ApplicationController
+    ERRORS = [
+      "ArgumentError",
+      "MagicLamp::AlreadyRegisteredFixtureError",
+      "MagicLamp::AmbiguousFixtureNameError",
+      "MagicLamp::UnregisteredFixtureError"
+    ]
+
+    rescue_from(*ERRORS) do |exception, message = exception.message|
+      error_message_with_bactrace = parse_error(exception, message)
+      logger.error(error_message_with_bactrace)
+      render text: message, status: 500
+    end
+
+    def show
+      namespace.load_lamp_files
+      render text: namespace.generate_fixture(params[:name])
+    end
+
+    def index
+      render json: namespace.generate_all_fixtures
+    end
+
+    private
+
+    def parse_error(exception, message)
+      ([message] + exception.backtrace).join("\n\s\s\s\s")
+    end
+
+    def namespace
+      MagicLamp
+    end
+  end
+end

data/app/helpers/magic_lamp/application_helper.rb

@@ -0,0 +1,4 @@
+module MagicLamp
+  module ApplicationHelper
+  end
+end

data/app/views/layouts/magic_lamp/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>MagicLamp</title>
+  <%= stylesheet_link_tag    "magic_lamp/application", media: "all" %>
+  <%= javascript_include_tag "magic_lamp/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,4 @@
+MagicLamp::Engine.routes.draw do
+  root to: "fixtures#index"
+  get "/*name", controller: :fixtures, action: :show
+end

data/lib/magic_lamp.rb

@@ -1,50 +1,113 @@
+require "magic_lamp/fixture_creator"
+require "magic_lamp/render_catcher"
+require "magic_lamp/engine"
+
 module MagicLamp
   LAMP = "_lamp"
-  MAGIC_LAMP = "magic#{LAMP}"
   SPEC = "spec"
   STARS = "**"
   TEST = "test"
-  TMP = "tmp"
-  TMP_PATH = [TMP, MAGIC_LAMP]
+  Genie = Engine
+
+  class AmbiguousFixtureNameError < StandardError
+  end
+
+  class UnregisteredFixtureError < StandardError
+  end
+
+  class AlreadyRegisteredFixtureError < StandardError
+  end
 
   class << self
+    attr_accessor :registered_fixtures
+
     def path
       Rails.root.join(directory_path)
     end
 
-    def create_fixture(fixture_name, controller_class, &block)
-      FixtureCreator.new.create_fixture(fixture_name, controller_class, &block)
+    def register_fixture(controller_class = ::ApplicationController, fixture_name = nil, &block)
+      if block.nil?
+        raise ArgumentError, "MagicLamp#register_fixture requires a block"
+      end
+
+      if fixture_name.nil?
+        fixture_name = default_fixture_name(controller_class, fixture_name, block)
+      end
+
+      if registered?(fixture_name)
+        raise AlreadyRegisteredFixtureError, "a fixture called '#{fixture_name}' has already been registered"
+      end
+
+      registered_fixtures[fixture_name] = [controller_class, block]
     end
 
-    def load_lamp_files
-      create_tmp_directory
-      require_all(Dir[path.join(STARS, "*#{LAMP}.rb")])
+    alias_method :rub, :register_fixture
+    alias_method :wish, :register_fixture
+
+    def registered?(fixture_name)
+      registered_fixtures.key?(fixture_name)
     end
 
-    def tmp_path
-      Rails.root.join(*TMP_PATH)
+    def load_lamp_files
+      self.registered_fixtures = {}
+      load_all(Dir[path.join(STARS, "*#{LAMP}.rb")])
     end
 
-    def create_tmp_directory
-      FileUtils.mkdir_p(tmp_path)
+    def generate_fixture(fixture_name)
+      unless registered?(fixture_name)
+        raise UnregisteredFixtureError, "'#{fixture_name}' is not a registered fixture"
+      end
+      controller_class, block = registered_fixtures[fixture_name]
+      FixtureCreator.new.generate_template(controller_class, &block)
     end
 
-    def remove_tmp_directory
-      FileUtils.rm_rf(tmp_path)
+    def generate_all_fixtures
+      load_lamp_files
+      registered_fixtures.keys.each_with_object({}) do |fixture_name, fixtures|
+        fixtures[fixture_name] = generate_fixture(fixture_name)
+      end
     end
 
     private
 
+    def default_fixture_name(controller_class, fixture_name, block)
+      first_arg = first_render_arg(block)
+      fixture_name = template_name(first_arg).to_s
+      if fixture_name.blank?
+        raise AmbiguousFixtureNameError, "Unable to infer fixture name"
+      end
+      fixture_name = prepend_controller_name(fixture_name, controller_class)
+      fixture_name
+    end
+
+    def first_render_arg(block)
+      render_catcher = RenderCatcher.new
+      render_catcher.first_render_argument(&block)
+    end
+
+    def template_name(render_arg)
+      if render_arg.is_a?(Hash)
+        render_arg[:template] || render_arg[:partial]
+      else
+        render_arg
+      end
+    end
+
+    def prepend_controller_name(fixture_name, controller_class)
+      controller_name = controller_class.controller_name
+      if controller_name == "application"
+        fixture_name
+      else
+        "#{controller_name}/#{fixture_name}"
+      end
+    end
+
     def directory_path
       Dir.exist?(Rails.root.join(SPEC)) ? SPEC : TEST
     end
 
-    def require_all(files)
-      files.each { |file| require file }
+    def load_all(files)
+      files.each { |file| load file }
     end
   end
 end
-
-require "fileutils"
-require "magic_lamp/fixture_creator"
-require "tasks/magic_lamp_tasks"