mackarel 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a876a6ccfa611381011f04602f493d657034fca
-  data.tar.gz: 95bf290db7928b83348729c8e700830b33c1adba
+  metadata.gz: ba8d3cddea2ae2293a123036d42f174ee25aeb69
+  data.tar.gz: ca4e02890c971a163a268c97584c5b084581835f
 SHA512:
-  metadata.gz: dc34f92ca95d8a854eb05c7cb2843ab40155bbfcc601f05c93d60127ec8061e837c70a369d6014e7f4002c0608cbc75a87ae469edd23968d2e2b5229c03cfbf8
-  data.tar.gz: 6ea8ca19c4e98f05fe5b8630fd5500c8e7864404f5148f959800302de4b683c94a03b1c1a876339923e164bd8dd3ddfd665c91b06b4ec125102fe8e0111fb624
+  metadata.gz: a0d72af7c7de0dc816758a57b8a17cdbf342de2313293ad61c62052dd12d30b0f0df9c3050d129f34ce440e36ed7a53e3730f61197dd24ed8fd29a5e154995fc
+  data.tar.gz: cac06af1748818c04fe572736e04b886854eb53ccc792d7efa21e4fc863f747681a7a7d767820cecbd0901644612b8b0bdc8f1f939f9a0594410441c11c67614

data/.gitignore

@@ -9,3 +9,4 @@
 /tmp/
 
 *.gem
+/flymd.*

data/README.md

@@ -18,15 +18,23 @@ Or install it yourself as:
 
     $ gem install mackarel
 
-In your spec/spec_helper.rb file add
+In your `spec/spec_helper.rb` or `spec/rails_helper.rb` file add:
 
 ```ruby
-config.include Mackarel
+RSpec.configure { |c| config.include Mackarel }
+```
+
+If you want to use [FactoryGirl](https://github.com/thoughtbot/factory_girl) as the backend for creating assets, add also:
+
+```ruby
+Mackarel.config { |c| c.factory = FactoryGirl }
 ```
 
 ## Usage
 
-Mackarel allows you to write acceptance tests in Rails in a readable way without having to deal with things like Cucumber. It uses feature tests with RSpec, Factorygirl as the factory for models, and generally follows my setup.
+Mackarel allows you to write acceptance tests in Rails in a readable way without having to deal with things like Cucumber.
+
+It uses feature tests with RSpec. It can use Factorygirl as the factory for models, and Capybara for website testing.
 
 You can do things like:
 
@@ -50,7 +58,92 @@ RSpec.feature "Visiting the homepage" do
 end
 ```
 
-### TODO: Document all helpers
+### What are all the things I can do?
+
+#### Yielding
+
+```ruby
+given {}
+when_i {}
+and_also {}
+and_i {}
+then_i {}
+```
+
+These just yield. They are used to increase readibility:
+
+```ruby
+RSpec.feature "Visiting admin page" do
+    scenario "It authenticates" do
+        given { username = "user" }
+        and_also { pass = "pass" }
+
+        when_i { visit admin_page_path }
+        and_i { login_with(username, pass) }
+
+        then_i { expect(page).to have_http_status(200) }
+    end
+end
+```
+
+#### Create objects
+
+```ruby
+create(what, *args, **kwargs, &blk)
+when_there_exists_a(what, *args, **kwargs, &blk)
+when_there_exists_an(what, *args, **kwargs, &blk)
+and_there_exists_a(what, *args, **kwargs, &blk)
+and_there_exists_an(what, *args, **kwargs, &blk)
+```
+
+These generate objects. By default, they use `Mackarel::BasicFactory`
+to do so, but you can change that to use Factorygirl with
+`Mackarel.config.factory = Mackarel::FactoryGirl`, or create your own. See later in this README to see how.
+
+
+Create and friends figure out what you want to call the created
+object: by default, it uses the "what", by converting it to a string,
+downcasing it, and "underscore-ing" it. Also, l You can pass option
+`called:` to change that name. They also return the created object. If
+you pass `called: nil`, they don't create any instance variable.
+
+The `what`, `*args` and `*kwargs` are passed as is to the factory.
+
+For example:
+```
+RSpec.feature "Visiting widget page" do
+    scenario "lists all widgets" do
+        when_i { create Widget, name: "first" }
+        and_there_exist_a Widget, name: "second"
+
+        and_i { visit admin_page_path }
+
+        then_i { can_see "first" }
+        and_i { can_see "second" }
+    end
+end
+```
+
+#### Create lists
+```ruby
+create_a_list_of(n, what, *args, **kwargs, &blk)
+and_there_exist(n, what, *args, **kwargs, &blk)
+when_there_exist(n, what, *args, **kwargs, &blk)
+```
+
+You can also generate lists of objects with one call. To do that, use `create_a_list_of` or one of its aliases. Pass how many objects you want in the list as the first parameter:
+
+```
+RSpec.feature "Visiting widget page" do
+    scenario "lists all widgets" do
+        when_there_exist 5,  Widget, name: "widget"
+        and_i { visit admin_page_path }
+
+        i_find ".widget", count: 5
+    end
+end
+```
+
 
 ## Development
 

data/lib/mackarel/capybara.rb

@@ -6,7 +6,6 @@ module Mackarel
       expect(current_path).to eq path
     end
 
-
     def i_can_see(something)
       expect(page).to have_content(something)
     end

data/lib/mackarel/core.rb

@@ -4,33 +4,42 @@ module Mackarel
       yield
     end
 
-    def factory
-      Mackarel.config.factory
-    end
-
-    def when_there_exists_a(what, *args, **options)
-      called = options.delete(:called) || what.to_s.underscore.tr("/", "_")
+    def create_a(what, *args, called: what, **options)
       asset = factory.create(what, *args, **options)
-      instance_variable_set("@#{called}", asset)
+      if called
+        called = called.to_s.underscore.tr("/", "_")
+        instance_variable_set("@#{called}", asset)
+      end
       yield(asset) if block_given?
+      asset
     end
 
-    def when_there_exist(number, what, *args, **options)
-      called = options.delete(:called) || "#{what.to_s.underscore.tr("/", "_")}_list"
+    def create_a_list_of(number, what, *args, called: "#{what}_list", **options)
       asset = factory.create_list(what, number, *args, **options)
-      instance_variable_set("@#{called}", asset)
+      if called
+        called = called.underscore.tr("/", "_")
+        instance_variable_set("@#{called}", asset)
+      end
       yield(asset) if block_given?
+      asset
+    end
+
+    def factory
+      Mackarel.config.factory
     end
 
     alias and_i when_i
     alias and_also when_i
     alias given when_i
+    alias then_i when_i
 
-    alias when_there_exists_an when_there_exists_a
-    alias and_there_exists_a when_there_exists_a
-    alias and_there_exists_an when_there_exists_a
+    alias when_there_exists_a create_a
+    alias when_there_exists_an create_a
+    alias and_there_exists_a create_a
+    alias and_there_exists_an create_a
 
-    alias and_there_exist when_there_exist
+    alias and_there_exist create_a_list_of
+    alias when_there_exist create_a_list_of
 
   end
 end

data/lib/mackarel/version.rb

@@ -1,3 +1,3 @@
 module Mackarel
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mackarel
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Paolo Gianrossi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-24 00:00:00.000000000 Z
+date: 2017-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler