capybara-workflows 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e0ced3bcfbcf204817c8806227b5b79452b3e98e
+  data.tar.gz: 621b5b0a3fb3ddd880aa04d71f81fcbde9c5180f
+SHA512:
+  metadata.gz: b15ca25183a838ea484b862af871902f151ebbe926ddfd38022d7558ef5fb45184e24795f04d8c0f452c977943a1fe5f7d180a5a19dc3869099d37c902822336
+  data.tar.gz: 26ba2e5ba1fac9581fad180a32ddfb6cd9e93e44d1d49e3ff37610e370f9688371217709c6d5f5db94ffe480af95b3b4854f4a3c69f53418cd2aef52f8751635

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.ruby-version

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in capybara-workflows.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Nicholas Rutherford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,199 @@
+# Capybara::Workflows
+
+Organise your Capybara helper library into by-role workflow sets or [page objects](https://code.google.com/p/selenium/wiki/PageObjects).
+
+Helpers are executed by the original Capybara session, which you provide by dependency injection, as if you'd written the code where you call the method. All your usual helpers are available.
+
+Example:
+
+```ruby
+specify 'I can enter my qualifications' do
+  qualifications = QualificationWorkflows.new(self)
+  qualifications.add_course 'GCSE', 'Maths', 'A', 'Predicted'
+  qualifications.add_course 'A2', 'Other', 'A*', '2010'
+  qualifications.add_course 'AS', 'Chemistry', 'B', '2011'
+  expect(page).to have_css('tr', text: 'GCSE Maths A Predicted')
+  expect(page).to have_css('tr', text: 'A2 Other A* 2010')
+  expect(page).to have_css('tr', text: 'AS Chemistry B 2011')
+end
+```
+
+Where you have defined the QualificationWorkflows class and its #add_course method as explained below.
+
+
+## Installation
+
+Add to your Gemfile's test group:
+
+```ruby
+gem 'capybara-workflows'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install capybara-workflows
+
+## Usage
+
+How you group things is up to you. This could have been called Capybara::PageObjectModel instead, but I wasn't grouping them that way at time of writing, and don't want to stand on [site_prism's](https://github.com/natritmeyer/site_prism) toes.
+
+That is to say, rather than having classes like
+
+```ruby
+MemberWorkflows.new(self, email, password).log_in
+```
+
+you could instead have
+
+```ruby
+MemberLoginPage.new(self).log_in(email, password)
+```
+
+or whichever structure you care to think of.
+
+All this actually does is enable you to write lines of capybara test code in another class, and share it between test files, reducing LOC and increasing sharing.
+
+The trick is executing that code in the context of the capybara session, not the object holding the helpers. That's why you pass the session in when initialising the object, and why you write workflow blocks rather than method definitions.
+
+
+### Defining workflows
+
+For simplicity you may want to start writing these class definitions directly into your test files, just to get started. See Loading workflows for some ideas how to reorganise later.
+
+```ruby
+class MemberWorkflows < Capybara::Workflows::WorkflowSet
+  # sign in
+  workflow :login_with do |email, password|
+    visit '/member'
+    fill_in("member_email", :with => email)  
+    fill_in("member_password", :with => password)
+    click_button("member_submit")
+  end
+
+  workflow :logout do
+    visit '/member'
+    click_on "Sign out"
+  end
+end
+```
+
+Here's something a little more complex, which tracks previous logins (if made through the same object's interface). The optional workflow parameter gives access to instance variables and other workflow definitions. It's passed to your block as its final argument.
+
+```ruby
+class MemberWorkflows < Capybara::Workflows::WorkflowSet
+  attr_accessor :logged_in, :email, :password
+  def initialize(session, email, password)
+    self.email = email
+    self.password = password
+    self.logged_in = false
+    super(session)
+  end
+
+  # sign in
+  workflow :login do |workflow|
+    unless workflow.logged_in
+      visit '/member'
+      fill_in("member_email", with: workflow.email)
+      fill_in("member_password", with: workflow.password)
+      click_button("member_submit")
+      workflow.logged_in = true
+    end
+  end
+
+  workflow :logout do |workflow|
+    visit '/member'
+    click_on "Sign out"
+    workflow.logged_in = false
+  end
+
+  workflow :post_article do |title, body, workflow|
+    workflow.login unless workflow.logged_in
+    visit new_article_path
+    fill_in "Title", with: title
+    fill_in "Body", with: body
+    click_on "Post article"
+  end
+end
+```
+
+
+
+### Cucumber
+
+Below demonstrates using workflows to help manage state between steps.
+
+```ruby
+Given(/^I am in a group$/) do
+  @group = member.groups.make
+  gm = @group.group_managers.make
+  @group_manager = GroupManagerWorkflows.new(self, gm.email, gm.password)
+end
+
+Then(/^my teacher can't monitor my progress$/) do
+  @group_manager.view_student_progress(@member.email)
+  expect(page).to have_content("has not given you permission to monitor their progress. Please ask them to add you to their supervisor list in their account settings page.")
+end
+
+or
+
+When(/^I go to my account page$/) do
+  MemberWorkflows.new(self).login_with(@member.email, @member.password)
+  ensure_on edit_member_path
+end
+```
+
+### RSpec
+
+```ruby
+describe "doing stuff" do
+  let(:member) {Member.make}
+  before(:each) do
+    MemberWorkflows.new(self).login_with(@member.email, @member.password)
+  end
+end
+```
+
+### Loading workflows
+
+Define workflow classes in spec/support, feature/support, or whichever directory you prefer that will be loaded before your tests run. Or require them explicitly in your tests.
+
+One approach is to put the following snippet into spec/support/load_shared_test_lib.rb for RSpec, and features/support/load_shared_test_lib.rb for Cucumber
+
+```ruby
+  # -*- encoding : utf-8 -*-
+  Dir[
+    File.expand_path(
+      Rails.root.join 'test_helper_lib', '**', '*.rb'
+    )
+  ].each {|f| require f}
+```
+
+We use:
+
+```
+-|
+ |- feature
+ |- spec
+ |- test_helper_lib
+   |- workflows
+     |- member_workflows.rb
+     |- etc
+```
+
+## State encapsulation
+
+Managing state, or context of execution, with shared cucumber steps is not fun. Assigning workflow objects to ivars and letting them track who is logged in, what their attributes are, what they can do, etc, may ease the pain.
+
+For RSpec state encapsulation may or may not be useful, since test statements share scope and are typically easier to manage than Cucumber. However, when sharing with Cucumber it may be simpler to reuse identical workflows.
+
+## Contributing
+
+1. Fork it ( https://github.com/nruth/capybara-workflows/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/capybara-workflows.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'capybara/workflows/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "capybara-workflows"
+  spec.version       = Capybara::Workflows::VERSION
+  spec.authors       = ["Nicholas Rutherford"]
+  spec.email         = ["nick.rutherford@gmail.com"]
+  spec.summary       = %q{Organise your Capybara helper library into by-role workflow sets or page objects}
+  spec.description   = ""
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/capybara/workflows.rb

@@ -0,0 +1,14 @@
+require "capybara/workflows/version"
+
+module Capybara
+  module Workflows
+    # for use in capybara integration tests
+    # session : the test session, where capybara and other libraries/helpers are available
+    class WorkflowSet < Struct.new(:session)
+      def self.workflow(name, &block)
+        workflow = Proc.new do |*args| session.instance_exec(*[*args, self], &block) end
+        define_method(name, &workflow)
+      end
+    end
+  end
+end

data/lib/capybara/workflows/version.rb

@@ -0,0 +1,5 @@
+module Capybara
+  module Workflows
+    VERSION = "0.1.0"
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: capybara-workflows
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicholas Rutherford
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: ''
+email:
+- nick.rutherford@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- capybara-workflows.gemspec
+- lib/capybara/workflows.rb
+- lib/capybara/workflows/version.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Organise your Capybara helper library into by-role workflow sets or page
+  objects
+test_files: []