boq_com_au 0.0.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1878f447c68ac5fc43e6982352185cfba05604eae3aaa849542e64e489e012fa
4
- data.tar.gz: 9e1127f5f592781198af0bd5a986dbcbd07ffd409c183d6a879a9dc3ec47f126
3
+ metadata.gz: 25b9fba8414050a29c7aba82c8f7e19df4ed098ece4345ec16002897fd3d8f10
4
+ data.tar.gz: 0e6053f79b2391dcccf6283100508c02b30b54155406663270bac28f32da58a4
5
5
  SHA512:
6
- metadata.gz: f4d30ffaaf0d48874655dfb1cf23a5d11748374be4ad2c9bb8a39073db5fa6e5e750e26945514b2c0b6fca71a3a460a534866dc9bc5e99535620d34c7e0a7b51
7
- data.tar.gz: c4fe46849427efb5c5d8d7d4aeeda21cb9b01ff69b974182f15dbd8d8083302fc6ef333aa37be6e316db4883040afdd51454f49580e63069670aba8621feef11
6
+ metadata.gz: 3fcf4ff2fb9ecfe8eb73d7cc5751202c4c16f4fd3876f3b448616477f2cc0719cf6b5151c67960ecd3ec9b2a1e18cc1c82472f484376565f68fcf87b84a98782
7
+ data.tar.gz: be41871305543362742a9cd6d86e56cfa26a1d320e4a624be742af293d4c5d417fc2d4202302926fec37d3725803e8bd572f07c882fe87c79e5daf292144f64d
data/CHANGELOG CHANGED
@@ -1,7 +1,35 @@
1
1
  # boq_com_au/CHANGELOG
2
2
 
3
+ ## 20261104
4
+
5
+ 0.2.0: + BoqComAu::Account#download_transactions(period:, from_date:, to_date:), choosing the dates.
6
+
7
+ 1. + BoqComAu::Account::TRANSACTIONS_SELECTORS: + advanced_search_link, text_fields, search_link.
8
+ 2. ~ BoqComAu::Account#download_transactions: + period: (:all, the last year, or :last_month), + from_date:, + to_date:; given any, the dates are set under Advanced Search and searched on before exporting.
9
+ 3. + BoqComAu::Account#dates, #last_month_start_date, #last_month_finish_date, #formatted_date
10
+ 4. + BoqComAu::Account#enter_dates: the displayed date fields set by JavaScript, so as a date picker doesn't open over them; and stops where the values didn't take, rather than exporting another range.
11
+ 5. + BoqComAu::Account#search: waits for the Export All link from before the search to be replaced, else what was there before would be exported.
12
+ 6. + BoqComAu::Account#set_value, #stale?, #date_fields
13
+ 7. ~ BoqComAu::Transactions.download_csv_file: + period:, from_date:, to_date:
14
+ 8. ~ test/BoqComAu/Account_test.rb, test/BoqComAu/Transactions_test.rb
15
+ 9. ~ README.md: choosing the dates.
16
+ 10. ~ BoqComAu::VERSION: /0.1.0/0.2.0/
17
+
18
+
3
19
  ## 20261103
4
20
 
21
+ 0.1.0: + BoqComAu::Account#download_transactions, exporting an account's transactions as a CSV file.
22
+
23
+ 1. + BoqComAu::Account::TRANSACTIONS_SELECTORS
24
+ 2. + BoqComAu::Account#download_transactions(account_number:): Transaction History, the account chosen by the digits of its number, then Export All as CSV; returns the file downloaded.
25
+ 3. + BoqComAu::Account#initialize(download_directory:), #download_directory: Chrome downloads there without asking, and opens nothing.
26
+ 4. + BoqComAu::Account#click, #wait_for, #choose_option: a link not displayed is clicked by JavaScript; a select hidden by Chosen is chosen from by its own list, once Chosen has drawn it.
27
+ 5. + BoqComAu::Account#newest_csv_filename, #wait_for_download: the file is the newest CSV since Download was clicked, rather than BOQ's name for it, which Chrome numbers where a download of the same day is there already.
28
+ 6. + BoqComAu::Transactions.download_csv_file: login, download and shutdown in one, shutting down even where the download fails.
29
+ 7. ~ test/BoqComAu/Account_test.rb, + test/BoqComAu/Transactions_test.rb
30
+ 8. ~ README.md, boq_com_au.gemspec: downloading transactions.
31
+ 9. ~ BoqComAu::VERSION: /0.0.3/0.1.0/
32
+
5
33
  0.0.3: BoqComAu::Account#login is WebAccount's, which waits for the log off link.
6
34
 
7
35
  1. - BoqComAu::Account#login, #logon
data/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Description
4
4
 
5
- Log into BOQ Classic Internet Banking (ib.boq.com.au), via Selenium WebDriver and WebAccount.
5
+ Log into BOQ Classic Internet Banking (ib.boq.com.au) and export an account's transactions as a CSV file, via Selenium WebDriver and WebAccount.
6
6
 
7
7
  myBOQ, BOQ's newer internet banking site, isn't covered.
8
8
 
@@ -23,16 +23,33 @@ $ gem install boq_com_au
23
23
 
24
24
  ## Usage
