uptime_monitor 0.0.4 → 0.0.5

data/README.md

@@ -1,6 +1,7 @@
 uptime_monitor (Hercules)
 ==========================
 [![Build Status](https://travis-ci.org/obi-a/uptime_monitor.png?branch=master)](https://travis-ci.org/obi-a/uptime_monitor)
+[![Gem Version](https://badge.fury.io/rb/uptime_monitor.svg)](http://badge.fury.io/rb/uptime_monitor)
 
 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.
 
@@ -34,7 +35,7 @@ monitor = {monitor: "My Blog title tag",
           }
 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".
+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". When the title tag doesn't match the text, a failure notification will be sent out to the contact.
 
 ###Using the plugin
 To use the uptime monitor plugin add the key/value pair to the monitor
@@ -43,7 +44,7 @@ plugin: "uptime_monitor"
 ```
 
 ###Browsers
-The browser to use is specified, by adding a browser key/value pair to the monitor
+A browser is specified, by adding a browser key/value pair to the monitor
 ```ruby
 browser: ["firefox"]
 ```
@@ -53,7 +54,7 @@ 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.
+uptime_monitor uses [Watir Webdriver](http://watirwebdriver.com), firefox runs out of the box with no configuration required. 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
@@ -75,7 +76,7 @@ exists?: [
            [:div]
          ]
 ```
-The above example will verify that an h1 and a div exists on the page.
+The above example will verify that a h1 and a div exists on the page.
 
 ####HTML Elements
 The simplest way to specify a html element is using a symbol.
@@ -112,7 +113,7 @@ Specifes a div with id="test" and class="test-section".
 
 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
+Custom or data attributes cannot be included, for example
 ```html
 <div data-brand="toyota">
 ```
@@ -139,13 +140,14 @@ To specify an element by data attributes
 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
+An anchor tag could be specified with a link helper, this makes it more readable and easier to reason about.
+
 Using the anchor tag
 ```ruby
 [a: {text: "Click Here"}]
 ```
 
-More readble using helper
+More readble using a helper
 ```ruby
 [link: {text: "Click Here"}]
 ```
@@ -166,10 +168,10 @@ More readble using helper
 
 More readable than the input tag
 ```ruby
-[input: {id: "search", type: "text"}]
+[input: {id: "search"}]
 ```
 
-#####Checkbox
+#####Checkboxes
 ```ruby
 [checkbox: {value: "Butter"}]
 ```
@@ -178,7 +180,7 @@ More readable than the input tag
 [radio: {name: "group1", value: "Milk"}]
 ```
 
-######Drop Down menus
+#####Drop Down menus
 ```html
 <select name="mydropdown">
 <option value="Milk">Fresh Milk</option>
@@ -202,38 +204,119 @@ Options of the drop-down menu can be specified using option
 ```
 
 ####Text Validations
+A text validation is used to verify that the text content of a html element hasn't changed. For example,
+```ruby
+exists?: [
+           [:title, [text: "Welcome to my site"]]
+         ]
+```
+The above example first verifies that a title tag exists on the page, then it verifies that title tag text is equal to "Welcome to my site".
+The following is a text validation:
+```ruby
+[text: "Welcome to my site"]
+```
+Text validations can also verify that the html element's text includes the provided string, in the format below:
+```ruby
+exists?: [
+           [:title, [includes_text: "Welcome"]]
+         ]
+```
+The above example verifies that the title tag's text includes the string "Welcome".
+Another example, to verify that a div with class="box_content" includes the string "SouthMunn is a Website"
+```ruby
+exists?: [
+           [{div: {class: "box_content"}}, [includes_text: "SouthMunn is a Website"]]
+         ]
+```
+Text validations can be used on html elements that can contain text like title, div, span, h1, h2 etc.
 
-... more documentation coming soon
+####Actions
+Validations can also include actions. The actions are performed on the html element after it is validated. Example to set a text field's value
+```ruby
+exists?: [
+            [{text_field: {id: "username"}}, [set: "admin"]]
+         ]
+```
+The above example will set the text field's value to the string "admin".
+The following is an action
+```ruby
+[set: "admin"]
+```
+#####Actions on html elements
+Common actions performed on elements are set, select and click.
 
-##Specification:
+Set value for a textfield or textarea.
+```ruby
+ [{text_field: {name: "q"}}, [set: "ruby"]]
+ [{text_area: {name: "longtext"}}, [set: "In a world..."]]
+```
+Select an option from a drop down menu
+```html
+<select name="mydropdown">
+<option value="Milk">Fresh Milk</option>
+<option value="Cheese">Old Cheese</option>
+<option value="Bread">Hot Bread</option>
+</select>
+```
+```ruby
+[{select_list: {name: "mydropdown"}},[select: "Old Cheese"]]
+```
+Click a radio button, checkbox, link or button
+```ruby
+[{radio: {name: "group1", value: "Milk"}}, [:click]]
+[{checkbox:{name: "checkbox"}}, [:click]]
+[{link: {text: "Click Here"}}, [:click]]
+[{button: {id: "submit"}}, [:click]]
+```
+####Waiting
+For webpages that use a lot of AJAX, it's possible to wait until an element exists, by using the wait_until_exists? key. This key takes an element as value. It is a special type of validation, it will wait for 30 seconds for the provided element to exist, if the element doesn't exist in 30 seconds the validation fails.
+```ruby
+[wait_until_exists?: [div: {id:"open-section"}]]
+```
+The above example will wait 30 seconds until the div exists, if it doesn't exist after 30 seconds the validation will fail.
 
-<pre lang="ruby">
-monitor = {monitor: "My Website",
-            url: "http://mysite.com",
-            every: "5m",
-            contact: "admin@mail.com",
-            via: "email_notifier",
+####Multiple validations and actions
+```ruby
+exists?: [
+            [{text_field: {id: "username"}}, [set: "admin"]],
+            [{text_field: {id: "password"}}, [set: "pass"]],
+            [:button, [:click]],
+            [:title, [includes_text: "Dashboard"]]
+         ]
+```
+With multiple validations like the example above, the monitor will run the validations, line by line, from top to bottom. When it meets an action it will apply it on the element in the validation. The monitor fails it's test if any of the validation fails. So for the monitor to pass, all validations must pass.
+
+When actions like clicking a link, changes the current page, the following validations will be performed on the new page.
+
+A combination of multiple validations and actions form the basis for performing transactions.
+
+
+####Performing Transactions
+Transactions are achieved by a combination of multiple validations and actions.
+
+To monitor the keyword search feature on my blog:
+```ruby
+monitor = {monitor: "My Blog: keyword search",
+            url: "http://obi-akubue.org",
+            every: "1h",
+            contact: "admin@obiora.com",
+            via: "gmail_notifier",
             plugin: "uptime_monitor",
             exists?: [
-                        [:title, [text: "Welcome to my site"]],
-                        [{div: {id:"test", class: "test-section"}}, [text: "this is a test"]],
-                        [a: {href: "/aboutus" }],
-                        [:h1],
-                        [:h2,[text: "Login"]],
-                        [form: {action: "/signup", method: "get"}],
-                        [{element: {css: "#submit-button"}}, [:click]],
-                        [{text_field: {id: "username"}}, [set: "admin"]],
-                        [{text_field: {id: "password"}}, [set: "pass"]],
-                        [link: {text: "Contact Us"}],
-                        [wait_until_exists?: [div: {id:"open-section"}]]
+                       [:title,[text: "Obi Akubue"]],
+                       [{text_field: {id: "s"}}, [set: "ruby"]],
+                       [{button:{id: "searchsubmit"}}, [:click]],
+                       [:title, [includes_text: "ruby"], [includes_text: "Search Results"]],
+                       [{h2:{class: "pagetitle"}},[includes_text: "Search results for"]]
                      ],
-            browser: ["firefox", headless: true]
+            browser: ["firefox"]
           }
 ragios.add [monitor]
-</pre>
+```
+In the above example the monitor will visit "http://obi-akubue.org" every hour, and perform a search for keyword 'ruby', then confirm that the search works by checking that the title tag and h2 tag of the search results page contains the expected text.
 
-###Monitor login process of a real site
-<pre lang="ruby">
+Another example, to monitor the login process of the website southmunn.com
+```ruby
 login_process = [
                     [:title, [text: "Website Uptime Monitoring | SouthMunn.com"]],
                     [{link: {text:"Login"}}, [:click]],
@@ -244,20 +327,23 @@ login_process = [
                     [:title, [text: "Dashboard - Website Uptime Monitoring | SouthMunn.com"]]
                 ]
 
-monitor = {monitor: "My Website",
+monitor = {monitor: "My Website login processs",
             url: "https:/southmunn.com",
-            every: "5m",
-            contact: "admin@mail.com",
+            every: "1h",
+            contact: "admin@obiora.com",
             via: "email_notifier",
             plugin: "uptime_monitor",
             exists?: login_process,
             browser: ["firefox", headless: true]
           }
 ragios.add [monitor]
-</pre>
+```
+
+####Testing the validations outside Ragios
+Sometimes it's useful to run validations outside Ragios to verify that the validations are syntactically correct and don't raise any exceptions. This is best done by running the uptime_monitor plugin as a Plain Old Ruby Object.
+```ruby
+require 'uptime_monitor'
 
-###Real site test:
-<pre lang="ruby">
 monitor = {monitor: "About Us page",
             url: "https://www.southmunn.com/aboutus",
             browser: ["firefox", headless: false],
@@ -268,7 +354,7 @@ monitor = {monitor: "About Us page",
           }
 
 u = Ragios::Plugin::UptimeMonitor.new
-u.init monitor
+u.init(monitor)
 u.test_command?
 #=> true
 u.test_result
@@ -294,6 +380,58 @@ u.test_result
 #    {:src=>
 #      "https://fc03.deviantart.net/fs14/f/2007/047/f/2/Street_Addiction_by_gizmodus.jpg"}}]=>
 #  :does_not_exist_as_expected}
+```
+In the above example the test_command?() method runs all validations and returns true when all validations passes, returns false when any of the validation fails. test_result is a hash that contains the result of the tests ran by test_command?().
+
+####Testing individual validations
+It can be very useful to test validations individually before adding them to Ragios. This can be done by running plugin's browser object directly.
+```ruby
+require 'uptime_monitor'
+
+url= "http://obi-akubue.org"
+headless = false
+browser_name = "firefox"
+browser = Hercules::UptimeMonitor::Browser.new(url, browser_name, headless)
+
+browser.exists? [:title, [includes_text: "ruby"]]
+
+browser.exists? [{h2:{class: "pagetitle"}}]
+
+browser.exists? [{checkbox:{name: "checkbox"}}, [:click]]
+
+browser.close
+```
+The above example creates a browser object and visits the url. The exists? method takes a single validation as arguement and performs the validation on the url, it returns true if the validation passes and returns false if the validation fails. In the first validation it checks if the title tag on the url includes the text 'ruby'.
+
+
+##Specification:
+<pre lang="ruby">
+monitor = {monitor: "My Website",
+            url: "http://mysite.com",
+            every: "5m",
+            contact: "admin@obiora.com",
+            via: "mail_notifier",
+            plugin: "uptime_monitor",
+            exists?: [
+                        [:title, [text: "Welcome to my site"]],
+                        [{div: {id:"test", class: "test-section"}}, [text: "this is a test"]],
+                        [a: {href: "/aboutus" }],
+                        [:h1],
+                        [:h2,[text: "Login"]],
+                        [form: {action: "/signup", method: "get"}],
+                        [{element: {css: "#submit-button"}}, [:click]],
+                        [{text_field: {id: "username"}}, [set: "admin"]],
+                        [{text_field: {id: "password"}}, [set: "pass"]],
+                        [link: {text: "Contact Us"}],
+                        [wait_until_exists?: [div: {id:"open-section"}]]
+                     ],
+            browser: ["firefox", headless: true]
+          }
+ragios.add [monitor]
 </pre>
 
-###More details coming soon
+
+##License:
+MIT License.
+
+Copyright (c) 2014 Obi Akubue, obi-akubue.org

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/uptime_monitor.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "uptime_monitor"
-  s.version = "0.0.4"
+  s.version = "0.0.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["obi-a"]
-  s.date = "2014-04-06"
+  s.date = "2014-04-12"
   s.description = "A Ragios plugin that uses a real web browser to monitor transactions on a website for availability"
   s.email = "obioraakubue@yahoo.com"
   s.extra_rdoc_files = [
@@ -38,7 +38,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/obi-a/uptime_monitor"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
+  s.rubygems_version = "1.8.28"
   s.summary = "Real browser website uptime monitoring plugin for Ragios"
 
   if s.respond_to? :specification_version then

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uptime_monitor
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-06 00:00:00.000000000 Z
+date: 2014-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: headless
@@ -196,7 +196,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 660930515595020497
+      hash: -2995370031578709279
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -205,7 +205,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.28
 signing_key: 
 specification_version: 3
 summary: Real browser website uptime monitoring plugin for Ragios