rutl 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ba7a05dd473a09ac45ecafc02d9e11f0a74e26d0e8eb5909e315226066e0ca
-  data.tar.gz: 6a272e4fc1afb2d1111b90604ceb3443cc89fd49c703ff417ab56fd9f609573b
+  metadata.gz: 100c19d4e865873162c8b2d6fef35433cfad509517fe33947f3620b8ec3e1501
+  data.tar.gz: c89348d198df34fb5574dff6ca684df5d7b9509726a6aa6524990ebe86549b8f
 SHA512:
-  metadata.gz: 58227d7b2a1dd426ced4d42a826081ad71b638b6f212a16c5905ef57d0fb28ea4689b0240233dbfbb8d42701460c3bf91354cb088414693047836dcf30fb56ce
-  data.tar.gz: c4acf6148162ef28b3f7704ea6885a6acd81b9bfb0dbff26fb87a6294f943fa5a1e6bcdeb3aaa8668bf597fa0d452620a90587aadf6cd71ea3b4670f5f3281a1
+  metadata.gz: 8bc3dcf1eb98a2f2359fd631b31550f722704b975a13eeab7bd348fe4f691f0433e12ccd446967aaf8bc77138252c005d025f6c59bafcf3a3ae66dbabf12277f
+  data.tar.gz: 95c3525a9dfdf0981584e6d7040c1a781229f824d7581b935c0fa8a56e9704151140a5be9aa101d0c6f720021ce0ce476e340ad158cde17495d8cd42cfd649e8

data/.rubocop.yml

@@ -1,3 +1,6 @@
+# The exclusions here and in source code are intentional decisions to not
+# follow Rubocop's advice. Anything that should be fiex but isn't is in
+# .rubocop_todo.yml
 inherit_from: .rubocop_todo.yml
 
 require: rubocop-rspec
@@ -14,3 +17,28 @@ AllCops:
   DisplayCopNames: true
   DisplayStyleGuide: true
   ExtraDetails: true
+
+# Metrics/BlockLength, Metrics/MethodLength
+# don't apply to the spec files. They naturally have long swaths of code.
+# And the gemspec is special.
+Metrics/BlockLength:
+  Exclude:
+    - 'rutl.gemspec'
+    - 'spec/*_spec.rb'
+Metrics/MethodLength:
+  Exclude:
+    - 'spec/*_spec.rb'
+
+# TODO: Change this setting? Ideally, I should force braces on the *Page files.
+# But should think about this first.
+Style/BracesAroundHashParameters:
+  Exclude:
+    - 'spec/pages/**/*'
+
+# NullDriverPageElement plays dirty tricks with @@variables to simulate
+# longer-lived data sources.
+# And BasePage does @@loaded_pages.
+Style/ClassVars:
+  Exclude:
+    - 'lib/rutl/driver/null_driver_page_element.rb'
+    - 'lib/rutl/base_page.rb'

data/.rubocop_todo.yml

@@ -1,36 +1,11 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2018-06-03 15:06:48 -0700 using RuboCop version 0.56.0.
+# on 2018-06-04 00:16:13 -0700 using RuboCop version 0.56.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 3
-# Configuration parameters: CountComments, ExcludedMethods.
-Metrics/BlockLength:
-  Max: 74
-
-# Offense count: 3
-# Configuration parameters: CountComments.
-Metrics/MethodLength:
-  Max: 13
-
-# Offense count: 4
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: braces, no_braces, context_dependent
-Style/BracesAroundHashParameters:
-  Exclude:
-    - 'spec/pages/internet_login_page.rb'
-    - 'spec/pages/page1.rb'
-
-# Offense count: 3
-Style/ClassVars:
-  Exclude:
-    - 'lib/rutl/base_page.rb'
-    - 'lib/rutl/driver/null_driver_page_element.rb'
-
 # Offense count: 4
 # Configuration parameters: AllowedVariables.
 Style/GlobalVars:
@@ -40,30 +15,9 @@ Style/GlobalVars:
     - 'lib/rutl/interface/elements/element_context.rb'
     - 'lib/rutl/interface/null_interface.rb'
 
-# Offense count: 1
-# Cop supports --auto-correct.
-Style/IfUnlessModifier:
-  Exclude:
-    - 'lib/rutl/interface/elements/element_context.rb'
-
-# Offense count: 4
+# Offense count: 3
 Style/MethodMissingSuper:
   Exclude:
     - 'lib/rutl/base_page.rb'
     - 'lib/rutl/browser.rb'
     - 'lib/rutl/interface/base_interface.rb'
