#40 Code Reading - The Capybara Gem

# dsl.rb
module Capybara
  class << self
    attr_accessor :app
__________________________________________________

# from rspec-rails
# browser_simulators.rb
begin
  require 'capybara/rails'
__________________________________________________

# rails.rb
Capybara.app = Rack::Builder.new do
  map "/" do
    if Rails.version.to_f >= 3.0
      run Rails.application
    else ...
end.to_app

# example.rb
RSpec::configure do |c|
  ...
  c.include RSpec::Rails::RequestExampleGroup, :type => :request, :example_group => {
    :file_path => c.escaped_path(%w[spec (requests|integration)])
  }
__________________________________________________ 

# request_example_group.rb
module RSpec::Rails
  module RequestExampleGroup
    ...
    capybara do
      include Capybara
    end
__________________________________________________

# dsl.rb
module Capybara
  ...
  extend(self)

  def page
    Capybara.current_session
  end

  Session::DSL_METHODS.each do |method|
    class_eval <<-RUBY, __FILE__, __LINE__+1
      def #{method}(*args, &block)
        page.#{method}(*args, &block)
      end
    RUBY
  end
__________________________________________________

# session.rb
module Capybara
  class Session
    DSL_METHODS =
     [
      :all, :attach_file, :body, :check, :choose, :click, :click_button, :click_link,
      :click_link_or_button, :click_on, :current_path, :current_url, :drag, :evaluate_script,
      :field_labeled, :fill_in, :find, :find_button, :find_by_id, :find_field, :find_link,
      :first, :has_button?, :has_checked_field?, :has_content?, :has_css?, :has_field?,
      :has_link?, :has_no_button?, :has_no_content?, :has_no_css?, :has_no_field?,
      :has_no_link?, :has_no_select?, :has_no_selector?, :has_no_table?, :has_no_xpath?,
      :has_select?, :has_selector?, :has_table?, :has_unchecked_field?, :has_xpath?, :locate,
      :save_and_open_page, :select, :source, :uncheck, :unselect, :visit, :wait_until,
      :within, :within_fieldset, :within_frame, :within_table, :within_window
    ]

# session.rb
module Capybara
  class Session

    def driver
      @driver ||= begin
        ...
        Capybara.drivers[mode].call(app)
      end
    end

    def visit(url)
      driver.visit(url)
    end

    def current_url
      driver.current_url
    end
    ...
    def method_missing(*args)
      current_node.send(*args)
    end

    def document
      Capybara::Node::Document.new(self, driver)
    end

    private

    def current_node
      scopes.last
    end

    def scopes
      @scopes ||= [document]
    end

# base.rb
module Capybara
  module Node
    class Base
      attr_reader :session, :base

      include Capybara::Node::Finders
      include Capybara::Node::Actions
      include Capybara::Node::Matchers

      def initialize(session, base) ...
      # 'base' is either a driver object or a driver-node object.
      # In the case of Document, 'base' is a driver object, ie. Capybara::Driver::RackTest
__________________________________________________

# document.rb
module Capybara
  module Node
    class Document < Base
      def inspect ...
__________________________________________________

# element.rb
module Capybara
  module Node
    class Element < Base

      def click
        base.click    # 'base' here refers to a driver-node object, ie. Capybara::Driver::RackTest::Node
      end

      def tag_name
        base.tag_name
      end
      ...
__________________________________________________

# simple.rb
module Capybara
  module Node
    class Simple
      include Capybara::Node::Finders
      include Capybara::Node::Matchers

      attr_reader :native

      def initialize(native)
        native = Nokogiri::HTML(native) if ...

      def text
        native.text
      end
      ...

# actions.rb
module Capybara
  module Node
    module Actions
      
      def click_link(locator)
        ...
        find(:xpath, XPath::HTML.link(locator), :message => msg).click
      end

      def fill_in(locator, options={})
        ...
        find(:xpath, XPath::HTML.fillable_field(locator), :message => msg).set(options[:with])
      end
      ...
__________________________________________________

# matchers.rb
module Capybara
  module Node
    module Matchers
      def has_selector?(*args)
        ...
        wait_conditionally_until do
          results = all(*args)

          case
          when results.empty?
            false
          when options[:between]
            options[:between] === results.size
          ...

      def has_no_selector?(*args)
        ...
        wait_conditionally_until do
          results = all(*args)

          case
          when results.empty?
            true
          when options[:between]
            not(options[:between] === results.size)
          ...
__________________________________________________

# finders.rb
module Capybara
  module Node
    module Finders
      ...
      def find(*args)
        begin
          node = wait_conditionally_until { first(*args) }
        ...

      def first(*args)
        ...
        Capybara::Selector.normalize(*args).each do |path|
          find_in_base(path).each do |node|
            if matches_options(node, options)
              return convert_element(node)
           ...

      def all(*args)
        ...
        Capybara::Selector.normalize(*args).
          map    { |path| find_in_base(path) }.flatten.
          select { |node| matches_options(node, options) }.
          map    { |node| convert_element(node) }
      end
      ....
      protected

      def find_in_base(xpath)
        base.find(xpath)    # 'base' is either a driver object or a driver-node object.
      end

      def convert_element(element)
        Capybara::Node::Element.new(session, element)    # 'element' refers to a driver-node object
      end

