citronella 0.0.4 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9020c7d6488bbbd5e67e35a1c939a2af5296736bbe99c45a6d8194ff347676aa
-  data.tar.gz: 1fb3f63ea173a9c6ca720bfa945037bb8f6a595922929ee91972751e82d0239d
+  metadata.gz: 572a05603b535810328bd3d82612b5133810773ad46ca094daa2e92618d3087f
+  data.tar.gz: 913908e8bf7d28b6b9beb7a3ad86d4e9a9b6278b7250d11e0c43d711a60b6e25
 SHA512:
-  metadata.gz: 9c52cdaeca3173c7d224f2d5f390b83d8b5e9835937bf1af3fa2e8a9ad05c03a1f16f02357b7a85f8052f36c598763a8b9a1551a8606964b78f53dee4bbd1194
-  data.tar.gz: cfd8f9876408c022b04eab006ac24793473ee5a946bba6963446e2d7a66736e917def508b0528718ae7f6003b40da63dd43be16653d60128798a81aea3068165
+  metadata.gz: 51b581dcf93989fcf87d08c26ef7c9ba79182e390234d9d051b9e71005a64964feb34da34f862d51f7ec400dc47c184c46e274dbbd1eb8c8862f512ff746cfea
+  data.tar.gz: 562b3a4941affe127b9f7f0be4ec893d64b6bbe1c9a809cc8edf52c8ae4fc73d87a304915a00fc2def16c44e2578266b3f0dc351fc3dae2f370289e90845fd6a

data/Gemfile

@@ -4,4 +4,5 @@ source "https://rubygems.org"
 
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
-gem "selenium-webdriver"
+gem 'selenium-webdriver'
+gem 'test-unit'

data/README.md

@@ -1,6 +1,6 @@
 # Citronella
 