25
25
 
26
- ### Logging in, out, and shutting down
26
+ ### Downloading transactions
27
27
  ```ruby
28
28
  require 'boq_com_au'
29
29
 
30
30
  boq_account = BoqComAu::Account.new
31
31
  boq_account.login
32
- boq_account.driver # The logged-in browser.
33
- boq_account.logout
32
+ boq_account.download_transactions(account_number: '12345678')
33
+ # => "/Users/me/Downloads/12345678_20261103.csv"
34
34
  boq_account.shutdown # Logs out if still logged in, then quits Chrome.
35
35
  ```
36
+ The account is picked from the list by the digits of its number alone, so `'12345678'` and `'1234 5678'` are the same. Its transactions are exported with Export All as Comma Delimited Format (CSV).
37
+
38
+ Without dates, the transactions are those BOQ shows on choosing the account. Given a period or dates, they're set under Advanced Search and searched on first:
39
+ ```ruby
40
+ boq_account.download_transactions(account_number: '12345678', period: :last_month)
41
+ boq_account.download_transactions(account_number: '12345678', period: :all) # The last year.
42
+ boq_account.download_transactions(account_number: '12345678', from_date: '2026-01-01', to_date: '2026-06-30')
43
+ ```
44
+ Dates are Dates, or Strings `Date.parse` can read. Where only one of `from_date` and `to_date` is given, the other is a year ago or today.
45
+
46
+ `download_transactions` waits for the download to finish, and returns the newest CSV file to have appeared in the download directory since Download was clicked. BOQ names it after the account number and the day's date, and Chrome adds a number to that where a file of the name is there already.
47
+
48
+ Or in one step, logging in, downloading, and shutting down even where the download fails:
49
+ ```ruby
50
+ BoqComAu::Transactions.download_csv_file(account_number: '12345678', period: :last_month)
51
+ ```
52
+ It takes `period:`, `from_date:` and `to_date:` as `download_transactions` does. Any other keyword arguments are passed to `BoqComAu::Account.new`.
36
53
 
37
54
  ### Credentials
38
55
 
@@ -49,13 +66,17 @@ Chrome is started with its automation flags masked. Given a `chrome_profile_dire
49
66
  ```ruby
50
67
  BoqComAu::Account.new(chrome_profile_directory: '~/path/to/chrome-profile')
