kobot 1.0.0 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9d8a789566c49cffabd4006d13502a6222a211d9193cdf58f0523c6dd89937
-  data.tar.gz: 993fed11502b5149ece85da3d46d69f74169cf75c479221e56becf6b195d6d97
+  metadata.gz: 3eba14b1e3b076a368dd700c2ac46a9db4fd13bf57a58e29797de7db7eb16fc3
+  data.tar.gz: 1926333cefbaf4272ae117cc7afb12284ed85d6ff41aa96a02094904599b5312
 SHA512:
-  metadata.gz: 3fe31ae275852246a0ba1656f829352ef204278d55f4578bc160d1917b8c07a8586b621eee42ed80e1c7535c0650de0cd8a7edcbb5b7da9f7359f2fa42a8a435
-  data.tar.gz: e904e08fe88b5c616e5c7287e77a6de4d0e7b85dba1306e4c5dd8ab9ff24938437cd69dcfed4e2da0c6904ddbfb561a96a4aea92f0d61a268b2460591d950efe
+  metadata.gz: '08ad9cb2d55c2931a34ed4243884a7e16c189d1d914e5aa935cfd4d32fc3d3d7567cdaecdb53de54e980e84ec4c6e696761b7f9b15fb65e3a0eef11f829370e5'
+  data.tar.gz: f8662e41fe53d35df04b1b530f946621330124684d6bd955e6b18e53830efaef74c22db66818a8a3958aa8a4745b4d37090419f538962c3a4876e8dbb9b6c1d7

data/CHANGELOG.md

@@ -1,2 +1,24 @@
 ### v1.0.0
 - Initial release
+
+### v1.1.0
+- Deprecated lower-case environment variables for credentials configuration
+- Updated option help doc to indicate weekends and public holidays are skipped by default
+- Updated required_ruby_version to be >= 2.4.0 to align with the webdrivers dependency
+
+### v1.2.0
+- Added an option to allow forcibly running regardless of weekends or public holidays
+- Added an ENV flag to allow requiring lib in local workspace for development purpose
+
+### v1.2.1
+- Improved logging for better readability in logs
+- Switched to builtin Logger#deprecate from Logger#warn for deprecations
+- Renamed internal method to skip? from holiday? as it was meant for skipping any specified date
+
+### v1.2.2
+- Improved login screen wait and logging
+- Applied fix for offenses about empty lines and long lines reported by Rubocop
+
+### v1.2.3
+- Improved validation logic to skip running due to weekend or intentional skips
+- Refactored engine by reducing methods length based on reports by Rubocop

data/README.md

@@ -1,8 +1,9 @@
-# Kobot
+# Kobot [![Gem Version](https://badge.fury.io/rb/kobot.svg)](https://badge.fury.io/rb/kobot)
 
 Kobot is a simple tool to automate the clock in or clock out operation on the web service