-[![Gem Version](https://badge.fury.io/rb/citronella.png)](http://badge.fury.io/rb/citronella)
+[![Gem Version](https://badge.fury.io/rb/citronella.svg)](http://badge.fury.io/rb/citronella)
 
 webdriver extension with a page object wrapper.
 
@@ -17,6 +17,8 @@ class NavigationTest < Test::Unit::TestCase
     options = Selenium::WebDriver::Chrome::Options.new
     driver = Selenium::WebDriver.for :chrome, options: options
     @web = Citronella::Web::WebPage.new(driver)
+    @web.page = ContentsPage
+    @web.driver.navigate.to('https://rubygems.org')
   end
 
   def teardown
@@ -24,27 +26,28 @@ class NavigationTest < Test::Unit::TestCase
   end
 
   def test_navigation
-    @web.page_object(ContentsPage.new.home_page, url=true)
-    @web.page.releases_button.click
+    @web.page.home_page.releases_button.click
     assert_includes(@web.driver.title, 'Releases')
 
-    @web.page.gems_button.click
+    @web.page.release_page.gems_button.click
     assert_includes(@web.driver.title, 'Gem')
     
-    @web.page.sign_in_button.click
+    @web.page.gems_page.sign_in_button.click
     assert_includes(@web.driver.title, 'Sign in')
     
-    @web.page.sign_up_button.click
+    @web.page.sign_in_page.sign_up_button.click
     assert_includes(@web.driver.title, 'Sign up')
     
-    @web.page.guides_button.click
+    @web.page.sign_up_page.guides_button.click
     assert_includes(@web.driver.title, 'Guides')
     
-    @web.page.blog_button.click
+    @web.page.guides_page.blog_button.click
     assert_includes(@web.driver.title, 'Blog')
   end
 end
 ```
+![alt terminal](https://github.com/heyclore/citronella/blob/main/ruby/screenshot/terminal.png?raw=true)
+
 Even though this module is mainly designed for the page object model, it can also be used without it for quick prototyping or mockups, etc.
 ```ruby
 require 'test/unit'
@@ -65,12 +68,14 @@ class PackageSearchTest < Test::Unit::TestCase
 
   def test_search_package
     @web.driver.navigate.to "https://rubygems.org/"
-    @web.locate(id: 'home_query').get_element.send_keys('citronella')
-    @web.locate(class: 'home__search__icon').get_element.click
+    @web.locate(id: 'home_query').send_keys('citronella')
+    @web.locate(class: 'home__search__icon').click
     assert(@web.locate(class: 'gems__gem__name').get_element.text, 'citronella')
   end
 end
 ```
+![alt terminal](https://github.com/heyclore/citronella/blob/main/ruby/screenshot/terminal2.png?raw=true)
+
 ___
 ## Install Package
 
@@ -81,7 +86,7 @@ gem install citronella
 ___
 ## Documentation
 
-There are only three modules imported in this package:
+There are only two modules imported in this package:
 
 * The first module is for the tests.
 
@@ -103,25 +108,84 @@ class NavigationTest < Test::Unit::TestCase
 end
 ```
 
-* The second and third modules are for the page object model.
+* The last module is for the page object model.
 
-```python
+```ruby
 require 'citronella'
-require_relative '../contents_page'
+require_relative '../components/header_menu'
 
-class HomePage < ContentsPage.new.header_menu
-  @url = "https://rubygems.org/"
+class HomePage
+  include HeaderMenu
 
   def search_button
-    ui(class: 'home__search__icon', page: ContentsPage.new.search_page)
+    ui(class: 'home__search__icon')
   end
 
   def code_link_button
-    ui(css: 'div.nav--v > a:nth-child(3)', page: Citronella::Dummy::PlaceholderPage)
+    ui(css: 'div.nav--v > a:nth-child(3)')
   end
 end
 ```
 
+___
+## Page Object Design / Strategy
+see full [Page object](https://github.com/heyclore/citronella/tree/main/ruby/examples/page_object/pages) example
+```ruby
+require "selenium-webdriver"
+require 'citronella'
+
+module HeaderMenu
+  def home_logo
+    ui(class: 'header__logo')
+  end
+
+  def search_input
+    ui(id: 'home_query')
+  end
+  
+  def gems_button
+    ui(css: 'a[href="/gems"]')
+  end
+end
+
+class HomePage
+  include HeaderMenu
+
+  def search_button
+    ui(class: 'home__search__icon')
+  end
+
+  def code_link_button
+    ui(css: 'div.nav--v > a:nth-child(3)')
+  end
+end
+
+class SearchPage
+  include HeaderMenu
+
+  def search_lists
+    ui(class: 'gems__gem__name')
+  end
+end
+
+class ContentsPage
+  def home_page
+    HomePage
+  end
+
+  def search_page
+    SearchPage
+  end
+end
+
+options = Selenium::WebDriver::Chrome::Options.new
+driver = Selenium::WebDriver.for :chrome, options: options
+web = Citronella::Web::WebPage.new(driver)
+web.page = ContentsPage
+web.driver.navigate.to('https://rubygems.org')
+web.page.home_page.search_input.send_keys('citronella', return_key=true)
+puts web.page.search_page.search_list.get_element.text
+```
 ___
 ## Usage
 
@@ -137,27 +201,25 @@ ___
 ###### Method Lists:
 | Method Name        | Args*       | Kwargs**         | Note |
 | ------------------ |:-----------:|:----------------:|:----:|
-| driver             | None        | None             | return selenium `webdriver` object |
-| locate             | None        | how: what        | similar as`driver.get_element` args |
-| page_object        | Page Object | url `bool`       | Page Object must contain `@url` variable with if using Kwargs** | 
-| page               | None        | None             |      |
-| back               | None        | None             |      |
-| webdriver_wait     | number(sec) | None             |      |
-| ready_state        | number(sec) | None             | execute javascript `document.readyState` manually |
+| driver             | -           | -                | return selenium `webdriver` object |
+| locate             | -           | how: what        | similar as`driver.get_element` as input & return [citronella.WebUi](https://github.com/heyclore/citronella/tree/main/ruby#citronellaui--citronellawebui)|
+| page               | Page Object | -                | setter |
+| page               | -           | -                | getter |
+| webdriver_wait     | number(sec) | -                |      |
+| ready_state        | number(sec) | -                | execute javascript `document.readyState` manually |
 
 ### citronella.ui / citronella.WebUi
 
 ###### Kwargs:
 - how: what
-- page_object (optional)
 
 ###### Method Lists:
 | Method Name   | Args*  | Kwargs**           | Note |
 | ------------- |:------:|:------------------:|:----:|
-| send_keys     | text   | clear `bool`, return_key `bool`, switch_page `bool` |    |
-| click         | None   | switch_page `bool` |      |
-| get_element   | None   | None               |      |
-| get_elements  | None   | None               |      |
+| send_keys     | text   | clear `bool`, return_key `bool` |      |
+| click         | -      | -                  |      |
+| get_element   | -      | -                  |      |
+| get_elements  | -      | -                  |      |
 
 
 ## Testing powered by

data/citronella.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'citronella'
-  s.version = '0.0.4'
+  s.version = '1.0.1'
 
   s.authors = ['heyclore']
   s.email = 'cloore@gmail.com'

data/lib/citronella.rb

@@ -23,4 +23,3 @@
 
 require_relative 'web_page'
 require_relative 'ui'
-require_relative 'placeholder_page'

data/lib/logger.rb

@@ -25,8 +25,14 @@ require 'logger'
 
 module Citronella
   module Log
+    # A wrapper for UI methods.
+    #
+    # @param [Boolean] logger Flag indicating whether to log actions.
+    # @param [String] class_name The name of the class.
+    # @param [String] function_name The name of the function.
+    # @param [String] name The name of the action.
+    #
     def self.logger(logger, class_name, function_name, name)
-      """This is a logger method."""
       if logger
         Logger.new(STDOUT, level: Logger::INFO).info("#{class_name} => #{function_name} => #{name}")
       end

data/lib/page_decorator.rb

@@ -26,20 +26,32 @@ require_relative 'web_ui.rb'
 module Citronella
   module Wrapper
     class PageDecorator
-      """This is a page decorator class."""
-      def initialize(driver, webdriver_wait, pages, logger)
+      # A wrapper for page object class.
+      #
+      # @param [Webdriver] driver The web driver object.
+      # @param [Integer] webdriver_wait The timeout for webdriver wait.
+      # @param [PageObject] page The page object class.
+      # @param [Boolean] logger A flag indicating whether to log actions.
+      #
+      def initialize(driver, webdriver_wait, page, logger)
         @driver = driver
         @webdriver_wait = webdriver_wait
-        @pages = pages
+        @page = page
         @logger = logger
       end
 
+      # Looks up the attribute/method name inside the page object.
+      #
+      # @return [PageDecorator, WebUi]
+      #
       def method_missing(attr)
-        """look up the attr / method name inside page object."""
-        original_method = @pages.current_page.new.method(attr)
+        original_method = @page.new.method(attr)
         args = original_method.call
-        Citronella::Ui::WebUi.new(@driver, @webdriver_wait, @pages, @logger,
-                                  args.last, args.first, attr, @pages.current_page.name)
+        if args.instance_of?(Class)
+          return PageDecorator.new(@driver, @webdriver_wait, args, @logger)
+        end
+        Citronella::Ui::WebUi.new(@driver, @webdriver_wait, @logger,
+                                  args, attr, @page.name)
       end
     end
   end

data/lib/ui.rb

@@ -21,22 +21,13 @@
 #SOFTWARE.
 
 
+# A wrapper for driver.find_element or driver.find_elements.
+#
+# @overload ui(args)
+#   @param locator [Symbol] The locator type.
+#   @param value [String] The locator value.
+#   @return [Citronella::Ui::WebUi] The web element object.
+#
 def ui(args)
-  """
-  forward the data to page decorator and wrap into WebUi class.
-
-  Args:
-      by
-
-  Kwarg:
-      page(optional)
-
-  Usage:
-      without reference / page object. ui(name:  'q')
-      with reference / page object.    ui(id: 'submit', UserMenuPage)
-
-  page are reference for the next page object if the element redirect to
-  another page with WebUi click and send_keys(enter key) from input form.
-  """
-  return args.delete(:page), args
+  args
 end

data/lib/web_page.rb

@@ -21,107 +21,89 @@
 #SOFTWARE.
 
 
-require_relative 'page_tab'
 require_relative 'page_decorator'
 require_relative 'web_ui'
 
 module Citronella
   module Web
+    # An object class that is used across the tests.
+    # `webdriver_wait` is set to '10' seconds by default.
+    # `logger` is set to 'true' by default.
+    #
+    # @param [Webdriver] driver The web driver object.
+    # @param [Integer] webdriver_wait The timeout for webdriver wait.
+    # @param [Boolean] logger A flag indicating whether to log actions.
+    #
+    # Usage:
+    #   driver = Selenium::WebDriver.for :chrome
+    #   web = WebPage.new(driver)
+    #
     class WebPage
-      """
-      an object class that use across the tests.
-      webdriver_wait is set '10' seconds by default
-      logger is set 'True' by default
-
-      Args:
-          driver
-      Kwargs (optional):
-          webdriver_wait
-          logger
-
-      Usage:
-          driver = Selenium::WebDriver.for :chrome
-          web = WebPage(driver)
-      """
       def initialize(driver, webdriver_wait:10, logger:true)
         @driver = driver
         @webdriver_wait = webdriver_wait
-        @pages = Citronella::PagesList.new
+        @page = nil
         @logger = logger
       end
 
+      # Returns the original Selenium driver.
+      #
+      # @return [Webdriver] The web driver object.
+      #
       def driver
-        """return the original selenium / appium driver."""
         @driver
       end
 
-      def page_object(new_page, url=false)
-        """
-        initialize page object module object, url kwargs is optional and
-        it set to FALSE by default, it can be use if the page object have
-        an @url variable.
-        in selenium:
-        it's equal as self.driver.navigate.to(url)
-
-        Args:
-            page_object_model
-
-        Kwargs:
-            url=true
-
-        Usage:
-            self.browser.page_object(Homepage)
-            or
-            self.browser.page_object(Homepage, url=true)
-        """
-        @pages.append(new_page)
-        if url
-          if not new_page.instance_variable_get(:@url)
-            raise "Error: '@url' variable does not exist in #{new_page}"
-          end
-          @driver.navigate.to(new_page.instance_variable_get(:@url))
-        end
-      end
-
+      # Returns the wrapped page object model.
+      #
+      # @return [Citronella::Wrapper::PageDecorator] The page object model.
+      #
       def page
-        """return last page object model."""
-        Citronella::Wrapper::PageDecorator.new(@driver, @webdriver_wait, @pages, @logger)
+        Citronella::Wrapper::PageDecorator.new(@driver, @webdriver_wait, @page,
+                                               @logger)
       end
 
-      def locate(args)
-        """
-        an alternative way for testing without page object and return WebUi
-        class, but can't use page and back method and causing an error.
-        good for quick prototype / write a tests.
-
-        Args:
-            by
-            value
-
-        Usage:
-            web.ui(name: 'q').get_element.text
-            web.ui(name: 'q').get_element.click
-        """
-        Citronella::Ui::WebUi.new(@driver, @webdriver_wait, @pages, @logger, args, nil,
-                                  __method__.to_s, self.class.name.split('::').last.to_s)
+      # Sets the page object model.
+      #
+      # @param [PageObject] page The page object model.
+      #
+      def page=(page)
+        @page = page
       end
 
-      def back
-        """return to previous page and delete the last page object."""
-        @driver.navigate.back
-        @pages.pop
+      # An alternative way for testing without using page objects.
+      # It returns a WebUi class, but can't use `page` and may cause an error.
+      # It's good for quick prototypes or writing tests.
+      #
+      # @param [Hash] args The locator details.
+      # @return [Citronella::Ui::WebUi] The web element.
+      #
+      # Usage:
+      #   web.ui(name: 'q').get_element.text
+      #   web.ui(name: 'q').get_element.click
+      #
+      def locate(args)
+        Citronella::Ui::WebUi.new(@driver, @webdriver_wait, @logger, args,
+                                  args, __method__.to_s)
       end
 
+      # Executes JavaScript to wait for the page to fully load.
+      #
+      # @param [Integer] wait The number of times to check the page's ready state.
+      #
       def ready_state(wait)
-        """execute javascript for page to fully load"""
         wait.times do |i|
-          return if driver.execute_script("return document.readyState") == "complete"
+          return if driver.execute_script(
+            "return document.readyState") == "complete"
           sleep(1)
         end
       end
 
+      # Overrides the `webdriver_wait` value.
+      #
+      # @param [Integer] wait The new value for `webdriver_wait`.
+      #
       def webdriver_wait(wait)
-        """override webdriver wait."""
         @webdriver_wait = wait
       end
     end

data/lib/web_ui.rb

@@ -26,21 +26,31 @@ require_relative 'logger'
 module Citronella
   module Ui
     class WebUi
-      """a wrapped object of a web element."""
-      def initialize(driver, webdriver_wait, pages, logger, locator, new_page,
-                     function_name, class_name)
+      #
+      # @param [Webdriver] driver The web driver object.
+      # @param [Integer] webdriver_wait The timeout for webdriver wait.
+      # @param [Boolean] logger A flag indicating whether to log actions.
+      # @param [Hash] locator The locator for the web element.
+      # @param [String] function_name The name of the function.
+      # @param [String] class_name The name of the class.
+      #
+      def initialize(driver, webdriver_wait, logger, locator, function_name,
+                     class_name)
         @driver = driver
         @wait = webdriver_wait
-        @pages = pages
         @logger = logger
         @locator = locator
-        @new_page = new_page
         @function_name = function_name
         @class_name = class_name
       end
 
+      # Waits for a web element to be available and returns it.
+      #
+      # @param [Webdriver] ele The web driver object.
+      # @param [Boolean] displayed Flag indicating whether to wait for the element to be displayed.
+      # @return [Webdriver::Element] The web element.
+      #
       private def webdriver_wait(ele, displayed=false)
-        """return a web element or elements."""
         el = Selenium::WebDriver::Wait.new(timeout: @wait).until { ele }
         if displayed
           @wait.times do
@@ -51,41 +61,47 @@ module Citronella
         el
       end
 
-      def send_keys(text, clear=false, return_key=false, switch_page=true)
-        """custom webdriver send_keys with optional clear field."""
+      # Sends keys to the web element.
+      #
+      # @param [String] text The text to be sent.
+      # @param [Boolean] clear Flag indicating whether to clear the field before sending keys.
+      # @param [Boolean] return_key Flag indicating whether to send a return key.
+      #
+      def send_keys(text, clear=false, return_key=false)
         Citronella::Log.logger(@logger, @class_name, @function_name, __method__)
         el = webdriver_wait(@driver.find_element(@locator), displayed=true)
         el.send_keys text
 
         if return_key
           el.send_keys :return
-
-          if @new_page and switch_page
-            @pages.append(@new_page)
-          end
         end
       end
 
-      def click(switch_page=true)
-        """click to web element."""
+      # Clicks on the web element.
+      #
+      def click
         Citronella::Log.logger(@logger, @class_name, @function_name, __method__)
         el = webdriver_wait(@driver.find_element(@locator), displayed=true)
         el.click
-
-        if @new_page and switch_page
-          @pages.append(@new_page)
-        end
       end
 
+      # Returns a web element using find_element method.
+      #
+      # @return [Webdriver::Element] The web element.
+      #
       def get_element
-        """return web element, equal as find_element."""
-        Citronella::Log.logger(@logger, @class_name, @function_name, __method__.to_s)
+        Citronella::Log.logger(@logger, @class_name, @function_name,
+                               __method__.to_s)
         webdriver_wait(@driver.find_element(@locator))
       end
 
+      # Returns a list of web elements using find_elements method.
+      #
+      # @return [Array<Webdriver::Element>] The list of web elements.
+      #
       def get_elements
-        """return list of web element, equal as find_elements."""
-        Citronella::Log.logger(@logger, @class_name, @function_name, __method__.to_s)
+        Citronella::Log.logger(@logger, @class_name, @function_name,
+                               __method__.to_s)
         webdriver_wait(@driver.find_elements(@locator))
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: citronella
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 1.0.1
 platform: ruby
 authors:
 - heyclore
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-12 00:00:00.000000000 Z
+date: 2023-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -36,8 +36,6 @@ files:
 - lib/citronella.rb
 - lib/logger.rb
 - lib/page_decorator.rb
-- lib/page_tab.rb
-- lib/placeholder_page.rb
 - lib/ui.rb
 - lib/web_page.rb
 - lib/web_ui.rb

data/lib/page_tab.rb

@@ -1,51 +0,0 @@
-#MIT License
-#
-#Copyright (c) 2023 Eko Purnomo
-#
-#Permission is hereby granted, free of charge, to any person obtaining a copy
-#of this software and associated documentation files (the "Software"), to deal
-#in the Software without restriction, including without limitation the rights
-#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#copies of the Software, and to permit persons to whom the Software is
-#furnished to do so, subject to the following conditions:
-#
-#The above copyright notice and this permission notice shall be included in all
-#copies or substantial portions of the Software.
-#
-#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-#SOFTWARE.
-
-
-module Citronella
-  class PagesList
-    """This is a page page tab class."""
-    def initialize
-      @pages = []
-    end
-
-    def current_page
-      """return the last page object stored."""
-      @pages.last
-    end
-
-    def append(new_page)
-      """store the page object in _pages."""
-      @pages << new_page
-      if @pages.length > 5
-        @pages.shift
-      end
-    end
-
-    def pop
-      """delete the last item of the _pages lists."""
-      return if @pages.empty?
-      @pages.delete_at(-1)
-    end
-  end
-end
-

data/lib/placeholder_page.rb

@@ -1,29 +0,0 @@
-#MIT License
-#
-#Copyright (c) 2023 Eko Purnomo
-#
-#Permission is hereby granted, free of charge, to any person obtaining a copy
-#of this software and associated documentation files (the "Software"), to deal
-#in the Software without restriction, including without limitation the rights
-#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#copies of the Software, and to permit persons to whom the Software is
-#furnished to do so, subject to the following conditions:
-#
-#The above copyright notice and this permission notice shall be included in all
-#copies or substantial portions of the Software.
-#
-#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-#SOFTWARE.
-
-
-module Citronella
-  module Dummy
-    class PlaceholderPage
-    end
-  end
-end