# selector.rb
module Capybara
  class Selector
    def xpath(&block)
      @xpath = block if block
      @xpath
    end

    def match(&block)
      @match = block if block
      @match
    end
  ...
  end
end

Capybara.add_selector(:xpath) do
  xpath { |xpath| xpath }
end

Capybara.add_selector(:css) do
  xpath { |css| XPath.css(css) }
end

Capybara.add_selector(:id) do
  xpath { |id| XPath.descendant[XPath.attr(:id) == id.to_s] }
  match { |value| value.is_a?(Symbol) }
end
__________________________________________________

# capybara.rb
...
Capybara.configure do |config|
  ...
  config.default_selector = :css
end

# capybara.rb
...
Capybara.register_driver :rack_test do |app|
  Capybara::Driver::RackTest.new(app)
end
__________________________________________________

# dsl.rb
module Capybara
  class << self
    def current_driver
      @current_driver || default_driver
    end

    def default_driver
      @default_driver || :rack_test
    end
__________________________________________________

# rack_test_driver.rb
class Capybara::Driver::RackTest < Capybara::Driver::Base
  include ::Rack::Test::Methods
  attr_reader :app

  alias_method :response, :last_response
  alias_method :request, :last_request

  def find(selector)
    html.xpath(selector).map { |node| Node.new(self, node) }
  end

  def body
    @body ||= response.body
  end

  def html
    @html ||= Nokogiri::HTML(body)
  end

  ### other public instance methods:
  # body (alias source), current_url, delete, follow_redirects!, get, post, process,
  # put, reset!, response_headers, status_code, submit, to_binary, visit

  ### public instance methods from Rack::Test::Methods
  # "_current_session_name, build_rack_mock_session,
  # build_rack_test_session, current_session, rack_mock_session, 
  # rack_test_session, with_session

  ### public instance methods from Rack::Test::Session via Rack::Test::Methods
  # authorize, basic_authorize, clear_cookies, delete, digest_authorize,
  # follow_redirect!, get, head, header, last_request, last_response, post,
  # put, request, set_cookie
__________________________________________________

# rack_test_driver.rb
class Capybara::Driver::RackTest < Capybara::Driver::Base
  class Node < Capybara::Driver::Node ...
    ### public instance methods:
    # [], checked?, click, find, path, select_option, selected?,
    # set, tag_name, text, unselect_option, value, visible?"
__________________________________________________

# rack_test_driver.rb
class Capybara::Driver::RackTest < Capybara::Driver::Base
  class Form < Node
    ### public instance methods:
    # multipart?, params, submit
__________________________________________________

# rack_test_driver.rb
class Capybara::Driver::RackTest < Capybara::Driver::Base
  class Form < Node
    class NilUploadedFile < Rack::Test::UploadedFile
      ### public instance methods:
      # content_type, original_filename, path

# dsl.rb
module Capybara
  class << self
    def javascript_driver
      @javascript_driver || :selenium
    end
__________________________________________________

# selenium_driver.rb
class Capybara::Driver::Selenium < Capybara::Driver::Base
  attr_reader :app, :rack_server, :options

  def browser
    ...
      @browser = Selenium::WebDriver.for(options[:browser] || :firefox, options)
      ...
  end

  def find(selector)
    browser.find_elements(:xpath, selector).map { |node| Node.new(self, node) }
  end

  ### other public instance methods:
  # body, current_url, evaluate_script, execute_script, reset!, source,
  # visit, wait?, within_frame, within_window

  ### Selenium::WebDriver::Driver methods exposed through #browser
  # [], all, browser, capabilities, close, current_url, execute_script, find_element,
  # find_elements, first, get, manage, navigate, page_source, quit, ref,
  # save_screenshot, screenshot_as, script, switch_to, title, visible=, visible?,
  # window_handle, window_handles
__________________________________________________

# selenium_driver.rb
class Capybara::Driver::Selenium < Capybara::Driver::Base
  class Node < Capybara::Driver::Node
    # public instance methods:
    # [], click, drag_to, find, select_option, selected? (alias checked?),
    # set, tag_name, unselect_option, value, visible?

# celerity_driver.rb
class Capybara::Driver::Celerity < Capybara::Driver::Base
  attr_reader :app, :rack_server, :options

  def browser
    ...
      require 'celerity'
      @_browser = ::Celerity::Browser.new(options)
    ...
  end

  def find(selector)
    browser.elements_by_xpath(selector).map { |node| Node.new(self, node) }
  end
  ### other public instance methods:
  # body, current_url, evaluate_script, execute_script,
  # find, reset!, response_headers, source, status_code, visit, wait?
__________________________________________________

# celerity_driver.rb
class Capybara::Driver::Celerity < Capybara::Driver::Base
  class Node < Capybara::Driver::Node
    ### public instance methods:
    # [], checked?, click, drag_to, find, path, select_option,
    # selected?, set, tag_name, text, trigger, unselect_option,
    # value, visible?
__________________________________________________

# culerity.rb
class Capybara::Driver::Culerity < Capybara::Driver::Celerity
  def self.server ...
  def browser