-    - 'spec/spec_helper.rb'
-
-# Offense count: 1
-# Cop supports --auto-correct.
-# Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, IgnoreClassMethods, Whitelist.
-# Whitelist: to_ary, to_a, to_c, to_enum, to_h, to_hash, to_i, to_int, to_io, to_open, to_path, to_proc, to_r, to_regexp, to_str, to_s, to_sym
-Style/TrivialAccessors:
-  Exclude:
-    - 'lib/rutl/base_page.rb'
-
-# Offense count: 15
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
-# URISchemes: http, https
-Metrics/LineLength:
-  Max: 223

data/README.md

@@ -17,13 +17,12 @@ Framework goals:
 * Secondary-ish goal: Make fake browser to test the framework faster.
 * Tertiary-ish: Stop calling browser "fake" because I'm sick of that word. Null!
 
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    ```ruby
-    gem 'rutl'
-    ```
+    $ gem 'rutl'
 
 And then execute:
 
@@ -33,36 +32,159 @@ Or install it yourself as:
 
     $ gem install rutl
 
+
 ## Usage
 
-TODO: Write usage instructions here
+### Page Objects
+Page objects are a common paradigm in browser testing. This framework uses the
+following convention for page classes:
+* must inherit from Rutl::BasePage (require rutl/base_page)
+* by default, the class should follow the naming convention ending with "Page" (optional?)
+* must have @url defined per page
+* must have a layout method such that
+ * field types are defined by methods button, checkbox, link, and text (more tbd?)
+ * field type is followed by name as a symbol (add support for string? tbd)
+ * then a comma
+ * hash of selectors
+   * key is selector type as symbol (currently only :css)
+   * value is string path
+ * optional comma if there are destinations or error conditions
+ * optional array of destination page or error condition classes if clicking the element causes transition
+* loaded? method returning boolean to determine when page is loaded
+  * defaults to just checking url; overide as needed
+* go_to_here (better name?) method to navigate to the page if we can't just go to the url
+* your own methods because it's a plain ol' Ruby class
+
+
+ Example:
+
+```ruby
+    require 'rutl/base_page'
+
+    class MyPage < BasePage
+      @url = 'https://url.string.com/page.html'
+
+      def layout
+        text :username, { css: 'some_css_input#username' }
+        text :password, { css: 'css#to_password_field' }
+        button :log_me_in, { css: 'button#login' }, [SomeOtherPage, LoginFailurePage]
+        link :refresh, { css: 'link_css_to_refresh_page' }, [MyPage]
+      end
+    end
+```
+
+And here's some example RSpec:
+
+```ruby
+    require 'spec_helper'
+
+    RSpec.describe MyTest do
+      let!(:browser) do
+        Browser.new(type: :firefox)
+      end
+
+      it 'logs in' do
+        goto(MyPage)
+        username_text = 'drew'
+        password_text = 's3cr3T!'
+        log_me_in_button.click
+        expect(current_page).to be_page(SomeOtherPage)
+      end
+    end
+```
+
+The framework loads and manages all the pages. You just have to interact with
+what you can see on whatever page you're on. Let's walk through this.
+* TBD: Does RUTL come with browser drivers? Browsers? What needs to be added?
+* We're using let! because:
+  * it forces instantiation of "browser" every time
+  * we include DefaultRspecToBrowser, defaulting missing methods to "browser"
+  * thus the terse lines that follow
+* We didn't pass named param rutl_pages: to Browser so we must have done one of:
+  * setting environment variable RUTL_PAGES
+  * setting RUTL::PAGES
+* Browser's type: parameter currently supports :chrome, :firefox, and :null.
+* The first call to the browser is goto because it wasn't on a page.
+* Auto-created fields are named "#{friendly_name}_#{field_type}".
+* Getting and setting text fields is as easy as calling a String.
+* When we call click, the framework polls for a next state.
+* We verify that the current page is an instance of the intended page.
+  * Also note here that we have a matcher be_page which matches a page class.
+
+### RSpec Goodies
+
+The tests here are in RSpec and use some conventions that may be common if your tests are also RSpec.
+
+#### DefaultRspecToBrowser
+This is a module that allows us to skip writing `browser.` in front of everything.
+1. We assume that `browser` is defined.
+2. On method_missing, we try to send the method to `browser`.
+
+It lets us turn this:
+```
+    browser.field1_text = 'foo'
+    browser.ok_button.click
+    expect(browser.current_page).to eq(NextPage)
+```
+into this:
+```
+    field1_text = 'foo'
+    ok_button.click
+    expect(current_page).to eq(NextPage)
+```
+which means less boilerplate and it's easier to follow.
+
+To use it:
+```
+    require 'rutl/rspec/default_rspec_to_browser'
+```
+
+#### RSpec Matcher
+
+Currently the only has the `be_page` matcher.
+
+It lets us turn this:
+```
+    expect(browser.current_page).to be_instance_of(MyPage)
+```
+into this:
+```
+    expect(browser.current_page).to be_page(MyPage)
+```
+Both are acceptable but the second is more readable.
+
+To use it:
+```
+    require 'rutl/rspec/rutl_matchers'
+```
+
 
 ## Roadmap
 Coming up soon in almost no order:
-* A test framework should have better tests. Goes with next bullet.
-* Flesh out null interface/driver. Make them do what a real browser does.
-* Restructure tests to handle fake browsers and real browsers. Same structure?
-* Make this work with pages files in some other location so we can use it as a gem.
+* A test framework should have better tests.
 * Put more info in this readme.
 * Take screenshots.
 * Diff screenshots. Make this smart so we don't have to be experts.
+* Move bugs and would-be features to Github Issues instead of this readme and scattered through the code.
+* Make the framework make it easier to spot bugs in pages. Focus on exception-handling?
 * The webdriver gem should already include InternetExplorerDriver. Maybe run tests on AppVeyor.
 * Other browser drivers? Look at https://github.com/fnando/browser
 * Get this working with Appium:
   * Make TK app to test on desktops and test it.
-    * Can Ruby TK create accesible apps?
+    * Can Ruby TK create accesible apps? Not in the simple demos.
   * Make Android example app and get this to work.
     * Corboba?
   * Same with iPhone.
     * Same Cordoba test app?
 * Others?
-* Spidering page object maker.
+* Spidering page object maker. Or selector checker/fixer?
 * Possibly pair the null browser with auto-generated pages for ______?
 * Call rutl.rb properly.
 * Optional install of test resources based on machine type.
 * Instructions about machine installs to help people using gem.
 * Pair with some kind of VM, Docker container, AMI, or something.
 
+
 ## Development
 
 Set everything up:
@@ -75,10 +197,13 @@ Set everything up:
 Great! You've checked out the code, installed everything and run the tests.
 
 Rubocop. I still have to tweak what I want it to complain about.
-    `bundle exec rubocop`
+```ruby
+    bundle exec rubocop
+```
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/drewcoo/rutl.

data/lib/rspec/default_rspec_to_browser.rb

@@ -0,0 +1,22 @@
+#
+# Currently not in use.
+# Should go in its own file, too.
+#
+module DefaultRspecToBrowser
+  # rubocop:disable Style/MethodMissingSuper
+  def method_missing(method, *args, &block)
+    if args.empty?
+      browser.send(method)
+    else
+      browser.send(method, *args, &block)
+    end
+  rescue ArgumentError
+    browser.send(method)
+  end
+  # rubocop:enable Style/MethodMissingSuper
+
+  def respond_to_missing?(method, _include_private = false)
+    return false if method =~ /browser/
+    browser.respond_to?(method)
+  end
+end

data/lib/rspec/rutl_matchers.rb

@@ -0,0 +1,8 @@
+#
+# Additional RSpec matchers specific to this framework go here.
+#
+RSpec::Matchers.define :be_page do |expected|
+  match do |actual|
+    actual.is_a?(expected) && expected.ancestors.include?(BasePage)
+  end
+end

data/lib/rutl/base_page.rb

@@ -9,6 +9,7 @@ class BasePage
   # BUGBUG: Kludgy. What do I really want to do here?
   # Make it easy to define a page's default url and
   # also matchers for page urls for pages with variable urls?
+  # rubocop:disable Style/TrivialAccessors
   def self.url
     @url
   end
@@ -16,6 +17,7 @@ class BasePage
   def url
     self.class.url
   end
+  # rubocop:enable Style/TrivialAccessors
 
   @@loaded_pages = []
 
@@ -29,6 +31,12 @@ class BasePage
     @@loaded_pages << self.class
   end
 