51
68
  ```
69
+ Chrome downloads into `download_directory`, `~/Downloads` unless given, without asking where, and opens nothing it downloads:
70
+ ```ruby
71
+ BoqComAu::Account.new(download_directory: '~/path/to/statements')
72
+ ```
52
73
  Passing `browser:` or `driver_options:` to `BoqComAu::Account.new` replaces all of that, as for any WebAccount.
53
74
 
54
75
  Where BOQ asks for a one-time code after logging on, `login` waits up to 30 seconds for it to be entered in the browser.
55
76
 
56
77
  ## Limitations
57
78
 
58
- The login page's selectors were taken from the live page. BOQ's ids are generated, so things are found by their labels and text, and a change to the wording of the site will break it.
79
+ The selectors were taken from the live site. BOQ's ids are generated, so things are found by their labels and text, and a change to the wording of the site will break it.
59
80
 
60
81
  The tests cover only what doesn't depend on BOQ's site.
61
82
 
data/boq_com_au.gemspec CHANGED
@@ -14,8 +14,8 @@ Gem::Specification.new do |spec|
14
14
  spec.name = 'boq_com_au'
15
15
  spec.version = BoqComAu::VERSION
16
16
 
17
- spec.summary = "Log into BOQ Classic Internet Banking via Selenium WebDriver."
18
- spec.description = "Log into BOQ Classic Internet Banking with a Customer Access Number and password."
17
+ spec.summary = "Download transactions from BOQ Classic Internet Banking via Selenium WebDriver."
18
+ spec.description = "Log into BOQ Classic Internet Banking with a Customer Access Number and password, and export an account's transactions as a CSV file."
19
19
 
20
20
  spec.author = 'thoran'
21
21
  spec.email = 'code@thoran.com'
@@ -3,10 +3,16 @@
3
3
 
4
4
  # Notes:
5
5
  # 1. The login page's ids and names (id4, 8, ...) appear to be generated, so the fields are found by their labels.
6
- # 2. Where a one-time code is asked for after logging on, login() waits default_wait_timeout seconds for it to be entered by hand.
7
- # 3. Chrome is started with its automation flags masked; and, given a chrome_profile_directory, with that profile, kept between runs, so as the bank sees a returning browser rather than a fresh automated one.
8
- # 4. A username or password not given stops login, saying which is missing.
6
+ # 2. The ids and names after login (id121, 74, ...) appear to be generated too, so TRANSACTIONS_SELECTORS find things by their text.
7
+ # 3. BankFast's links are javascript:void(0) where they aren't the session's key and a callback number, and some, such as Transaction History, are in a menu which is closed. A link which isn't displayed is clicked by JavaScript.
8
+ # 4. Dropdowns are Chosen's, which hides the select and draws its own: <select id>_chosen, opened by its a.chosen-single and chosen from its li.active-result. A select which is displayed is used as it is.
9
+ # 5. Where a one-time code is asked for after logging on, login() waits default_wait_timeout seconds for it to be entered by hand.
10
+ # 6. Chrome is started with its automation flags masked; and, given a chrome_profile_directory, with that profile, kept between runs, so as the bank sees a returning browser rather than a fresh automated one. It downloads into download_directory without asking, and opens nothing it downloads.
11
+ # 7. A username or password not given stops login, saying which is missing.
12
+ # 8. BOQ names the exported file after the account number and the date, as 12345678_20261103.csv, and Chrome numbers a second download of the same name; so the newest CSV file to appear in download_directory once Download is clicked is taken to be it. Chrome names a download in progress .crdownload, so a CSV file is a finished one.
13
+ # 9. Dates are BOQ's own, as shown on choosing the account, unless a period or a date is given; then they're set under Advanced Search and searched on before exporting.
9
14
 
15
+ require 'date'
10
16
  require 'webaccount'
11
17
 
12
18
  module BoqComAu
@@ -20,6 +26,18 @@ module BoqComAu
20
26
  logged_out_xpath: '//a[normalize-space()="Log On Again"] | //input[@id="btnSignIn"]'
21
27
  }
22
28
 
29
+ TRANSACTIONS_SELECTORS = {
30
+ transaction_history_link: {xpath: '//a[normalize-space()="Transaction History"]'},
31
+ account_select_list: {xpath: '//select[option[contains(., "Select one of the Accounts")]]'},
32
+ advanced_search_link: {xpath: '//a[normalize-space()="Advanced Search"]'},
33
+ text_fields: {xpath: '//input[@type="text"]'},
34
+ search_link: {xpath: '//a[normalize-space()="Search"]'},
35
+ export_all_link: {xpath: '//a[normalize-space()="Export All"]'},
36
+ export_format_select_list: {xpath: '//select[option[contains(., "Comma Delimited Format (CSV)")]]'},
37
+ download_button: {xpath: '//*[self::a or self::button][normalize-space()="Download"] | //input[@value="Download"]'}
38
+ }
39
+
40
+ attr_reader :download_directory
23
41
  def username
24
42
  @username || raise("No username: it's given as username:.")
25
43
  end
@@ -28,10 +46,23 @@ module BoqComAu
28
46
  @password || raise("No password: it's given as password:.")
29
47
  end
30
48
 
49
+ # period is :all, the last year, or :last_month. Without it, from_date and to_date, either of which defaults to a year ago and today respectively where the other is given. Returns the name of the CSV file downloaded.
50
+ def download_transactions(account_number:, period: nil, from_date: nil, to_date: nil)
51
+ from_date, to_date = dates(period: period, from_date: from_date, to_date: to_date)
52
+ get_transactions_page
53
+ select_bank_account(account_number)
54
+ if from_date
55
+ enter_dates(from_date: from_date, to_date: to_date)
56
+ search
57
+ end
58
+ export_csv
59
+ end
60
+
31
61
  private
32
62
 
33
- def initialize(username: nil, password: nil, chrome_profile_directory: nil, browser: nil, driver_options: nil)
63
+ def initialize(username: nil, password: nil, chrome_profile_directory: nil, download_directory: File.join('~', 'Downloads'), browser: nil, driver_options: nil)
34
64
  @chrome_profile_directory = chrome_profile_directory && File.expand_path(chrome_profile_directory)
65
+ @download_directory = File.expand_path(download_directory)
35
66
  super(
36
67
  username: username, password: password,
37
68
  browser: browser, driver_options: driver_options,
@@ -53,7 +84,140 @@ module BoqComAu
53
84
  o.add_argument('--disable-blink-features=AutomationControlled')
54
85
  o.exclude_switches << 'enable-automation'
55
86
  o.add_preference(:credentials_enable_service, false)
87
+ o.add_preference(:download, default_directory: @download_directory, prompt_for_download: false, directory_upgrade: true, extensions_to_open: '')
88
+ end
89
+ end
90
+
91
+ # page interaction
92
+
93
+ # Found afresh on each attempt, so as an element replaced by a redrawn page is retried rather than ending in StaleElementReferenceError.
94
+ def click(selector)
95
+ driver.attempt do
96
+ element = find(selector)
97
+ element.displayed? ? element.click : driver.execute_script('arguments[0].click();', element)
98
+ end
99
+ end
100
+
101
+ def stale?(element)
102
+ element.displayed?
103
+ false
104
+ rescue Selenium::WebDriver::Error::StaleElementReferenceError
105
+ true
106
+ end
107
+
108
+ def wait_for(selector)
109
+ driver_wait.until{driver.find_elements(*selector.first).any?(&:displayed?)}
110
+ end
111
+
112
+ # Dates are set by JavaScript, so as a date picker doesn't open over the fields.
113
+ def set_value(element, value)
114
+ driver.execute_script("arguments[0].value = arguments[1]; arguments[0].dispatchEvent(new Event('change', {bubbles: true}));", element, value)
115
+ end
116
+
117
+ def chosen_list(select_element)
118
+ driver.find_elements(id: "#{select_element.attribute('id')}_chosen").first
119
+ end
120
+
121
+ # Yields the text of each option in turn, and chooses the first for which the block is true; nil where there's none. A select hidden by Chosen is waited on until Chosen has drawn its list, which it does after the page has loaded.
122
+ def choose_option(select_element)
123
+ driver_wait.until{select_element.displayed? || chosen_list(select_element)}
124
+ if select_element.displayed?
125
+ option = Selenium::WebDriver::Support::Select.new(select_element).options.detect{|option| yield(option.text)}
126
+ else
127
+ chosen = chosen_list(select_element)
128
+ chosen.find_element(css: 'a.chosen-single').click
129
+ option = chosen.find_elements(css: 'li.active-result').detect{|option| yield(option.text)}
130
+ end
131
+ option&.click
132
+ option
133
+ end
134
+
135
+ # dates
136
+
137
+ def last_month_start_date
138
+ Date.today.prev_month - (Date.today.prev_month.day - 1)
139
+ end
140
+
141
+ def last_month_finish_date
142
+ Date.today - Date.today.day
143
+ end
144
+
145
+ # The from and to dates of the period, or of the dates given; nil and nil where neither is given, BOQ's own dates being used.
146
+ def dates(period:, from_date:, to_date:)
147
+ case period
148
+ when :all then [Date.today.prev_year, Date.today]
149
+ when :last_month then [last_month_start_date, last_month_finish_date]
150
+ when nil then (from_date || to_date) ? [from_date || Date.today.prev_year, to_date || Date.today] : [nil, nil]
151
+ else raise ArgumentError, "Unknown period #{period.inspect}: it's :all or :last_month."
152
+ end
153
+ end
154
+
155
+ def formatted_date(date)
156
+ date = Date.parse(date) if date.is_a?(String)
157
+ date.strftime('%d/%m/%Y')
158
+ end
159
+
160
+ # downloads
161
+
162
+ def newest_csv_filename(since:)
163
+ Dir.glob(File.join(@download_directory, '*.csv')).select{|filename| File.mtime(filename) >= since}.max_by{|filename| File.mtime(filename)}
164
+ end
165
+
166
+ def wait_for_download(since:)
167
+ driver_wait.until{newest_csv_filename(since: since)}
168
+ end
169
+
170
+ # transactions
171
+
172
+ def get_transactions_page
173
+ login unless logged_in?
174
+ click(TRANSACTIONS_SELECTORS[:transaction_history_link])
175
+ driver_wait.until{driver.element_present?(*TRANSACTIONS_SELECTORS[:account_select_list].first)}
176
+ end
177
+
178
+ def select_bank_account(account_number)
179
+ digits = account_number.to_s.delete('^0-9')
180
+ raise ArgumentError, "No digits in the account number #{account_number.inspect}." if digits.empty?
181
+ unless choose_option(find(TRANSACTIONS_SELECTORS[:account_select_list])){|text| text.delete('^0-9').include?(digits)}
182
+ raise "Can't find account #{account_number} in the account list."
183
+ end
184
+ wait_for(TRANSACTIONS_SELECTORS[:export_all_link])
185
+ end
186
+
187
+ # The from and to fields are the two displayed text fields holding a date, as BOQ fills them in. Hidden ones are the form before Advanced Search has redrawn it.
188
+ def date_fields
189
+ driver.find_elements(*TRANSACTIONS_SELECTORS[:text_fields].first).select{|field| field.displayed? && field.attribute('value').to_s.match?(%r{\A\d\d/\d\d/\d{4}\z})}
190
+ rescue Selenium::WebDriver::Error::StaleElementReferenceError
191
+ []
192
+ end
193
+
194
+ def enter_dates(from_date:, to_date:)
195
+ click(TRANSACTIONS_SELECTORS[:advanced_search_link])
196
+ from_date_field, to_date_field = driver_wait.until{fields = date_fields; fields if fields.size >= 2}
197
+ set_value(from_date_field, formatted_date(from_date))
198
+ set_value(to_date_field, formatted_date(to_date))
199
+ unless [from_date_field, to_date_field].map{|field| field.attribute('value')} == [formatted_date(from_date), formatted_date(to_date)]
200
+ raise "The dates #{formatted_date(from_date)} to #{formatted_date(to_date)} didn't take."
201
+ end
202
+ end
203
+
204
+ # Export All is already there before the search, and is replaced when the results are, so the old link is waited out first; otherwise it'd export what was there before.
205
+ def search
206
+ export_all_link = driver.find_elements(*TRANSACTIONS_SELECTORS[:export_all_link].first).first
207
+ click(TRANSACTIONS_SELECTORS[:search_link])
208
+ driver_wait.until{stale?(export_all_link)} if export_all_link
209
+ wait_for(TRANSACTIONS_SELECTORS[:export_all_link])
210
+ end
211
+
212
+ def export_csv
213
+ click(TRANSACTIONS_SELECTORS[:export_all_link])
214
+ driver_wait.until{driver.element_present?(*TRANSACTIONS_SELECTORS[:export_format_select_list].first)}
215
+ unless choose_option(find(TRANSACTIONS_SELECTORS[:export_format_select_list])){|text| text.include?('(CSV)')}
216
+ raise "Can't find the CSV export format."
56
217
  end
218
+ clicked_at = Time.now
219
+ click(TRANSACTIONS_SELECTORS[:download_button])
220
+ wait_for_download(since: clicked_at)
57
221
  end
58
222
  end
59
223
  end
@@ -0,0 +1,18 @@
1
+ # BoqComAu/Transactions.rb
2
+ # BoqComAu::Transactions
3
+
4
+ require_relative './Account'
5
+
6
+ module BoqComAu
7
+ module Transactions
8
+ class << self
9
+ # Returns the name of the CSV file downloaded.
10
+ def download_csv_file(account_number:, period: nil, from_date: nil, to_date: nil, **account_args)
11
+ boq_account = BoqComAu::Account.new(**account_args)
12
+ boq_account.download_transactions(account_number: account_number, period: period, from_date: from_date, to_date: to_date)
13
+ ensure
14
+ boq_account&.shutdown
15
+ end
16
+ end # class << self
17
+ end
18
+ end
@@ -2,5 +2,5 @@
2
2
  # BoqComAu::VERSION
3
3
 
4
4
  module BoqComAu
5
- VERSION = '0.0.3'
5
+ VERSION = '0.2.0'
6
6
  end
data/lib/boq_com_au.rb CHANGED
@@ -2,4 +2,5 @@
2
2
  # BoqComAu
3
3
 
4
4
  require_relative './BoqComAu/Account'
5
+ require_relative './BoqComAu/Transactions'
5
6
  require_relative './BoqComAu/VERSION'
@@ -1,14 +1,78 @@
1
1
  # test/BoqComAu/Account_test.rb
2
2
 
3
3
  # Notes:
4
- # 1. No browser and no BOQ: only what doesn't depend on the site is tested.
4
+ # 1. No browser and no BOQ: only what doesn't depend on the site is tested. Every account which might reach for its browser is given a stand-in, so as none is started.
5
5
 
6
6
  require_relative '../../lib/boq_com_au'
7
7
 
8
+ require 'date'
8
9
  require 'minitest/autorun'
9
10
  require 'minitest-spec-context'
11
+ require 'tmpdir'
10
12
 
11
13
  describe BoqComAu::Account do
14
+ def stand_in_element(text: '', displayed: true, id: nil)
15
+ element = Object.new
16
+ element.define_singleton_method(:text){text}
17
+ element.define_singleton_method(:displayed?){displayed}
18
+ element.define_singleton_method(:attribute){|name| id if name == 'id'}
19
+ element.define_singleton_method(:click){@clicked = true}
20
+ element.define_singleton_method(:clicked?){!!@clicked}
21
+ element
22
+ end
23
+
24
+ # What Chosen draws for a hidden select: <select id>_chosen, with a.chosen-single to open it and li.active-result to choose from.
25
+ def stand_in_chosen(*texts)
26
+ opener = stand_in_element
27
+ options = texts.map{|text| stand_in_element(text: text)}
28
+ chosen = Object.new
29
+ chosen.define_singleton_method(:find_element){|*| opener}
30
+ chosen.define_singleton_method(:find_elements){|*| options}
31
+ [chosen, opener, options]
32
+ end
33
+
34
+ # Goes stale, as a link does when the page redraws it, once stale! is called.
35
+ def stand_in_link
36
+ link = stand_in_element
37
+ link.define_singleton_method(:stale!){@stale = true}
38
+ link.define_singleton_method(:displayed?){@stale ? raise(Selenium::WebDriver::Error::StaleElementReferenceError) : true}
39
+ link
40
+ end
41
+
42
+ # Finds the elements by id given, and otherwise those given in elements; though only after the number of looks given in drawn_after, as for a list Chosen hasn't drawn yet.
43
+ def stand_in_driver(elements_by_id: {}, elements: [], drawn_after: 0)
44
+ driver = Object.new
45
+ looks = 0
46
+ driver.define_singleton_method(:attempt){|&block| block.call(self)}
47
+ driver.define_singleton_method(:find_elements){|*, **by| (looks += 1) > drawn_after ? (by[:id] ? [elements_by_id[by[:id]]].compact : elements) : []}
48
+ driver.define_singleton_method(:element_present?){|*| true}
49
+ driver.define_singleton_method(:execute_script){|script, *args| (@scripts ||= []) << [script, *args]}
50
+ driver.define_singleton_method(:scripts){@scripts || []}
51
+ driver
52
+ end
53
+
54
+ def account_with_driver(driver, **args)
55
+ account = BoqComAu::Account.new(**args)
56
+ account.instance_variable_set(:@driver, driver)
57
+ account.instance_variable_set(:@logged_in, true)
58
+ account
59
+ end
60
+
61
+ # An account whose account list is a hidden select drawn by Chosen, as BOQ's is.
62
+ def account_with_accounts(*texts, drawn_after: 0)
63
+ chosen, opener, options = stand_in_chosen(*texts)
64
+ select_list = stand_in_element(displayed: false, id: 'id71')
65
+ account = account_with_driver(stand_in_driver(elements_by_id: {'id71_chosen' => chosen}, drawn_after: drawn_after))
66
+ account.define_singleton_method(:find){|*| select_list}
67
+ account.define_singleton_method(:wait_for){|*| true}
68
+ [account, opener, options]
69
+ end
70
+
71
+ def touch(filename, mtime)
72
+ File.write(filename, '')
73
+ File.utime(mtime, mtime, filename)
74
+ end
75
+
12
76
  describe "#username and #password" do
13
77
  it "are those given" do
14
78
  account = BoqComAu::Account.new(username: 'customer', password: 'secret')
@@ -34,6 +98,28 @@ describe BoqComAu::Account do
34
98
  end
35
99
  end
36
100
 
101
+ describe "#download_transactions" do
102
+ def account_recording_steps
103
+ account = account_with_driver(stand_in_driver)
104
+ steps = []
105
+ %i{get_transactions_page select_bank_account search export_csv}.each{|step| account.define_singleton_method(step){|*| steps << step}}
106
+ account.define_singleton_method(:enter_dates){|from_date:, to_date:| steps << [:enter_dates, from_date, to_date]}
107
+ [account, steps]
108
+ end
109
+
110
+ it "uses BOQ's own dates where neither a period nor a date is given" do
111
+ account, steps = account_recording_steps
112
+ account.download_transactions(account_number: '12345678')
113
+ _(steps).must_equal(%i{get_transactions_page select_bank_account export_csv})
114
+ end
115
+
116
+ it "sets the dates and searches on them before exporting where they're given" do
117
+ account, steps = account_recording_steps
118
+ account.download_transactions(account_number: '12345678', from_date: '2026-10-01', to_date: '2026-10-31')
119
+ _(steps).must_equal([:get_transactions_page, :select_bank_account, [:enter_dates, '2026-10-01', '2026-10-31'], :search, :export_csv])
120
+ end
121
+ end
122
+
37
123
  describe "#default_driver_options" do
38
124
  it "masks Chrome's automation flags, leaving the profile to Chrome where none is given" do
39
125
  options = BoqComAu::Account.new.send(:default_driver_options)
@@ -47,8 +133,193 @@ describe BoqComAu::Account do
47
133
  _(options.args).must_include("--user-data-dir=#{File.expand_path('~/profiles/boq')}")
48
134
  end
49
135
 
136
+ it "downloads into the download directory without asking, opening nothing" do
137
+ options = BoqComAu::Account.new(download_directory: '~/statements').send(:default_driver_options)
138
+ download = options.prefs[:download]
139
+ _(download[:default_directory]).must_equal(File.expand_path('~/statements'))
140
+ _(download[:prompt_for_download]).must_equal(false)
141
+ _(download[:extensions_to_open]).must_equal('')
142
+ end
143
+
144
+ it "downloads into ~/Downloads where no directory is given" do
145
+ _(BoqComAu::Account.new.download_directory).must_equal(File.expand_path('~/Downloads'))
146
+ end
147
+
50
148
  it "is nil for browsers other than Chrome" do
51
149
  _(BoqComAu::Account.new(browser: :firefox).send(:default_driver_options)).must_be_nil
52
150
  end
53
151
  end
152
+
153
+ describe "#click" do
154
+ it "finds the element afresh where the one found first has been redrawn" do
155
+ old_link, new_link = stand_in_link, stand_in_link
156
+ old_link.stale!
157
+ driver = stand_in_driver
158
+ attempts = 0
159
+ driver.define_singleton_method(:attempt) do |&block|
160
+ block.call(self)
161
+ rescue Selenium::WebDriver::Error::StaleElementReferenceError
162
+ attempts += 1
163
+ retry if attempts < 3
164
+ raise
165
+ end
166
+ account = account_with_driver(driver)
167
+ links = [old_link, new_link]
168
+ account.define_singleton_method(:find){|*| links.shift}
169
+ account.send(:click, {xpath: '//a'})
170
+ _(new_link.clicked?).must_equal(true)
171
+ end
172
+ end
173
+
174
+ describe "#dates" do
175
+ def dates(**args)
176
+ BoqComAu::Account.new.send(:dates, **{period: nil, from_date: nil, to_date: nil}.merge(args))
177
+ end
178
+
179
+ it "is the last year for :all" do
180
+ _(dates(period: :all)).must_equal([Date.today.prev_year, Date.today])
181
+ end
182
+
183
+ it "is last month for :last_month" do
184
+ today = Date.today
185
+ _(dates(period: :last_month)).must_equal([Date.new(today.prev_month.year, today.prev_month.month, 1), Date.new(today.year, today.month, 1) - 1])
186
+ end
187
+
188
+ it "is the dates given, defaulting the other to a year ago or today" do
189
+ _(dates(from_date: '2026-01-01', to_date: '2026-02-01')).must_equal(['2026-01-01', '2026-02-01'])
190
+ _(dates(from_date: '2026-01-01')).must_equal(['2026-01-01', Date.today])
191
+ _(dates(to_date: '2026-02-01')).must_equal([Date.today.prev_year, '2026-02-01'])
192
+ end
193
+
194
+ it "is none where neither a period nor a date is given" do
195
+ _(dates).must_equal([nil, nil])
196
+ end
197
+
198
+ it "refuses a period it doesn't know" do
199
+ _{dates(period: :fortnight)}.must_raise(ArgumentError)
200
+ end
201
+ end
202
+
203
+ describe "#formatted_date" do
204
+ it "is day/month/year, from a Date or a String" do
205
+ account = BoqComAu::Account.new
206
+ _(account.send(:formatted_date, Date.new(2026, 3, 4))).must_equal('04/03/2026')
207
+ _(account.send(:formatted_date, '2026-03-04')).must_equal('04/03/2026')
208
+ end
209
+ end
210
+
211
+ describe "#newest_csv_filename" do
212
+ it "is the newest CSV file in the download directory since the time given" do
213
+ Dir.mktmpdir do |directory|
214
+ since = Time.now - 60
215
+ touch(File.join(directory, 'old.csv'), since - 60)
216
+ touch(File.join(directory, 'new.csv'), since + 10)
217
+ touch(File.join(directory, 'newer.csv'), since + 20)
218
+ touch(File.join(directory, 'newest.csv.crdownload'), since + 30)
219
+ account = BoqComAu::Account.new(download_directory: directory)
220
+ _(account.send(:newest_csv_filename, since: since)).must_equal(File.join(directory, 'newer.csv'))
221
+ end
222
+ end
223
+
224
+ it "is nil where none has appeared since" do
225
+ Dir.mktmpdir do |directory|
226
+ since = Time.now
227
+ touch(File.join(directory, 'old.csv'), since - 60)
228
+ _(BoqComAu::Account.new(download_directory: directory).send(:newest_csv_filename, since: since)).must_be_nil
229
+ end
230
+ end
231
+ end
232
+
233
+ describe "#get_transactions_page" do
234
+ it "clicks the history link by JavaScript, the link being in a menu which is closed" do
235
+ driver = stand_in_driver
236
+ link = stand_in_element(displayed: false)
237
+ account = account_with_driver(driver)
238
+ account.define_singleton_method(:find){|*| link}
239
+ account.send(:get_transactions_page)
240
+ _(driver.scripts).must_equal([['arguments[0].click();', link]])
241
+ _(link.clicked?).must_equal(false)
242
+ end
243
+ end
244
+
245
+ describe "#select_bank_account" do
246
+ it "opens the account list and picks the account by the digits of its number, however either is written" do
247
+ account, opener, options = account_with_accounts('Everyday 1111 2222', 'Saver 3333-4444')
248
+ account.send(:select_bank_account, '33334444')
249
+ _(opener.clicked?).must_equal(true)
250
+ _(options.map(&:clicked?)).must_equal([false, true])
251
+ end
252
+
253
+ it "waits for Chosen to draw the list where it hasn't yet" do
254
+ account, opener, options = account_with_accounts('Everyday 1111 2222', drawn_after: 2)
255
+ account.send(:select_bank_account, '11112222')
256
+ _(opener.clicked?).must_equal(true)
257
+ _(options.map(&:clicked?)).must_equal([true])
258
+ end
259
+
260
+ it "says which account it couldn't find" do
261
+ account, _opener, _options = account_with_accounts('Everyday 1111 2222')
262
+ error = _{account.send(:select_bank_account, '9999')}.must_raise(RuntimeError)
263
+ _(error.message).must_include('9999')
264
+ end
265
+
266
+ it "refuses an account number without digits, which would match every account" do
267
+ account, _opener, options = account_with_accounts('Everyday 1111 2222')
268
+ _{account.send(:select_bank_account, '...')}.must_raise(ArgumentError)
269
+ _(options.map(&:clicked?)).must_equal([false])
270
+ end
271
+ end
272
+
273
+ describe "#enter_dates" do
274
+ def stand_in_date_field(value, displayed: true)
275
+ field = Object.new
276
+ field.instance_variable_set(:@value, value)
277
+ field.define_singleton_method(:displayed?){displayed}
278
+ field.define_singleton_method(:attribute){|name| @value if name == 'value'}
279
+ field.define_singleton_method(:value=){|value| @value = value}
280
+ field
281
+ end
282
+
283
+ # A driver whose set_value() sets the field, or, where the page throws the value away, doesn't.
284
+ def account_with_date_fields(fields, taking: true)
285
+ driver = stand_in_driver(elements: fields)
286
+ driver.define_singleton_method(:execute_script){|script, element = nil, value = nil| element.value = value if taking && element.respond_to?(:value=)}
287
+ account = account_with_driver(driver)
288
+ account.define_singleton_method(:click){|*| true}
289
+ account
290
+ end
291
+
292
+ it "sets the displayed date fields, leaving the hidden ones of the form before it was redrawn" do
293
+ hidden_from, hidden_to = stand_in_date_field('28/10/2026', displayed: false), stand_in_date_field('03/11/2026', displayed: false)
294
+ from, to = stand_in_date_field('28/10/2026'), stand_in_date_field('03/11/2026')
295
+ account = account_with_date_fields([hidden_from, hidden_to, from, to])
296
+ account.send(:enter_dates, from_date: Date.new(2026, 10, 1), to_date: Date.new(2026, 10, 31))
297
+ _([from, to].map{|field| field.attribute('value')}).must_equal(['01/10/2026', '31/10/2026'])
298
+ _([hidden_from, hidden_to].map{|field| field.attribute('value')}).must_equal(['28/10/2026', '03/11/2026'])
299
+ end
300
+
301
+ it "says so where the dates didn't take, rather than searching another range" do
302
+ account = account_with_date_fields([stand_in_date_field('28/10/2026'), stand_in_date_field('03/11/2026')], taking: false)
303
+ error = _{account.send(:enter_dates, from_date: Date.new(2026, 10, 1), to_date: Date.new(2026, 10, 31))}.must_raise(RuntimeError)
304
+ _(error.message).must_include('01/10/2026 to 31/10/2026')
305
+ end
306
+ end
307
+
308
+ describe "#search" do
309
+ it "waits for the results to replace the Export All link that was there before the search" do
310
+ old_export_all_link = stand_in_link
311
+ account = account_with_driver(stand_in_driver(elements: [old_export_all_link]))
312
+ account.define_singleton_method(:click){|*| old_export_all_link.stale!}
313
+ account.define_singleton_method(:wait_for){|*| true}
314
+ account.send(:search)
315
+ _(account.send(:stale?, old_export_all_link)).must_equal(true)
316
+ end
317
+
318
+ it "doesn't wait to see a link replaced where there was none" do
319
+ account = account_with_driver(stand_in_driver(elements: []))
320
+ account.define_singleton_method(:click){|*| true}
321
+ account.define_singleton_method(:wait_for){|*| true}
322
+ _(account.send(:search)).must_equal(true)
323
+ end
324
+ end
54
325
  end
@@ -0,0 +1,43 @@
1
+ # test/BoqComAu/Transactions_test.rb
2
+
3
+ # Notes:
4
+ # 1. BoqComAu::Account.new is swapped for a stand-in for the length of each example and put back afterwards, so as no browser is started.
5
+
6
+ require_relative '../../lib/boq_com_au'
7
+
8
+ require 'minitest/autorun'
9
+ require 'minitest-spec-context'
10
+
11
+ describe BoqComAu::Transactions do
12
+ def with_stand_in_account(download: ->{'/downloads/transactions.csv'})
13
+ account = Object.new
14
+ account.define_singleton_method(:download_transactions){|account_number:, **dates| (@asked ||= []) << [account_number, dates]; download.call}
15
+ account.define_singleton_method(:asked){@asked}
16
+ account.define_singleton_method(:shutdown){@shut_down = true}
17
+ account.define_singleton_method(:shut_down?){!!@shut_down}
18
+ arguments = []
19
+ original = BoqComAu::Account.method(:new)
20
+ BoqComAu::Account.define_singleton_method(:new){|**args| arguments << args; account}
21
+ yield account, arguments
22
+ ensure
23
+ BoqComAu::Account.define_singleton_method(:new, original)
24
+ end
25
+
26
+ describe ".download_csv_file" do
27
+ it "is the file downloaded, for the account and period given, the other arguments going to the account, which is shut down" do
28
+ with_stand_in_account do |account, arguments|
29
+ _(BoqComAu::Transactions.download_csv_file(account_number: '12345678', period: :last_month, download_directory: '/downloads')).must_equal('/downloads/transactions.csv')
30
+ _(account.asked).must_equal([['12345678', {period: :last_month, from_date: nil, to_date: nil}]])
31
+ _(arguments).must_equal([{download_directory: '/downloads'}])
32
+ _(account.shut_down?).must_equal(true)
33
+ end
34
+ end
35
+
36
+ it "shuts the account down even where the download fails" do
37
+ with_stand_in_account(download: ->{raise Selenium::WebDriver::Error::TimeoutError}) do |account, _arguments|
38
+ _{BoqComAu::Transactions.download_csv_file(account_number: '12345678')}.must_raise(Selenium::WebDriver::Error::TimeoutError)
39
+ _(account.shut_down?).must_equal(true)
40
+ end
41
+ end
42
+ end
43
+ end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: boq_com_au
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.3
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - thoran
@@ -80,7 +80,7 @@ dependencies:
80
80
  - !ruby/object:Gem::Version
81
81
  version: '0'
82
82
  description: Log into BOQ Classic Internet Banking with a Customer Access Number and
83
- password.
83
+ password, and export an account's transactions as a CSV file.
84
84
  email: code@thoran.com
85
85
  executables: []
86
86
  extensions: []
@@ -93,9 +93,11 @@ files:
93
93
  - Rakefile
94
94
  - boq_com_au.gemspec
95
95
  - lib/BoqComAu/Account.rb
96
+ - lib/BoqComAu/Transactions.rb
96
97
  - lib/BoqComAu/VERSION.rb
97
98
  - lib/boq_com_au.rb
98
99
  - test/BoqComAu/Account_test.rb
100
+ - test/BoqComAu/Transactions_test.rb
99
101
  homepage: https://github.com/thoran/boq_com_au
100
102
  licenses:
101
103
  - MIT
@@ -116,5 +118,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
116
118
  requirements: []
117
119
  rubygems_version: 4.0.23
118
120
  specification_version: 4
119
- summary: Log into BOQ Classic Internet Banking via Selenium WebDriver.
121
+ summary: Download transactions from BOQ Classic Internet Banking via Selenium WebDriver.
120
122
  test_files: []