-provided by [KING OF TIME](kingtime.jp) by leveraging [Selenium WebDriver](selenium.dev),
-and with Google Gmail service email notification can also be sent to notify the results.
+provided by [KING OF TIME](https://www.kingtime.jp/) by leveraging [Selenium WebDriver](
+https://www.selenium.dev/), and with Google Gmail service email notifications can also be
+sent to notify the results.
 
 It is meant for use only by one working under the discretionary labor system or flexible
 hours where the daily record is still required regardless of the actual start or end time
@@ -21,10 +22,11 @@ Tested on macOS Catelina and runs on Heroku platform so it works on unix-like sy
 #### Configuration
 
 By default it uses `~/.kobot` file locally to persist credentials for reuse, but all credentials
-can be overridden by setting environment variables, which is the recommended way of running the
-job on platforms like Heroku. When running for the first time, if none of the configuration file
-and ENV satisfies all required credentials, an interactive prompt will be displayed for setting,
-so there is no need to manually prepare the file beforehand. The content looks something like:
+can also be supplied or overridden by runtime environment variables, which is the recommended way
+of running as scheduled jobs on platforms like Heroku. When running for the first time, if neither
+the configuration file nor ENV satisfies all required credentials, `an interactive prompt will be
+displayed for initial setting, so there is no need to manually prepare the file beforehand`. The
+content looks something like:
 ```property
 kot_id=xxx
 kot_password=xxx
@@ -34,6 +36,7 @@ Gmail account and password (or `app` password if MFA is on) are asked when notif
 gmail_id=xxx
 gmail_password=xxx
 ```
+Note: use all upper-case letters for the above variables if using environment variables, e.g. `KOT_ID`.
 
 #### Google Chrome browser
 
@@ -51,17 +54,20 @@ $ gem install kobot
 ## Usage
 
 Get help doc:
-```bash
+```
 $ kobot -h
 Usage: kobot [options]
-    -c, --clock CLOCK                The clock action: in, out
-    -l, --loglevel [LEVEL]           Specify log level: debug, info, warn, error. Default is info
+    -c, --clock CLOCK                Required; the clock action option: in, out
+    -l, --loglevel [LEVEL]           Specify log level: debug, info, warn, error; default is info
     -s, --skip [D1,D2,D3]            Specify dates to skip clock in/out with date format YYYY-MM-DD and
-                                     multiple values separated by comma, such as: 2020-05-01,2020-12-31
-    -t, --to [TO]                    Email address to send notification to. By default it is sent to
+                                     multiple values separated by comma, such as: 2020-05-01,2020-12-31;
+                                     weekends and public holidays in Japan will be skipped by default
+    -t, --to [TO]                    Email address to send notification to; by default it is sent to
                                      the same self email account used in SMTP config as the sender
     -n, --notify                     Enable email notification
     -d, --dryrun                     Run the process without actual clock in/out
+    -f, --force                      Run the process forcibly regardless of weekends or public holidays;
+                                     must be used together with --dryrun to prevent mistaken operations
     -x, --headless                   Start browser in headless mode
     -g, --geolocation                Allow browser to use geolocation
     -h, --help                       Show this help message
@@ -69,20 +75,25 @@ Usage: kobot [options]
 ```
 
 Dryrun to try out:
-```bash
-$ kobot --clock in --dryrun
+```
+$ kobot --clock in --notify --dryrun
 ```
 
 Clock in/out with email notification
-```bash
-$ kobot --clock in --notify
-$ kobot --clock out --notify
+```
+$ kobot --clock in --notify --headless
+$ kobot --clock out --notify --headless
 ```
 
 Run the task with crontab
 ```cron
-30 09 * * * user kobot --clock in --notify
-30 18 * * * user kobot --clock out --notify
+# Weekend and public holidays will be skipped by default
+30 09 * * * user kobot --cin -n -x
+30 18 * * * user kobot --cout -n -x
+
+# Skip for weekdays planned to take leave for example
+30 09 * * * user kobot --cin -n -x -s 2020-09-01,2020-11-11
+30 18 * * * user kobot --cout -n -x -s 2020-09-01,2020-11-11
 ```
 On platforms like Heroku, an add-on called [Heroku Scheduler](https://elements.heroku.com/addons/scheduler) makes
 running scheduled tasks much easier. Tips: either clock in or clock out task can be scheduled multiple times in

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'kobot'

data/exe/kobot

@@ -1,6 +1,15 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'kobot'
+begin
+  # For quickly tryout in local development
+  # without installing to system gems path
+  raise LoadError if ENV['KOBOT_DEV']
+
+  require 'kobot'
+rescue LoadError
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'kobot'
+end
 
 Kobot.run

data/kobot.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
 
   spec.homepage                      = 'https://github.com/yuan-jiang/kobot'
   spec.license                       = 'MIT'
-  spec.required_ruby_version         = Gem::Requirement.new('>= 2.3.0')
+  spec.required_ruby_version         = Gem::Requirement.new('>= 2.4.0')
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
   spec.metadata['homepage_uri']      = spec.homepage

data/lib/kobot.rb

@@ -14,8 +14,6 @@ require 'kobot/engine'
 # and with Google Gmail service email notification can also be sent to notify the results.
 module Kobot
   class << self
-
-    # The entrance to run Kobot.
     def run
       configure
       Engine.new.start
@@ -33,6 +31,7 @@ module Kobot
         config.clock                 = options[:clock].to_sym
         config.loglevel              = options[:loglevel]&.to_sym || :info
         config.dryrun                = options[:dryrun]
+        config.force                 = options[:force]
         config.skip                  = options[:skip] || []
 
         config.kot_url               = 'https://s2.kingtime.jp/independent/recorder/personal/'

data/lib/kobot/config.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Kobot
-
   # Configuration definition includes static ones hardcoded and
   # dynamic ones that can be specified by command line options.
   class Config
@@ -9,7 +8,8 @@ module Kobot
       attr_accessor :clock,
                     :loglevel,
                     :skip,
-                    :dryrun
+                    :dryrun,
+                    :force
 
       attr_accessor :kot_url,
                     :kot_timezone_offset,

data/lib/kobot/credential.rb

@@ -4,7 +4,6 @@ module Kobot
   # Credentials include id and password to login to KOT and
   # Gmail SMTP id and password to send email notifications.
   class Credential
-
     class << self
       attr_accessor :kot_id,
                     :kot_password,
@@ -30,7 +29,7 @@ module Kobot
         @credentials.each do |attr, value|
           send("#{attr}=".to_sym, value)
         end
-        Kobot.logger.info('Credentials load successful')
+        Kobot.logger.info('Load credentials successful')
         Kobot.logger.debug(@credentials)
       end
 
@@ -41,18 +40,18 @@ module Kobot
         if File.exist? Config.credentials_file
           File.open(Config.credentials_file) do |file|
             file.each do |line|
-              attr, value = line.chomp.split('=')
+              attr, value = line.strip.split('=')
               @credentials[attr] = value
             end
           end
         end
-        @credentials['kot_id'] = ENV['kot_id'] if ENV['kot_id']
-        @credentials['kot_password'] = ENV['kot_password'] if ENV['kot_password']
-        @credentials['gmail_id'] = ENV['gmail_id'] if ENV['gmail_id']
-        @credentials['gmail_password'] = ENV['gmail_password'] if ENV['gmail_password']
-
         required_credentials = %w[kot_id kot_password]
         required_credentials.concat %w[gmail_id gmail_password] if Config.gmail_notify_enabled
+        required_credentials.each do |attr|
+          Kobot.logger.deprecate(attr, attr.upcase) if ENV[attr]
+          env_attr_value = ENV[attr.upcase] || ENV[attr]
+          @credentials[attr] = env_attr_value if env_attr_value
+        end
         required_credentials.none? do |attr|
           credential = @credentials[attr]
           !credential || credential.strip.empty?

data/lib/kobot/engine.rb

@@ -6,7 +6,6 @@ module Kobot
   # The core class that launches browser, logins to KOT, reads today
   # record, and conducts clock in or clock out action based on config.
   class Engine
-
     def initialize
       @now = Time.now.getlocal(Config.kot_timezone_offset)
       @today = @now.strftime(Config.kot_date_format)
@@ -25,28 +24,19 @@ module Kobot
     # System errors or any unknown exceptions occurred if any are
     # to be popped up and should be handled by the outside caller.
     def start
-      if weekend?
-        Kobot.logger.info("Today=#{@today} is weekend.")
-        return
-      end
-      if holiday?
-        Kobot.logger.info("Today=#{@today} is holiday.")
-        return
-      end
-      unless %i[in out].include? Config.clock
-        Kobot.logger.warn("Invalid clock operation: #{Config.clock}")
-        return
-      end
+      validate_today!
       launch_browser
       login
       read_today_record
-      verify_today_record!
+      validate_today_record!
       if Config.clock == :in
         clock_in!
       else
         clock_out!
       end
       logout
+    rescue KotSkip => e
+      Kobot.logger.warn(e.message)
     rescue KotRecordError => e
       Kobot.logger.warn(e.message)
       Mailer.send(clock_notify_message(status: e.message))
@@ -65,11 +55,20 @@ module Kobot
       Mailer.send(clock_notify_message(status: e.message))
       logout
     ensure
-      @browser&.quit
+      close_browser
     end
 
     private
 
+    def validate_today!
+      raise KotSkip, "Today=#{@today} is skipped as per: --skip=#{Config.skip}" if skip?
+
+      return unless weekend?
+      raise KotSkip, "Today=#{@today} is weekend" unless Config.force
+
+      Kobot.logger.info("[Force] should have exited: today=#{@today} is weekend")
+    end
+
     def launch_browser
       prefs = {
         profile: {
@@ -85,9 +84,18 @@ module Kobot
       Kobot.logger.info('Launch browser successful')
     end
 
+    def close_browser
+      return unless @browser
+
+      Kobot.logger.info('Close browser')
+      @browser.quit
+    end
+
     def login
-      @browser.get @top_url
       Kobot.logger.info("Navigate to: #{@top_url}")
+      @browser.get @top_url
+      @wait.until { @browser.find_element(id: 'modal_window') }
+      Kobot.logger.info "Page title: #{@browser.title}"
       Kobot.logger.debug do
         "Login with id=#{Credential.kot_id} and password=#{Credential.kot_password}"
       end
@@ -104,13 +112,15 @@ module Kobot
           Kobot.logger.warn "Get geolocation failed: #{e.message}"
         end
       end
-      Kobot.logger.info @browser.title
+      Kobot.logger.info "Page title: #{@browser.title}"
     end
 
     def logout
       if @browser.current_url.include? 'admin'
+        Kobot.logger.info('Logout from タイムカード page')
         @browser.find_element(css: 'div.htBlock-header_logoutButton').click
       else
+        Kobot.logger.info('Logout from Myレコーダー page')
         @wait.until { @browser.find_element(id: 'menu_icon') }.click
         @wait.until { @browser.find_element(link: 'ログアウト') }.click
         @browser.switch_to.alert.accept
@@ -119,6 +129,7 @@ module Kobot
     end
 
     def read_today_record
+      Kobot.logger.info('Navigate to タイムカード page')
       @wait.until { @browser.find_element(id: 'menu_icon') }.click
       @wait.until { @browser.find_element(link: 'タイムカード') }.click
 
@@ -131,8 +142,12 @@ module Kobot
         @kot_today = date_cell.text
         @kot_today_css_class = date_cell.attribute('class')
         @kot_today_type = tr.find_element(css: 'td.work_day_type').text
-        @kot_today_clock_in = tr.find_element(css: 'td.start_end_timerecord[data-ht-sort-index="START_TIMERECORD"]').text
-        @kot_today_clock_out = tr.find_element(css: 'td.start_end_timerecord[data-ht-sort-index="END_TIMERECORD"]').text
+        @kot_today_clock_in = tr.find_element(
+          css: 'td.start_end_timerecord[data-ht-sort-index="START_TIMERECORD"]'
+        ).text
+        @kot_today_clock_out = tr.find_element(
+          css: 'td.start_end_timerecord[data-ht-sort-index="END_TIMERECORD"]'
+        ).text
         Kobot.logger.debug do
           {
             kot_toay: @kot_today,
@@ -146,10 +161,23 @@ module Kobot
       end
     end
 
-    def verify_today_record!
-      raise KotRecordError, "Today=#{@today} is not found on kot." if @kot_today.strip.empty?
-      raise KotRecordError, "Today=#{@today} is marked as weekend on kot: #{@kot_today}" if kot_weekend?
-      raise KotRecordError, "Today=#{@today} is marked as public holiday on kot: #{@kot_today}" if kot_public_holiday?
+    def validate_today_record!
+      raise KotRecordError, "Today=#{@today} is not found on kot" if @kot_today.strip.empty?
+
+      if kot_weekend?
+        raise KotRecordError, "Today=#{@today} is marked as weekend on kot: #{@kot_today}" unless Config.force
+
+        Kobot.logger.info(
+          "[Force] should have exited: today=#{@today} is marked as weekend on kot: #{@kot_today}"
+        )
+      end
+
+      return unless kot_public_holiday?
+      raise KotRecordError, "Today=#{@today} is marked as public holiday on kot: #{@kot_today}" unless Config.force
+
+      Kobot.logger.info(
+        "[Force] should have exited: today=#{@today} is marked as public holiday on kot: #{@kot_today}"
+      )
     end
 
     def clock_in!
@@ -192,21 +220,25 @@ module Kobot
     end
 
     def click_clock_in_button
+      Kobot.logger.info("Navigate to: #{@top_url}")
       @browser.get @top_url
       clock_in_button = @wait.until { @browser.find_element(css: 'div.record-clock-in') }
       if Config.dryrun
         Kobot.logger.info('[Dryrun] clock in button (出勤) would have been clicked')
       else
+        Kobot.logger.info('Clicking the clock in button (出勤)')
         clock_in_button.click
       end
     end
 
     def click_clock_out_button
+      Kobot.logger.info("Navigate to: #{@top_url}")
       @browser.get @top_url
       clock_out_button = @wait.until { @browser.find_element(css: 'div.record-clock-out') }
       if Config.dryrun
         Kobot.logger.info('[Dryrun] clock out button (退勤) would have been clicked')
       else
+        Kobot.logger.info('Clicking the clock in button (退勤)')
         clock_out_button.click
       end
     end
@@ -215,7 +247,7 @@ module Kobot
       @now.saturday? || @now.sunday?
     end
 
-    def holiday?
+    def skip?
       return false unless Config.skip
       return false unless Config.skip.respond_to? :include?
 

data/lib/kobot/exception.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Kobot
+  class KotSkip < StandardError
+  end
 
   class KotRecordError < StandardError
   end
@@ -10,5 +12,4 @@ module Kobot
 
   class KotClockOutError < StandardError
   end
-
 end

data/lib/kobot/mailer.rb

@@ -3,11 +3,9 @@
 require 'net/smtp'
 
 module Kobot
-
   # Responsible for sending email notifications in SMTP with Gmail
   class Mailer
     class << self
-
       # Sends email in preconfigured Gmail SMTP credential and to the recipient
       # configured by #{Config.gmail_notify_to} or self if not configured, with
       # email subject set by #{Config.gmail_notify_subject}.

data/lib/kobot/option.rb

@@ -3,33 +3,32 @@
 require 'optparse'
 
 module Kobot
-
   # Responsible for parsing the command line options for custom execution.
   class Option
     class << self
-
       # Parses command line options and returns a hash containing the options.
       def parse!
         options = {}
         opt_parser = OptionParser.new do |opt|
           opt.banner = "Usage: #{$PROGRAM_NAME} [options]"
 
-          opt.on('-c', '--clock CLOCK', 'The clock action: in, out') do |clock|
+          opt.on('-c', '--clock CLOCK', 'Required; the clock action option: in, out') do |clock|
             options[:clock] = clock
           end
 
-          opt.on('-l', '--loglevel [LEVEL]', 'Specify log level: debug, info, warn, error. Default is info') do |level|
+          opt.on('-l', '--loglevel [LEVEL]', 'Specify log level: debug, info, warn, error; default is info') do |level|
             options[:loglevel] = level
           end
 
           opt.on('-s', '--skip [D1,D2,D3]', Array,
                  'Specify dates to skip clock in/out with date format YYYY-MM-DD and',
-                 'multiple values separated by comma, such as: 2020-05-01,2020-12-31') do |skip|
+                 'multiple values separated by comma, such as: 2020-05-01,2020-12-31;',
+                 'weekends and public holidays in Japan will be skipped by default') do |skip|
             options[:skip] = skip
           end
 
           opt.on('-t', '--to [TO]',
-                 'Email address to send notification to. By default it is sent to',
+                 'Email address to send notification to; by default it is sent to',
                  'the same self email account used in SMTP config as the sender') do |to|
             options[:to] = to
           end
@@ -42,6 +41,12 @@ module Kobot
             options[:dryrun] = dryrun
           end
 
+          opt.on('-f', '--force',
+                 'Run the process forcibly regardless of weekends or public holidays;',
+                 'must be used together with --dryrun to prevent mistaken operations') do |force|
+            options[:force] = force
+          end
+
           opt.on('-x', '--headless', 'Start browser in headless mode') do |headless|
             options[:headless] = headless
           end
@@ -62,7 +67,12 @@ module Kobot
         end
         opt_parser.parse! ARGV
         raise OptionParser::MissingArgument, 'The clock option is required' if options[:clock].nil?
-        raise OptionParser::InvalidArgument, 'The clock option must be either: in, out' unless %w[in out].include? options[:clock]
+        unless %w[in out].include? options[:clock]
+          raise OptionParser::InvalidArgument, 'The clock option must be either: in, out'
+        end
+        if options[:force] && !options[:dryrun]
+          raise OptionParser::InvalidArgument, 'Must specify --dryrun for forcibly running'
+        end
 
         options
       rescue OptionParser::MissingArgument, OptionParser::InvalidArgument => e

data/lib/kobot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobot
-  VERSION = '1.0.0'
+  VERSION = '1.2.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kobot
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.3
 platform: ruby
 authors:
 - Andy Jiang
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-10 00:00:00.000000000 Z
+date: 2020-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: webdrivers
@@ -100,7 +100,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="