README.md in rutl-0.6.0 vs README.md in rutl-0.8.0
- old
+ new
@@ -1,9 +1,10 @@
# RUTL
[](https://travis-ci.org/drewcoo/rutl)
[](https://circleci.com/gh/drewcoo/rutl)
+[](https://ci.appveyor.com/project/drewcoo/rutl)
[](https://coveralls.io/github/drewcoo/rutl?branch=master)
[](https://badge.fury.io/rb/rutl)
[](https://www.codacy.com/app/drewcoo/rutl?utm_source=github.com&utm_medium=referral&utm_content=drewcoo/rutl&utm_campaign=Badge_Grade)
This is the Ruby Ui Test Library, or RUTL. Not to be confused with [The Rutles](https://www.rutles.org/).
@@ -20,11 +21,11 @@
## Installation
Add this line to your application's Gemfile:
- $ gem 'rutl'
+ $ gem rutl
And then execute:
$ bundle
@@ -33,32 +34,34 @@
$ gem install rutl
## Usage
+
### 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 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 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)
+ * 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
+* `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:
+Example:
```ruby
require 'rutl/base_page'
class MyPage < BasePage
@@ -95,99 +98,121 @@
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"
+ * 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.
+* 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.
+ * 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'
+```ruby
+ message = 'foo'
+ browser.field1_text = message
browser.ok_button.click
- expect(browser.current_page).to eq(NextPage)
+ expect(browser.current_page).to be_page(NextPage)
```
into this:
-```
- field1_text = 'foo'
+```ruby
+ message = 'foo'
+ field1_text = message
ok_button.click
- expect(current_page).to eq(NextPage)
+ expect(current_page).to be_page(NextPage)
```
-which means less boilerplate and it's easier to follow.
+which means less boilerplate.
+Because we insist on adding UI element type as part of the naming convention there's no confusion about which things are UI elements and which aren't. In this case, we don't mistake our variable "message" for a UI element.
To use it:
-```
+```ruby
require 'rutl/rspec/default_rspec_to_browser'
```
+
#### RSpec Matcher
Currently the only has the `be_page` matcher.
It lets us turn this:
-```
+```ruby
expect(browser.current_page).to be_instance_of(MyPage)
```
into this:
-```
+```ruby
expect(browser.current_page).to be_page(MyPage)
```
Both are acceptable but the second is more readable.
To use it:
-```
+```ruby
require 'rutl/rspec/rutl_matchers'
```
+
### Auto-screenshotting
-If you have RUTL::SCREENSHOTS or ENV['SCREENSHOTS'] set to a directory, RUTL
+If you have `RUTL::SCREENSHOTS` or `ENV['SCREENSHOTS']` set to a directory, RUTL
will automatically take screenshots on page transitions.
If you're using RSpec, they'll be automatically named something based on the
RSpec description with an auto-incrementing number.
If you're not using RSpec, that's not terribly useful but you can always have
your tests screenshot anyway, just less magic.
+
## Roadmap
+
Coming up soon in almost no order:
* Handle other errors. Auto-screenshot on errors. Navigation errors. Unexpected exceptions?
* A test framework should have better tests.
* Diff screenshots. Make this smart so we don't have to be experts.
* Put more info in this readme.
* 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.
+* The webdriver gem should already include [InternetExplorerDriver](https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver). Maybe run tests on [AppVeyor](https://www.appveyor.com/).
+* [Other browser drivers](https://github.com/fnando/browser)?
+* Get this working with [Appium](https://appium.io/):
+ * Make [TK app](https://www.tutorialspoint.com/ruby/ruby_tk_guide.htm) to test on desktops and test it.
* Can Ruby TK create accesible apps? Not in the simple demos.
* Make Android example app and get this to work.
- * Corboba?
+ * [Cordova](https://cordova.apache.org/) or [React Native](https://facebook.github.io/react-native/) or maybe even [Flutter](https://flutter.io/)for app?
+ * Choose (default?) emulator. Many choices.
* Same with iPhone.
- * Same Cordoba test app?
-* Documentation. RDoc?
+ * Where to build/test? [CircleCI](https://circleci.com/build-environments/#apple-platforms)?
+ * Same test app as Android.
+ * Are there decent alternatives yet to the simulator?
+* Improve documentation.
+* Add these things and treat as plugins?
+ * Security testing. See [OWASP](https://github.com/OWASP) stuff.
+ * Also OWASP mobile security testing guide.
+ * Avoid deeper pen testing. Leave it to other toolkits.
+ * Other toolkits? Accessibility?
+ * Support web proxy and integrate out of the box. Browsermob?
+ * Get HARs here for perf stuff.
+ * Also look at browser events and tie to HARs? (Always wanted to do that.)
* Auto-screenshot support frameworks other than RSpec.
+ * Or just default them to screenshots at known view changes (links/buttons/other?) or errors.
* Others?
* Spidering page object maker. Or selector checker/fixer?
* Possibly pair the null browser with auto-generated pages for ______?
* Optional install of test resources based on machine type.
* Instructions about machine installs to help people using gem.
@@ -208,10 +233,22 @@
Rubocop. I still have to tweak what I want it to complain about.
```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).
+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` like so
+```ruby
+ bundle exec gem bump -v [major|minor|patch|pre|release]
+```
+
+and then run
+```ruby
+ 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.