Accurate Polling

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [2.2.3] Unreleased
+
+- Implement more accurate polling
+- Make `poll` function part of the public `chrobot` API
+
 ## [2.2.3] 2024-06-08
 
 - Add `launch_window` function to launch browser in headful mode

gleam.toml

@@ -1,5 +1,5 @@
 name = "chrobot"
-version = "2.2.3"
+version = "2.2.4"
 
 description = "A browser automation tool and interface to the Chrome DevTools Protocol."
 licences = ["MIT"]

src/chrobot.gleam

@@ -35,6 +35,7 @@ import gleam/erlang/process.{type Subject}
 import gleam/json
 import gleam/list
 import gleam/option.{type Option, None, Some}
+import gleam/otp/task
 import gleam/result
 import gleam/string
 import protocol
@@ -762,21 +763,54 @@ pub fn defer_quit(browser: Subject(chrome.Message), body) {
 }
 
 // ---- UTILS
-const poll_interval = 100
-
-// TODO measure time elapsed during function call and take it into account
-/// Periodically try to call the function until it returns a 
-/// result instead of an error.
-/// Note: doesn't handle elapsed time during function call attempt yet
-fn poll(callback: fn() -> Result(a, b), remaining_time: Int) -> Result(a, b) {
- case callback() {
- Ok(a) -> Ok(a)
- Error(b) if remaining_time <= 0 -> {
- Error(b)
+const poll_delay = 5
+
+/// Utility to repeatedly call a browser function until it succeeds or times out.
+pub fn poll(
+ callback: fn() -> Result(a, chrome.RequestError),
+ timeout: Int,
+) -> Result(a, chrome.RequestError) {
+ let deadline = utils.get_time_ms() + timeout
+ do_poll(callback, deadline, None)
+}
+
+fn do_poll(
+ callback: fn() -> Result(a, chrome.RequestError),
+ deadline: Int,
+ previous_error: Option(chrome.RequestError),
+) -> Result(a, chrome.RequestError) {
+ // available time before current polling attempt
+ let available_time = deadline - utils.get_time_ms()
+
+ let result =
+ callback
+ |> task.async()
+ |> task.try_await(available_time)
+
+ // remaining available time after the polling attempt finishes
+ let available_time = deadline - utils.get_time_ms() - poll_delay
+
+ case result {
+ // Task did not return before deadline
+ // A task exit should never happen but we consider it a timeout
+ Error(task.Timeout) | Error(task.Exit(_)) -> {
+ // We return the error from the last failed poll attempt if there was one
+ case previous_error {
+ Some(err) -> Error(err)
+ None -> Error(chrome.ChromeAgentTimeout)
+ }
+ }
+ // Task returned Ok result, polling is done 
+ // and result is returned
+ Ok(Ok(res)) -> Ok(res)
+ // Task returned an error and we still have time, we continue polling with delay
+ Ok(Error(err)) if available_time > 0 -> {
+ process.sleep(poll_delay)
+ do_poll(callback, deadline, Some(err))
  }
- Error(_) -> {
-  process.sleep(poll_interval)
- poll(callback, remaining_time - poll_interval)
+ // Task returned an error but the time is up
+ Ok(Error(err)) -> {
+ Error(err)
  }
  }
 }

src/chrobot/internal/utils.gleam

@@ -196,3 +196,6 @@ pub fn try_call_with_subject(
  Ok(res) -> res
  }
 }
+
+@external(erlang, "chrobot_ffi", "get_time_ms")
+pub fn get_time_ms() -> Int

src/chrobot_ffi.erl

@@ -1,13 +1,14 @@
 -module(chrobot_ffi).
 -include_lib("kernel/include/file.hrl").
--export([open_browser_port/2, send_to_port/2, get_arch/0, unzip/2, set_executable/1, run_command/1]).
+-export([open_browser_port/2, send_to_port/2, get_arch/0, unzip/2, set_executable/1, run_command/1, get_time_ms/0]).
 
 % ---------------------------------------------------
 % RUNTIME
 % ---------------------------------------------------
 
 % FFI to interact with the browser via a port from erlang
 % since gleam does not really support ports yet.
+% module: chrome.gleam
 
 % The port is opened with the option "nouse_stdio"
 % which makes it use file descriptors 3 and 4 for stdin and stdout
@@ -37,6 +38,7 @@ send_to_port(Port, BinaryString) ->
 % ---------------------------------------------------
 
 % Utils for the installer script
+% module: browser_install.gleam
 
 % Get the architecture of the system
 get_arch() ->
@@ -75,3 +77,13 @@ set_executable(FilePath) ->
  {error, Reason} ->
  {error, Reason}
  end.
+
+% ---------------------------------------------------
+% UTILITIES
+% ---------------------------------------------------
+
+% Miscelaneous utilities
+% module: chrobot/internal/utils.gleam
+
+get_time_ms() ->
+ os:system_time(millisecond).

test/chrobot_test.gleam

@@ -3,6 +3,7 @@ import chrobot
 import chrobot/internal/utils
 import chrome
 import gleam/dynamic
+import gleam/erlang/process
 import gleam/io
 import gleam/list
 import gleam/result
@@ -297,3 +298,77 @@ pub fn press_key_test() {
  |> should.be_ok
  |> should.equal("ENTER KEY PRESSED")
 }
+
+pub fn poll_test() {
+ let initial_time = utils.get_time_ms()
+
+ // this function will start returning "Success" in 200ms
+ let poll_function = fn() {
+ case utils.get_time_ms() - initial_time {
+ time if time > 200 -> Ok("Success")
+ _ -> Error(chrome.NotFoundError)
+ }
+ }
+
+ chrobot.poll(poll_function, 500)
+ |> should.be_ok()
+ |> should.equal("Success")
+}
+
+pub fn poll_failure_test() {
+ let initial_time = utils.get_time_ms()
+
+ // this function will start returning "Success" in 200ms
+ let poll_function = fn() {
+ case utils.get_time_ms() - initial_time {
+ time if time > 200 -> Ok("Success")
+ _ -> Error(chrome.NotFoundError)
+ }
+ }
+
+ case chrobot.poll(poll_function, 100) {
+ Error(chrome.NotFoundError) -> {
+ should.be_true(True)
+ let elapsed_time = utils.get_time_ms() - initial_time
+ // timeout should be within a 10ms window of accuracy
+ { elapsed_time < 105 && elapsed_time > 95 }
+ |> should.be_true()
+ }
+ _ -> {
+ utils.err("Polling function didn't return the correct error")
+ should.fail()
+ }
+ }
+}
+
+pub fn poll_timeout_failure_test() {
+ let initial_time = utils.get_time_ms()
+
+ // this function will return errors first
+ // and after 100ms it will start blocking for 10s
+ let poll_function = fn() {
+ case utils.get_time_ms() - initial_time {
+ time if time > 100 -> {
+ process.sleep(10_000)
+ Ok("Success")
+ }
+ _ -> Error(chrome.NotFoundError)
+ }
+ }
+
+ // the timeout is 300ms, so the polling function will be interrupted
+ // while it's blocking, it should still return the original error
+ case chrobot.poll(poll_function, 300) {
+ Error(chrome.NotFoundError) -> {
+ should.be_true(True)
+ let elapsed_time = utils.get_time_ms() - initial_time
+ // timeout should be within a 10ms window of accuracy
+ { elapsed_time < 305 && elapsed_time > 295 }
+ |> should.be_true()
+ }
+ _ -> {
+ utils.err("Polling function didn't return the correct error")
+ should.fail()
+ }
+ }
+}