magic_lamp 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2f6a80fc4bb9835603fed87f0d08b6fad8e6564
-  data.tar.gz: 6b90fee38734efbb331d547e3514edb9ff200d8a
+  metadata.gz: b87fe861fd4ccfea4db716756adf4f5a04d7e645
+  data.tar.gz: cfd72a4b279d340905dea883d6f2c181d1a07e76
 SHA512:
-  metadata.gz: 46143b9947260d1da0c7e45a9cd26c16aa569e682cd1be085b91a4fcbf1714225b0232b1fbf5aa077fdbc17c0379e1c95caa12bbb68e57ffb10385077dca2719
-  data.tar.gz: a0fbd5f0fe9c80ddfb99ff86f90133a2c4faadd30ac6ae45ccf2bb44228dd592f047e3b34615b7b96d0c5af8b8a974cd735e669304ba1a12186ef6a3547474ae
+  metadata.gz: 648a7ad1efcc83b2f452fc866235f200ffa203f450c8f970efb8f098e3caf264e502fe8bde2ede4490f0a5d008ad8291f32f7a5ecc78ed31d17761f1bdbcb68f
+  data.tar.gz: d2e5fadd3b8b04c55b3f4809a5e4b0cc004638232166ac8134119c93a6d1dab895a1ff9b75de736f130f17925e2c914235f8b00198f711c3b24c40ee8acb28ab

data/README.md

