isomorfeus-puppetmaster 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b481e8e7cbdaf5306f466442b34746e75b94ae25f0b8c0df4f0f9f1f697ae9d
+  data.tar.gz: '008940290200527c011ec2a629282582943dfb447e0731dfe91c28839844d250'
+SHA512:
+  metadata.gz: 9991f261a20cfc93bed0f58be805beaa0ffd5c6bba33509eac520a334f0ea4efe008005a1b98ef444636785036ecf13ba0bf60a2b2f1282885cdc24b1f3f9e58
+  data.tar.gz: cc1cec085b651ed9611f3dadc3094143d3b73081e7449e00942954bee77f5d43ae9ec5f5cc3baeba16fe61e048c3d91f6066972cfbc85106739404e25644cfd9

data/README.md

@@ -0,0 +1,191 @@
+# isomorfeus-puppetmaster
+
+A framework for acceptance tests or simply running tests in a headless browser. 
+Comes with drivers for chromium headless, firefox and jsdom.
+
+## Chat
+At our [Gitter Isomorfeus Lobby](http://gitter.im/isomorfeus/Lobby) 
+
+## Running on:
+- [CircleCI](https://circleci.com): [![CircleCI](https://circleci.com/gh/isomorfeus/isomorfeus-puppetmaster/tree/master.svg?style=svg)](https://circleci.com/gh/isomorfeus/isomorfeus-puppetmaster/tree/master)
+- [SemaphoreCI 2.0](https://semaphoreci.com): (no badge yet, and i dont know how to link to public 2.0 repos)
+- [TravisCI](https://travis-ci.org): [![Build Status](https://travis-ci.org/isomorfeus/isomorfeus-puppetmaster.svg?branch=master)](https://travis-ci.org/isomorfeus/isomorfeus-puppetmaster)
+ 
+## Installation
+
+In Gemfile:
+`gem 'isomorfeus-puppetmaster'`, then `bundle install`
+
+Also requires the following npm modules with recommended versions:
+
+- puppeteer 1.13.0 - for the chromium driver
+- puppeteer-firefox 0.5.0 - for the firefox driver
+- jsdom 14.0.0 - for the jsdom driver
+- canvas 2.4.1 - for the jsdom driver
+
+Simply install them in your projects root. Puppetmaster also depends on isomorfeus-speednode, which will be installed automatically.
+Speednode will pickup the node modules then from the projects root node_modules directory.
+
+## Configuration
+
+Puppetmaster provides these drivers:
+- chromium - a real browser, headless, fast
+- chromium_debug - opens a chromium browser window with devtools enabled, useful for debugging tests
+- firefox - real firefox, running headless, not so fast
+- firefox_debug - opens a firefox browser window with devtools enabled, useful for debugging tests
+- jsdom - provides a dom implementation in javascript, can execute javascript in the document, super fast, headless, has certain limitations,
+  especially because its not rendering anything (no element bounding box, etc.)
+
+Selecting a driver, for example jsdom:
+```ruby
+Isomorfeus::Puppetmaster.driver = :jsdom
+```
+(chromium is the default driver)
+
+
+Getting the app ready and running:
+1. Assign a rack app
+2. Boot the app
+
+For Example:
+````ruby
+Isomorfeus::Puppetmaster.app = TestApp
+Isomorfeus::Puppetmaster.boot_app
+````
+
+Include the Puppetmaster DSL in the spec_helper.rb:
+```ruby
+RSpec.configure do |config|
+  config.include Isomorfeus::Puppetmaster::DSL
+end
+```
+Ready to play!
+
+## Terminology
+
+There are Browsers which may have windows or tabs, which translate to targets or pages which may contain documents or frames which consist of elements or nodes.
+In Puppetmaster, which is focusing on headless testing, the main "thing" is **just a document**. Its possible to open many documents at once, but what exactly a document is contained in,
+a window or tab or browser or target or whatever, is not of interest.
+A document consists of nodes. Simply working with just documents and nodes makes testing a lot simpler.
+``` 
+document
+    |____head (is a node)
+    |      |
+    |      |___more nodes
+    |      |___...
+    | 
+    |____body (is a node)
+           |
+           |___more nodes
+           |___...
+```
+
+## Basic usage pattern
+
+1. Find something
+2. Interact with it
+
+## Documents
+The drivers open a empty default document, to use that and go to the apps root page:
+```ruby
+doc = visit('/')
+```
+This provides the document `doc` which can further be used to interact with.
+To go to another location, call visit or goto on that doc:
+```ruby
+doc.visit('/login') # or
+doc.goto('/login')
+```
+
+To open another document:
+```ruby
+doc2 = open_new_document('/play')
+```
+
+Both open documents can then be independently interacted with:
+```ruby
+doc.visit('/go')
+doc2.goto('/location')
+```
+
+### Documents and Javascript
+
+#### Executing Javascript
+
+TODO
+
+#### DOM changes by Javascript, Timing
+
+TODO
+ 
+## Nodes
+
+### Finding Nodes ...
+
+Nodes can be found by CSS selectors or XPath queries.
+Node can be found from the document or or other nodes as root.
+
+#### ... with CSS selectors
+
+Documents and nodes provide methods for finding single nodes or a group of nodes with CSS selectors. Examples:
+Find a single node in a document:
+```ruby
+node1 = doc.find('div') # finds the first div in the document
+node2 = doc.find('#super') # find node with id="super"
+```
+Find a single from another node:
+```ruby
+node3 = node1.find('div') # find first div within the node
+```
+
+Find multiple nodes in a document or from a node:
+```ruby
+node_array1 = doc.find_all('div') # finds all div's in a document
+node_array2 = node2.find_all('div') # find all div's within node2
+```
+
+#### ... with XPath queries
+
+Documents and nodes provide methods for finding single nodes or a group of nodes with Xpath queries. Examples:
+Find a single node in a document:
+```ruby
+node1 = doc.find_xpath('//div') # finds the first div in the document
+node2 = doc.find_xpath("//div[contains(@id,'super')]") # find div with id="super"
+```
+Find a single from another node:
+```ruby
+node3 = node1.find_xpath('//div') # find first div within the node
+```
+
+Find multiple nodes in a document or from a node:
+```ruby
+node_array1 = doc.find_all_xpath('//div') # finds all div's in a document
+node_array2 = node2.find_all_xpath('//div') # find all div's within node2
+```
+
+### Interacting with nodes
+
+Puppetmaster provides methods for emulating user interactions with nodes or documents.
+
+### Mouse
+```ruby
+node1.click
+```
+TODO
+
+### Keyboard
+```ruby
+node4 = doc.find('input')
+node4.type_keys('Message')
+```
+TODO
+
+### Fingers
+TODO
+
+
+### Tests
+To run tests:
+- clone repo
+- `bundle install`
+- `bundle exec rake`

data/lib/isomorfeus-puppetmaster.rb

@@ -0,0 +1,43 @@
+require 'active_support/core_ext/string'
+require 'uri'
+require 'net/http'
+require 'rack'
+
+require 'isomorfeus-speednode'
+
+# use execjs speednode for sure, unless something else has been specified
+unless ENV["EXECJS_RUNTIME"]
+  ExecJS.runtime = ExecJS::Runtimes::Speednode
+end
+
+require 'isomorfeus/puppetmaster'
+require 'isomorfeus/puppetmaster/self_forwardable'
+require 'isomorfeus/puppetmaster/errors'
+require 'isomorfeus/puppetmaster/cookie'
+require 'isomorfeus/puppetmaster/console_message'
+require 'isomorfeus/puppetmaster/request'
+require 'isomorfeus/puppetmaster/response'
+require 'isomorfeus/puppetmaster/node'
+require 'isomorfeus/puppetmaster/node/content_editable'
+require 'isomorfeus/puppetmaster/node/input'
+require 'isomorfeus/puppetmaster/node/checkbox'
+require 'isomorfeus/puppetmaster/node/filechooser'
+require 'isomorfeus/puppetmaster/node/radiobutton'
+require 'isomorfeus/puppetmaster/node/select'
+require 'isomorfeus/puppetmaster/node/textarea'
+require 'isomorfeus/puppetmaster/document'
+require 'isomorfeus/puppetmaster/iframe'
+require 'isomorfeus/puppetmaster/driver/puppeteer_document'
+require 'isomorfeus/puppetmaster/driver/puppeteer_node'
+require 'isomorfeus/puppetmaster/driver/puppeteer'
+require 'isomorfeus/puppetmaster/driver/jsdom_document'
+require 'isomorfeus/puppetmaster/driver/jsdom_node'
+require 'isomorfeus/puppetmaster/driver/jsdom'
+require 'isomorfeus/puppetmaster/driver_registration'
+
+require 'isomorfeus/puppetmaster/server/middleware'
+require 'isomorfeus/puppetmaster/server/checker'
+require 'isomorfeus/puppetmaster/server'
+require 'isomorfeus/puppetmaster/server_registration'
+
+require 'isomorfeus/puppetmaster/dsl'

data/lib/isomorfeus/puppetmaster.rb

@@ -0,0 +1,62 @@
+module Isomorfeus
+  module Puppetmaster
+    class << self
+      attr_accessor :app, :server_port, :session
+      attr_writer :save_path, :server_host, :server_scheme
+      attr_reader :served_app, :server
+
+      def boot_app
+        @served_app = Isomorfeus::Puppetmaster::Server.new(app, port: server_port, host: server_host).boot
+      end
+
+      def driver
+        @driver ||= :chromium
+      end
+
+      def driver=(drvr)
+        raise "#{drvr}: no such driver registered! Available drivers: #{drivers.keys.join(', ')}." unless drivers.has_key?(drvr)
+        @driver = drvr
+      end
+
+      def drivers
+        @drivers ||= {}
+      end
+
+      def register_driver(name, &block)
+        drivers[name.to_sym] = block
+      end
+
+      def register_server(name, &block)
+        servers[name.to_sym] = block
+      end
+
+      def save_path
+        @save_path ||= Dir.pwd
+      end
+
+      def server=(name)
+        raise "#{name}: no such server registered! Available drivers: #{servers.keys.join(', ')}." unless servers.has_key?(name)
+        name, options = *name if name.is_a? Array
+        @server = if name.respond_to? :call
+                    name
+                  elsif options
+                    proc { |app, port, host| servers[name.to_sym].call(app, port, host, options) }
+                  else
+                    servers[name.to_sym]
+                  end
+      end
+
+      def server_host
+        @server_host ||= '127.0.0.1'
+      end
+
+      def server_scheme
+        @server_scheme ||= 'http'
+      end
+
+      def servers
+        @servers ||= {}
+      end
+    end
+  end
+end

data/lib/isomorfeus/puppetmaster/console_message.rb

@@ -0,0 +1,19 @@
+module Isomorfeus
+  module Puppetmaster
+    class ConsoleMessage
+      def initialize(message_hash = {})
+        @message_hash = message_hash ? message_hash : {}
+      end
+
+      def method_missing(name, *args)
+        if %i[column_number level location line_number text].include?(name)
+          @message_hash[name.to_s]
+        elsif %i[location url].include?(name)
+          @message_hash['location'] ? @message_hash['location']['url'] : ''
+        else
+          super(name, *args)
+        end
+      end
+    end
+  end
+end

data/lib/isomorfeus/puppetmaster/cookie.rb

@@ -0,0 +1,46 @@
+module Isomorfeus
+  module Puppetmaster
+    class Cookie
+      def initialize(attributes)
+        @attributes = attributes
+      end
+
+      def ==(other)
+        return super unless other.is_a? String
+        value == other
+      end
+
+      def domain
+        @attributes['domain']
+      end
+
+      def expires
+        Time.at @attributes['expires'] unless [nil, 0, -1].include? @attributes['expires']
+      end
+
+      def http_only?
+        !!@attributes['httpOnly']
+      end
+
+      def name
+        @attributes['name']
+      end
+
+      def value
+        @attributes['value']
+      end
+
+      def path
+        @attributes['path']
+      end
+
+      def secure?
+        !!@attributes['secure']
+      end
+
+      def same_site
+        @attributes['sameSite']
+      end
+    end
+  end
+end

data/lib/isomorfeus/puppetmaster/document.rb

@@ -0,0 +1,160 @@
+module Isomorfeus
+  module Puppetmaster
+    class Document
+      extend Isomorfeus::Puppetmaster::SelfForwardable
+
+      document_forward %i[
+        all_text
+        accept_alert
+        accept_confirm
+        accept_leave_page
+        accept_prompt
+        body
+        bring_to_front
+        clear_authentication_credentials
+        clear_cookies
+        clear_extra_headers
+        clear_url_blacklist
+        click
+        close
+        cookies
+        console
+        dismiss_confirm
+        dismiss_leave_page
+        dismiss_prompt
+        dispatch_event
+        double_click
+        evaluate_script
+        execute_script
+        find
+        find_all
+        find_all_xpath
+        find_xpath
+        head
+        html
+        open_new_document
+        remove_cookie
+        render_base64
+        reset_user_agent
+        right_click
+        save_pdf
+        save_screenshot
+        scroll_by
+        scroll_to
+        set_authentication_credentials
+        set_cookie
+        set_extra_headers
+        set_url_blacklist
+        set_user_agent
+        title
+        url
+        user_agent
+        viewport_maximize
+        viewport_resize
+        viewport_size
+        wait_for
+        wait_for_xpath
+      ]
+
+      attr_reader :handle, :response
+
+      def initialize(driver, handle, response)
+        @driver = driver
+        @handle = handle
+        @response = response
+        ObjectSpace.define_finalizer(self, @driver.class.document_handle_disposer(@driver, @handle))
+      end
+
+      def browser
+        @driver.browser
+      end
+
+      def go_back
+        @response = @driver.document_go_back(self)
+        self
+      end
+
+      def go_forward
+        @response = @driver.document_go_forward(self)
+        self
+      end
+
+      def goto(uri)
+        @response = @driver.document_goto(self, uri)
+        self
+      end
+      alias_method :visit, :goto
+
+      def has_content?(content, **options)
+        body.has_content?(content, options)
+      end
+
+      def has_css?(selector, **options)
+        body.has_css?(selector, options)
+      end
+
+      def has_current_path?(other_path)
+        path == other_path
+      end
+
+      def has_text?(text, **options)
+        body.has_text?(text, options)
+      end
+
+      def has_xpath?(query, **options)
+        body.has_xpath?(query, options)
+      end
+
+      def method_missing(name, *args)
+        method_name = name.to_s
+        if method_name.start_with?('find_by_')
+          what = method_name[8..-1]
+          return find("[#{what}=\"#{args.first}\"]") if %w[name type value].include?(what)
+          return find_xpath("//*[text()=\"#{args.first}\"]") if what == 'content'
+        elsif method_name.start_with?('has_')
+          #       :has_checked_field?, #
+          #       :has_content?,
+          #       :has_css?,
+          #       :has_field?,
+          #       :has_link?,
+          #       :has_select?,
+          #       :has_selector?,
+          #       :has_table?,
+          #       :has_text?,
+          #       :has_unchecked_field?,
+          #       :has_xpath?,
+          # :has_button?, # method_missing
+        end
+        super(name, *args)
+      end
+
+      def open_document_by(&block)
+        open_documents = @driver.document_handles
+        block.call
+        new_documents = @driver.document_handles - open_documents
+        raise 'Multiple documents opened' if new_documents.size > 1
+        raise 'No window opened' if new_documents.size < 1
+        Isomorfeus::Puppetmaster::Document.new(@driver, new_documents.first, Isomorfeus::Puppetmaster::Response.new)
+      end
+
+      def path
+        URI.parse(url).path
+      end
+
+      def reload
+        @response = @driver.reload(self)
+      end
+
+      def respond_to?(name, include_private = false)
+        return true if %i[find_by_content find_by_name find_by_type find_by_value].include?(name)
+        super(name, include_private)
+      end
+
+      # assertions
+      #       :assert_current_path,
+      #       :assert_no_current_path
+      #       assert_title
+      #       assert_no_title
+    end
+  end
+end