boq_com_au 0.1.0 → 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: 4ee1609019ff26e0055fe57d7e98bb43efcaa7708da26b4e3df98f310ecffb3a
4
- data.tar.gz: 14545bd78bf644f95d33a0df3e0794a3a58ac2c88c070a2341a22e3acf2a91a9
3
+ metadata.gz: 25b9fba8414050a29c7aba82c8f7e19df4ed098ece4345ec16002897fd3d8f10
4
+ data.tar.gz: 0e6053f79b2391dcccf6283100508c02b30b54155406663270bac28f32da58a4
5
5
  SHA512:
6
- metadata.gz: fdcf36437f2ce71868d7b4ce856b035b103f180fc517d3cd3e51b50bdba59db0bad95fcf7a36b2dde86562ef397fcdd352b182a62390b6b50950452b69a2c511
7
- data.tar.gz: 9a95829cdd54d422172206b69f0a869191a046ea7b6472fc23f89b655253baa0a64640fa1f373a6fbc5378b7c78e6d328afa3e8bb801ccfca085226b58ff3096
6
+ metadata.gz: 3fcf4ff2fb9ecfe8eb73d7cc5751202c4c16f4fd3876f3b448616477f2cc0719cf6b5151c67960ecd3ec9b2a1e18cc1c82472f484376565f68fcf87b84a98782
7
+ data.tar.gz: be41871305543362742a9cd6d86e56cfa26a1d320e4a624be742af293d4c5d417fc2d4202302926fec37d3725803e8bd572f07c882fe87c79e5daf292144f64d
data/CHANGELOG CHANGED
@@ -1,5 +1,21 @@
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
 
5
21
  0.1.0: + BoqComAu::Account#download_transactions, exporting an account's transactions as a CSV file.
data/README.md CHANGED
@@ -33,15 +33,23 @@ $ gem install boq_com_au
33
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 those BOQ shows on choosing it, exported with Export All as Comma Delimited Format (CSV).
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.
37
45
 
38
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.
39
47
 
40
48
  Or in one step, logging in, downloading, and shutting down even where the download fails:
41
49
  ```ruby
42
- BoqComAu::Transactions.download_csv_file(account_number: '12345678')
50
+ BoqComAu::Transactions.download_csv_file(account_number: '12345678', period: :last_month)
43
51
  ```
44
- Any other keyword arguments are passed to `BoqComAu::Account.new`.
52
+ It takes `period:`, `from_date:` and `to_date:` as `download_transactions` does. Any other keyword arguments are passed to `BoqComAu::Account.new`.
45
53
 
46
54
  ### Credentials
47
55
 
@@ -70,8 +78,6 @@ Where BOQ asks for a one-time code after logging on, `login` waits up to 30 seco
70
78
 
71
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.
72
80
 
73
- The date range is BOQ's own, as shown on choosing the account; it can't yet be chosen.
74
-
75
81
  The tests cover only what doesn't depend on BOQ's site.
76
82
 
77
83
  ## Contributing
@@ -10,7 +10,9 @@
10
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
11
  # 7. A username or password not given stops login, saying which is missing.
12
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.
13
14
 
15
+ require 'date'
14
16
  require 'webaccount'
15
17
 
16
18
  module BoqComAu
@@ -27,6 +29,9 @@ module BoqComAu
27
29
  TRANSACTIONS_SELECTORS = {
28
30
  transaction_history_link: {xpath: '//a[normalize-space()="Transaction History"]'},
29
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"]'},
30
35
  export_all_link: {xpath: '//a[normalize-space()="Export All"]'},
31
36
  export_format_select_list: {xpath: '//select[option[contains(., "Comma Delimited Format (CSV)")]]'},
32
37
  download_button: {xpath: '//*[self::a or self::button][normalize-space()="Download"] | //input[@value="Download"]'}
@@ -41,10 +46,15 @@ module BoqComAu
41
46
  @password || raise("No password: it's given as password:.")
42
47
  end
43
48
 
44
- # Returns the name of the CSV file downloaded.
45
- def download_transactions(account_number:)
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)
46
52
  get_transactions_page
47
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
48
58
  export_csv
49
59
  end
50
60
 
@@ -88,10 +98,22 @@ module BoqComAu
88
98
  end
89
99
  end
90
100
 
101
+ def stale?(element)
102
+ element.displayed?
103
+ false
104
+ rescue Selenium::WebDriver::Error::StaleElementReferenceError
105
+ true
106
+ end
107
+
91
108
  def wait_for(selector)
92
109
  driver_wait.until{driver.find_elements(*selector.first).any?(&:displayed?)}
93
110
  end
94
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
+
95
117
  def chosen_list(select_element)
96
118
  driver.find_elements(id: "#{select_element.attribute('id')}_chosen").first
97
119
  end
@@ -110,6 +132,31 @@ module BoqComAu
110
132
  option