+  def go_to_here
+    # Ovveride this in base page to have something more
+    # complicated than this.
+    @interface.driver.navigate.to(url)
+  end
+
   # Written by Browser and only used internally.
   attr_writer :interface
 
@@ -40,6 +48,9 @@ class BasePage
   # to the current class where that method creates an instance
   # of klass.
   # context is an ElementContext
+  #
+  # As it is, this seems silly to break into pieces for Rubocop.
+  # rubocop:disable Metrics/MethodLength
   def add_method(context:, klass:, name:, setter: false)
     name = "#{name}_#{klass.downcase}"
     constant = Module.const_get(klass.capitalize)
@@ -55,11 +66,15 @@ class BasePage
       end
     end
   end
+  # rubocop:enable Metrics/MethodLength
 
   # This creates a new element instance whenever it's called.
   # Because of that we can't keep state in any element objects.
   # That seems like a good thing, actually.
   # Called by layout method on pages.
+  #
+  # Hard to make shorter.
+  # rubocop:disable Metrics/MethodLength
   def method_missing(element, *args, &_block)
     name, selectors, rest = args
     context = ElementContext.new(destinations: rest,
@@ -76,6 +91,7 @@ class BasePage
       raise "#{element} NOT FOUND WITH ARGS #{args}!!!"
     end
   end
+  # rubocop:enable Metrics/MethodLength
 
   def respond_to_missing?(*args)
     # Is this right at all???

data/lib/rutl/browser.rb

@@ -11,12 +11,15 @@ class Browser
 
   attr_reader :interface
 
-  def initialize(interface_type:, page_object_dir: 'spec/pages')
+  def initialize(type:, rutl_pages: RUTL::PAGES || ENV['RUTL_PAGES'])
+    if rutl_pages.nil? || rutl_pages.empty?
+      raise "Set RUTL::PAGES or ENV['RUTL_PAGES'] or pass dir as rutl_pages:"
+    end
     # This is kind of evil. Figure out how to ditch the $ variable.
     $browser = self
     @interface = nil
-    @interface = load_interface(interface_type)
-    @interface.pages = load_pages(dir: page_object_dir)
+    @interface = load_interface(type)
+    @interface.pages = load_pages(dir: rutl_pages)
   end
 
   def load_interface(type)

data/lib/rutl/driver/null_driver_page_element.rb

@@ -30,7 +30,7 @@ class NullDriverPageElement
   def attribute(attr)
     case attr.to_sym
     when :value
-      @@variables[@location]
+      @@variables[@location] || ''
     else
       raise ArgumentError, "Attribute unknown: #{attr}"
     end

data/lib/rutl/interface/base_interface.rb

@@ -15,7 +15,8 @@ class BaseInterface
   end
 
   def goto(page)
-    @driver.navigate.to find_page(page).url
+    raise 'expect Page class' unless page.ancestors.include?(BasePage)
+    find_page(page).go_to_here
   end
 
   def current_page

data/lib/rutl/interface/chrome_interface.rb

@@ -5,6 +5,7 @@ require 'rutl/interface/base_interface'
 # Small interface for Chrome browser.
 #
 class ChromeInterface < BaseInterface
+  # rubocop:disable Metrics/MethodLength
   def initialize
     @logged_in = true
     options = Selenium::WebDriver::Chrome::Options.new
@@ -20,6 +21,7 @@ class ChromeInterface < BaseInterface
     @driver = Selenium::WebDriver.for :chrome, options: options
     super
   end
+  # rubocop:enable Metrics/MethodLength
 
   def current_page
     url = @driver.current_url

data/lib/rutl/version.rb

@@ -1,3 +1,3 @@
 module RUTL
-  VERSION = '0.1.4'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/rutl.rb

@@ -6,5 +6,8 @@ require 'rutl/version'
 # desktop UI testing, turning the UI into an API via its DSL.
 #
 module RUTL
-  # Your code goes here...
+  # Should define RUTL::PAGES directory for your code
+  # or set ENV['RUTL_PAGES']
+  # or Browser intialize will raise.
+  PAGES = nil
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rutl
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Drew Cooper
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-04 00:00:00.000000000 Z
+date: 2018-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -185,6 +185,8 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- lib/rspec/default_rspec_to_browser.rb
+- lib/rspec/rutl_matchers.rb
 - lib/rutl.rb
 - lib/rutl/base_page.rb
 - lib/rutl/browser.rb