@@ -48,15 +48,14 @@ 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).
+at the top of your `spec_helper.js` (assuming you're using [Teaspoon](https://github.com/modeset/teaspoon) or another JavaScript spec runner for Rails that allows the use of Sprockets directives).
+
+(I highly recommend that you use [Teaspoon](https://github.com/modeset/teaspoon) as your JavaScript spec runner.)
 
 Now you've got the basic setup.
 
 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.
@@ -78,8 +77,7 @@ MagicLamp.configure do |config|
   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.
+in a file called `magic_lamp_config.rb` which you can place anywhere in your `spec` or `test` directories.
 
 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.
@@ -90,19 +88,19 @@ Magic Lamp will load all files in your `spec` or `test` directory that end with
 "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:
+In your lamp files you just call [`MagicLamp.fixture`](#fixture) like so:
 ```ruby
-MagicLamp.register_fixture do
+MagicLamp.fixture do
   @order = Order.new
   render partial: "orders/form"
 end
 ```
-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).
+Inside the block you pass to `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.
 
@@ -112,14 +110,14 @@ beforeEach(function() {
   MagicLamp.load("orders/form");
 });
 ```
-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
+which will put the `orders/form` partial in a div with a class of `magic-lamp` (this all happens synchronously).
+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.
 
 ### 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
+to `fixture`. This gives us access to helper methods in the `fixture` block
 and in the template. It also means we don't need a fully qualified path to the rendered template
 or partial.
 
@@ -128,17 +126,17 @@ to render the template the fixture will be named "orders/order".
 
 We're also taking advantage of `render`'s `:collection` option.
 ```ruby
-MagicLamp.register_fixture(controller: OrdersController) do
+MagicLamp.fixture(controller: OrdersController) do
   orders = 3.times.map { Order.new }
   render partial: "order", collection: orders
 end
 ```
 
-Here we're specifying a name with the `:name` option that's passed to `register_fixture`.
+Here we're specifying a name with the `:name` option that's passed to `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.
+of the default `MagicLamp.load("orders/foo")`. Custom names for fixtures must be url safe strings. We're also extending the controller and its view with the `AuthStub` module to stub some methods that we don't want executing in our fixtures.
 ```ruby
-MagicLamp.register_fixture(name: "custom/name") do
+MagicLamp.fixture(name: "custom/name", extend: AuthStub) do
   render "orders/foo"
 end
 ```
@@ -146,12 +144,50 @@ end
 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
+MagicLamp.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).
+
+### Drying up your fixtures
+If you have several fixtures that depend on the same setup (same controller, extensions, etc), you can use the `define` method to dry things up:
+
+```ruby
+MagicLamp.define(controller: OrdersController, extend: AuthStub) do
+  fixture do # orders/new
+    @order = Order.new
+    render :new
+  end
+
+  fixture(name: "customized_new") do # orders/customized_new
+    session[:custom_user_info] = "likes movies"
+    @order = Order.new
+    render :new
+  end
+
+  fixture do # orders/form
+    @order = Order.new
+    render partial: :form
+  end
+
+  define(namespace: "errors", extend: DeadBeatUserStub)
+    fixture(name: "form_without_price") do # orders/errors/form_without_price
+      @order = Order.new
+      @order.errors.add(:price, "can't be blank")
+      render partial: :form
+    end
+
+    fixture do # orders/errors/form
+      @order = Order.new
+      @order.errors.add(:address, "can't be blank")
+      render partial: :form
+    end
+  end
+end
+```
+
 Where the files go
 ------------------------
 ### Config File
@@ -169,57 +205,145 @@ Call `rake magic_lamp:lint` to see if there are any errors when registering or r
 
 Ruby API
 --------
-### register_fixture
+### fixture
+(also aliased to `register_fixture` and `register`)
+
 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`
+  * the controller's name becomes the default `namespace`, ie `OrdersController` provides a default namespace of `orders` resulting in a template named `orders/foo`
 * `: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.
+* `:extend`
+  * takes a module or an array of modules
+  * extends the controller and view context (via Ruby's `extend`)
 Also note that only symbol keys are recognized.
 
-`register_fixture` will also execute any callbacks you've specified. See [configure](#configure) for more.
+`fixture` will also execute any callbacks you've specified. See [configure](#configure) for more.
 
 Example:
 ```ruby
-MagicLamp.register_fixture(name: "foo", controller: OrdersController) do
+MagicLamp.fixture(name: "foo", controller: OrdersController) do
   @order = Order.new
   render partial: :form
 end
 ```
+
+### define
+Allows you scope groups of fixtures with defaults and can be nested arbitrarily. It takes an optional hash and a required block. The hash accepts the following options:
+* `: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`
+  * the controller's name becomes the default `namespace` if no namespace is provided, ie `OrdersController` provides a default namespace of `orders` resulting in a template named `orders/foo`
+* `: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.
+* `:extend`
+  * takes a module or an array of modules
+  * extends the controller and view context (via Ruby's `extend`)
+* `:namespace`
+  * namespaces all fixtures defined within it
+  * overrides the default controller namespace if passed
+Also note that only symbol keys are recognized.
+
+Inside of the block you can nest more calls to `define` and create fixtures
+via the `fixture` method or one of its aliases.
+
+Example:
+```ruby
+module DefinesFoo
+  def foo
+    "foo!"
+  end
+end
+
+module AlsoDefinesFoo
+  def foo
+    "also foo!"
+  end
+end
+
+MagicLamp.define(controller: OrdersController, extend: DefinesFoo) do
+
+  fixture do # orders/edit
+    foo #=> "foo!"
+    @order = Order.create!
+    render :edit
+  end
+
+  fixture do # orders/new
+    foo #=> "foo!"
+    @order = Order.new
+    render :new
+  end
+
+  define(namespace: "errors", extend: AlsoDefinesFoo) do
+
+    fixture do # orders/errors/edit
+      foo #=> "also foo!"
+      @order = Order.create!
+      @order.errors.add(:price, "Can't be negative")
+      render :edit
+    end
+
+    fixture(extend: DefinesFoo) do # orders/errors/new
+      foo #=> "foo!"
+      @order = Order.new
+      @order.errors.add(:price, "Can't be negative")
+      render :new
+    end
+  end
+end
+```
+
 ### 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
+  * called before each block you pass to `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
+  * called after each block you pass to `fixture` is executed
   * note: if you call it a second time with a second block, only the second block will be executed
+* `global_defaults`
+  * can be set to a hash of default options that every fixture generated will inherit from. Options passed to `define` and `fixture` take precedence.
+  * accepts all of the keys `define` accepts
 * `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)
+  * if set to false, the name parameter becomes required for `MagicLamp.fixture` (this can be done to improve performance or force your team to be more explicit)
 
 Example:
 
 ```ruby
+module AuthStub
+  def current_user
+    @current_user ||= User.create!(
+      email: "foo@example.com",
+      password: "password"
+    )
+  end
+end
+
 MagicLamp.configure do |config|
 
-  # if you want to require the name parameter for `MagicLamp.register_fixture`
+  # if you want to require the name parameter for the `fixture` method
   config.infer_names = false
 
+  config.global_defaults = { extend: AuthStub }
+
   config.before_each do
-    puts "I appear before the block passed to register fixture executes!"
+    puts "I appear before the block passed to `fixture` executes!"
   end
 
   config.after_each do
-    puts "I appear after the block passed to register fixture executes!"
+    puts "I appear after the block passed to `fixture` executes!"
   end
 end
 ```
@@ -245,6 +369,8 @@ container if present so you never end up with duplicate fixture containers or en
 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.
 
+The call to get your template is completely synchronous.
+
 Example:
 ```js
   beforeEach(function() {
@@ -256,6 +382,8 @@ Call `MagicLamp.preload` to load all of your templates into MagicLamp's cache. T
 only hit the network once, so the rest of your specs will be quicker and you can go wild stubbing the
 network.
 
+The call to get your templates is completely synchronous.
+
 Example:
 ```js
 // Probably should be in your `spec_helper.js`
@@ -310,8 +438,10 @@ Sweet aliases
 ### Ruby
 
 ```ruby
-MagicLamp.rub => register_fixture
-MagicLamp.wish => register_fixture
+MagicLamp.register_fixture => fixture
+MagicLamp.register => fixture
+MagicLamp.rub => fixture
+MagicLamp.wish => fixture
 ```
 
 ### JavaScript

data/VERSION

@@ -0,0 +1 @@
+1.1.0

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

@@ -76,7 +76,7 @@
       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');
+        this.handleError('Something went wrong, please check the server log or run `rake magic_lamp:lint` for more information');
       }
       return xhr;
     },

data/lib/magic_lamp.rb

@@ -1,34 +1,18 @@
 require "rake"
 
+require "magic_lamp/engine"
+require "magic_lamp/constants"
 require "magic_lamp/callbacks"
 
 require "magic_lamp/configuration"
+require "magic_lamp/defaults_manager"
 require "magic_lamp/fixture_creator"
 require "magic_lamp/render_catcher"
-require "magic_lamp/engine"
 
 require "tasks/lint_task"
 require "tasks/fixture_names_task"
 
 module MagicLamp
-  LAMP = "_lamp"
-  SPEC = "spec"
-  STARS = "**"
-  TEST = "test"
-  Genie = Engine
-
-  class AmbiguousFixtureNameError < StandardError
-  end
-
-  class UnregisteredFixtureError < StandardError
-  end
-
-  class AlreadyRegisteredFixtureError < StandardError
-  end
-
-  class ArgumentError < StandardError
-  end
-
   class << self
     attr_accessor :registered_fixtures, :configuration
 
@@ -36,20 +20,25 @@ module MagicLamp
       Rails.root.join(directory_path)
     end
 
-    def register_fixture(options = {}, &block)
-      controller_class = options.fetch(:controller, ::ApplicationController)
-      raise_missing_block_error(block, __method__)
-      fixture_name = fixture_name_or_raise(options[:name], controller_class, block)
+    def register_fixture(options = {}, &render_block)
+      raise_missing_block_error(render_block, __method__)
+
+      options[:controller] ||= ::ApplicationController
+      options[:namespace] ||= options[:controller].controller_name
+      options[:extend] = Array(options[:extend])
+      options[:render_block] = render_block
+      fixture_name = namespaced_fixture_name_or_raise(options)
 
       if registered?(fixture_name)
         raise AlreadyRegisteredFixtureError, "a fixture called '#{fixture_name}' has already been registered"
       end
 
-      registered_fixtures[fixture_name] = [controller_class, block]
+      registered_fixtures[fixture_name] = options
     end
 
-    alias_method :rub, :register_fixture
-    alias_method :wish, :register_fixture
+    REGISTER_FIXTURE_ALIASES.each do |method_name|
+      alias_method method_name, :register_fixture
+    end
 
     def configure(&block)
       raise_missing_block_error(block, __method__)
@@ -57,6 +46,13 @@ module MagicLamp
       block.call(configuration)
     end
 
+    def define(options = {}, &block)
+      raise_missing_block_error(block, __method__)
+      defaults_manager = DefaultsManager.new(configuration, options)
+      defaults_manager.instance_eval(&block)
+      defaults_manager
+    end
+
     def registered?(fixture_name)
       registered_fixtures.key?(fixture_name)
     end
@@ -75,8 +71,8 @@ module MagicLamp
       unless registered?(fixture_name)
         raise UnregisteredFixtureError, "'#{fixture_name}' is not a registered fixture"
       end
-      controller_class, block = registered_fixtures[fixture_name]
-      FixtureCreator.new(configuration).generate_template(controller_class, &block)
+      controller_class, block, extensions = registered_fixtures[fixture_name].values_at(:controller, :render_block, :extend)
+      FixtureCreator.new(configuration).generate_template(controller_class, extensions, &block)
     end
 
     def generate_all_fixtures
@@ -88,6 +84,32 @@ module MagicLamp
 
     private
 
+    def namespaced_fixture_name_or_raise(options)
+      fixture_name = options.delete(:name)
+      controller_class, render_block = options.values_at(:controller, :render_block)
+      fixture_name = fixture_name_or_raise(fixture_name, controller_class, render_block)
+      namespace_fixture_name(fixture_name, options[:namespace])
+    end
+
+    def namespace_fixture_name(fixture_name, namespace)
+      namespace_without_application = strip_application(namespace)
+      full_name = compose_full_name(namespace_without_application, fixture_name)
+
+      full_name.split(FORWARD_SLASH).each do |namespace_piece|
+        namespace_piece_doubled = [namespace_piece, namespace_piece].join(FORWARD_SLASH)
+        full_name.gsub!(namespace_piece_doubled, namespace_piece)
+      end
+      full_name
+    end
+
+    def strip_application(namespace)
+      namespace.gsub(APPLICATION_MATCHER, EMPTY_STRING)
+    end
+
+    def compose_full_name(namespace, fixture_name)
+      [namespace, fixture_name].select(&:present?).join(FORWARD_SLASH)
+    end
+
     def fixture_name_or_raise(fixture_name, controller_class, block)
       if fixture_name.nil? && configuration.infer_names
         default_fixture_name(controller_class, block)
@@ -118,7 +140,6 @@ module MagicLamp
       if fixture_name.blank?
         raise AmbiguousFixtureNameError, "Unable to infer fixture name"
       end
-      fixture_name = prepend_controller_name(fixture_name, controller_class)
       fixture_name
     end
 
@@ -135,16 +156,6 @@ module MagicLamp
       end
     end
 
-    def prepend_controller_name(fixture_name, controller_class)
-      controller_name = controller_class.controller_name
-      controller_name_regex = Regexp.new("\\A#{controller_name}")
-      if controller_name == "application" || fixture_name.match(controller_name_regex)
-        fixture_name
-      else
-        "#{controller_name}/#{fixture_name}"
-      end
-    end
-
     def directory_path
       Dir.exist?(Rails.root.join(SPEC)) ? SPEC : TEST
     end