111
133
  end
112
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
+
113
160
  # downloads
114
161
 
115
162
  def newest_csv_filename(since:)
@@ -137,6 +184,31 @@ module BoqComAu
137
184
  wait_for(TRANSACTIONS_SELECTORS[:export_all_link])
138
185
  end
139
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
+
140
212
  def export_csv
141
213
  click(TRANSACTIONS_SELECTORS[:export_all_link])
142
214
  driver_wait.until{driver.element_present?(*TRANSACTIONS_SELECTORS[:export_format_select_list].first)}
@@ -7,9 +7,9 @@ module BoqComAu
7
7
  module Transactions
8
8
  class << self
9
9
  # Returns the name of the CSV file downloaded.
10
- def download_csv_file(account_number:, **account_args)
10
+ def download_csv_file(account_number:, period: nil, from_date: nil, to_date: nil, **account_args)
11
11
  boq_account = BoqComAu::Account.new(**account_args)
12
- boq_account.download_transactions(account_number: account_number)
12
+ boq_account.download_transactions(account_number: account_number, period: period, from_date: from_date, to_date: to_date)
13
13
  ensure
14
14
  boq_account&.shutdown
15
15
  end
@@ -2,5 +2,5 @@
2
2
  # BoqComAu::VERSION
3
3
 
4
4
  module BoqComAu
5
- VERSION = '0.1.0'
5
+ VERSION = '0.2.0'
6
6
  end
@@ -5,6 +5,7 @@
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'
10
11
  require 'tmpdir'
@@ -38,12 +39,12 @@ describe BoqComAu::Account do
38
39
  link
39
40
  end
40
41
 
41
- # Finds the elements by id given, though only after the number of looks given in drawn_after, as for a list Chosen hasn't drawn yet.
42
- def stand_in_driver(elements_by_id: {}, drawn_after: 0)
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)
43
44
  driver = Object.new
44
45
  looks = 0
45
46
  driver.define_singleton_method(:attempt){|&block| block.call(self)}
46
- driver.define_singleton_method(:find_elements){|*, **by| (looks += 1) > drawn_after ? [elements_by_id[by[:id]]].compact : []}
47
+ driver.define_singleton_method(:find_elements){|*, **by| (looks += 1) > drawn_after ? (by[:id] ? [elements_by_id[by[:id]]].compact : elements) : []}
47
48
  driver.define_singleton_method(:element_present?){|*| true}
48
49
  driver.define_singleton_method(:execute_script){|script, *args| (@scripts ||= []) << [script, *args]}
49
50
  driver.define_singleton_method(:scripts){@scripts || []}
@@ -97,6 +98,28 @@ describe BoqComAu::Account do
97
98
  end
98
99
  end
99
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
+
100
123
  describe "#default_driver_options" do
101
124
  it "masks Chrome's automation flags, leaving the profile to Chrome where none is given" do
102
125
  options = BoqComAu::Account.new.send(:default_driver_options)
@@ -148,6 +171,43 @@ describe BoqComAu::Account do
148
171
  end
149
172
  end
150
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
+
151
211
  describe "#newest_csv_filename" do
152
212
  it "is the newest CSV file in the download directory since the time given" do
153
213
  Dir.mktmpdir do |directory|
@@ -209,4 +269,57 @@ describe BoqComAu::Account do
209
269
  _(options.map(&:clicked?)).must_equal([false])
210
270
  end
211
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
212
325
  end
@@ -11,7 +11,7 @@ require 'minitest-spec-context'
11
11
  describe BoqComAu::Transactions do
12
12
  def with_stand_in_account(download: ->{'/downloads/transactions.csv'})
13
13
  account = Object.new
14
- account.define_singleton_method(:download_transactions){|account_number:| (@asked ||= []) << account_number; download.call}
14
+ account.define_singleton_method(:download_transactions){|account_number:, **dates| (@asked ||= []) << [account_number, dates]; download.call}
15
15
  account.define_singleton_method(:asked){@asked}
16
16
  account.define_singleton_method(:shutdown){@shut_down = true}
17
17
  account.define_singleton_method(:shut_down?){!!@shut_down}
@@ -24,10 +24,10 @@ describe BoqComAu::Transactions do
24
24
  end
25
25
 
26
26
  describe ".download_csv_file" do
27
- it "is the file downloaded, for the account given, the other arguments going to the account, which is shut down" 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
28
  with_stand_in_account do |account, arguments|
29
- _(BoqComAu::Transactions.download_csv_file(account_number: '12345678', download_directory: '/downloads')).must_equal('/downloads/transactions.csv')
30
- _(account.asked).must_equal(['12345678'])
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
31
  _(arguments).must_equal([{download_directory: '/downloads'}])
32
32
  _(account.shut_down?).must_equal(true)
33
33
  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.1.0
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - thoran