README.md in uptime_monitor-0.0.2 vs README.md in uptime_monitor-0.0.4
- old
+ new
@@ -1,11 +1,212 @@
uptime_monitor (Hercules)
==========================
[](https://travis-ci.org/obi-a/uptime_monitor)
-Using a real web browser, this plugin checks pages of a website at the specified time intervals, to ensure that the specified elements of the pages and features of the site are still working correctly.
+Uptime_monitor is a [ragios](https://github.com/obi-a/ragios) plugin that uses a real web browser to perform transactions on a website to ensure that features of the site are still working correctly. It can check elements of a webpage to ensure they still exist and it can also perform transactions like a website login to ensure that the process still works correctly.
+##Requirements
+[Ragios](https://github.com/obi-a/ragios)
+
+##Installation:
+ Add the uptime_monitor gem to your ragios Gemfile
+ ```ruby
+ gem "uptime_monitor"
+ ```
+Run bundle install from the ragios root directory
+ ```
+ bundle install
+ ```
+Restart ragios
+
+##usage:
+A quick example, to monitor the title tag of a web page to ensure that it hasn't changed. Using [Ragios ruby client](http://www.whisperservers.com/ragios/ragios-saint-ruby/using-ragios)
+````ruby
+monitor = {monitor: "My Blog title tag",
+ url: "http://obi-akubue.org",
+ every: "5m",
+ contact: "admin@obiora.com",
+ via: "gmail_notifier",
+ plugin: "uptime_monitor",
+ exists?: [
+ [:title, [text: "Obi Akubue"]]
+ ],
+ browser: ["firefox"]
+ }
+ragios.add [monitor]
+```
+The above example will create a ragios monitor that will, every 5 minutes, use firefox to visit the website url http://obi-akubue.org, and verify that the title tag on the page matches the text "Obi Akubue".
+
+###Using the plugin
+To use the uptime monitor plugin add the key/value pair to the monitor
+```ruby
+plugin: "uptime_monitor"
+```
+
+###Browsers
+The browser to use is specified, by adding a browser key/value pair to the monitor
+```ruby
+browser: ["firefox"]
+```
+Supported browsers include Firefox, Chrome, Safari and Phantomjs. Other browsers can be specified as
+```ruby
+browser: ["chrome"]
+browser: ["safari"]
+browser: ["phantomjs"]
+```
+uptime_monitor uses [Watir Webdriver](http://watirwebdriver.com), firefox runs out of the box with no configuration requried. To use Chrome or Safari see the Watir Webdriver documentation on downloading the appropriate driver binary and configuration.
+
+By default, the browsers don't run headless, to run the browser headless, you can specify it in the format below:
+```ruby
+browser: ["firefox", headless: true]
+```
+This will run firefox as a headless browser. You should have [Xvfb](https://en.wikipedia.org/wiki/Xvfb) installed to run a non-headless browsers as headless. Headless browsers like Phantomjs don't require Xvfb.
+
+You can also specify headless as false
+```ruby
+browser: ["firefox", headless: false]
+```
+The above example will run firefox as a non-headless browser.
+
+###Validations
+To verify that a html element exists on the web page, a validation needs to be added to the monitor. Validations are specified with the exists? key/value pair which takes an array of html elements as it's value. It verifies that the html elements in the array exists on the current web page.
+```ruby
+exists?: [
+ [:h1]
+ [:div]
+ ]
+```
+The above example will verify that an h1 and a div exists on the page.
+
+####HTML Elements
+The simplest way to specify a html element is using a symbol.
+```ruby
+exists?: [
+ [:h1]
+ [:div]
+ [:a]
+ [:img]
+ [:span]
+ ]
+```
+HTML elements can also be specified as a hash with their name as key and attributes as value.
+```ruby
+exists?: [
+ [div: {class: "box_content"}]
+ ]
+```
+The above will verify that a div with class "box_content" exists on the page.
+
+Other examples:
+```ruby
+[img: {src: "https://fc03.deviantart.net/fs14/f/2007/047/f/2/Street_Addiction_by_gizmodus.jpg"}]
+
+```
+Specifies an img tag with src="https://fc03.deviantart.net/fs14/f/2007/047/f/2/Street_Addiction_by_gizmodus.jpg".
+
+```ruby
+[div: {id:"test", class: "test-section"}]
+```
+Specifes a div with id="test" and class="test-section".
+
+####Standard attributes
+
+Only standard attributes for an element can be included in the hash, for example a div can only include all or any of the following attributes id, class, lang, dir, title, align, onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, onmouseout, onkeypress, onkeydown, onkeyup.
+
+Custom or data attributes cannot be included, for example to specify a div by data attributes, for example
+```html
+<div data-brand="toyota">
+```
+The following
+```ruby
+[div: {"data-brand" => "toyota"}]
+```
+will give an error because "data-brand" is not a standard attibute for div, to specify elements by data or custom attributes use css selectors, see below.
+
+
+####Using CSS Selectors
+HTML elements can also be specified with css selectors.
+```ruby
+[element: {css: '#rss-link'}]
+```
+This specifies an element with id="rss-link".
+
+To specify an element by data attributes
+```ruby
+[element: {css: '[data-brand="toyota"]'}]
+```
+
+####Helpers for HTML elements
+Helpers are available to make some elements easier to reason about:
+
+#####Links
+An anchor tag could be specified by a link, this makes it more readable and easier to reason about
+Using the anchor tag
+```ruby
+[a: {text: "Click Here"}]
+```
+
+More readble using helper
+```ruby
+[link: {text: "Click Here"}]
+```
+
+```ruby
+[link: {href: "https://www.southmunn.com/aboutus"}]
+```
+
+#####Buttons
+```ruby
+[button: {id: "searchsubmit"}]
+```
+
+#####Text Fields
+```ruby
+[text_field: {id: "search"}]
+```
+
+More readable than the input tag
+```ruby
+[input: {id: "search", type: "text"}]
+```
+
+#####Checkbox
+```ruby
+[checkbox: {value: "Butter"}]
+```
+#####Radio Buttons
+```ruby
+[radio: {name: "group1", value: "Milk"}]
+```
+
+######Drop Down menus
+```html
+<select name="mydropdown">
+<option value="Milk">Fresh Milk</option>
+<option value="Cheese">Old Cheese</option>
+<option value="Bread">Hot Bread</option>
+</select>
+```
+Helper
+```ruby
+[select_list: {name: "mydropdown"}]
+```
+
+Or HTML select tag
+```ruby
+[select: {name: "mydropdown"}]
+```
+
+Options of the drop-down menu can be specified using option
+```ruby
+[option: {value: "Milk"}]
+```
+
+####Text Validations
+
+... more documentation coming soon
+
##Specification:
<pre lang="ruby">
monitor = {monitor: "My Website",
url: "http://mysite.com",
@@ -92,19 +293,7 @@
# [{:img=>
# {:src=>
# "https://fc03.deviantart.net/fs14/f/2007/047/f/2/Street_Addiction_by_gizmodus.jpg"}}]=>
# :does_not_exist_as_expected}
</pre>
-
-###Supported browsers:
-Firefox, Chrome, Safari, Phantomjs
-
-### Browser Format:
-<pre lang="ruby">
-browser: ["firefox", headless: true]
-browser: ["firefox", headless: false]
-browser: ["firefox"]
-browser: ["chrome"]
-</pre>
-Running a browser headless requires xvfb installed.
###More details coming soon