add launch_window function, release 2.2.3

CHANGELOG.md

@@ -1,3 +1,7 @@
+## [2.2.3]
+
+- Add `launch_window` function to launch browser in headful mode
+
 ## [2.2.2] 2024-06-07
 
 This update brings basic utilities for integration testing and some conveniences in the high level `chrobot` module

README.md

@@ -50,19 +50,24 @@ Install as an Elixir dependency with mix
 # in your mix.exs
 defp deps do
   [
-    {:chrobot, "~> 2.2.2", app: false, manager: :rebar3}
+    {:chrobot, "~> 2.2.3", app: false, manager: :rebar3}
   ]
 end
 ```
 
 ### Browser
 
+#### System Installation
+
 Chrobot can use an existing system installation of Google Chrome or Chromium, if you already have one.
 
-Chrobot also comes with a simple utility to install a version of [Google Chrome for Testing](https://github.com/GoogleChromeLabs/chrome-for-testing) directly inside your project.
+
+#### Browser Install Tool
+
+Chrobot comes with a simple utility to install a version of [Google Chrome for Testing](https://github.com/GoogleChromeLabs/chrome-for-testing) directly inside your project.
 Chrobot will automatically pick up this local installation when started via the `launch` command, and will prioritise it over a system installation of Google Chrome.
 
-You can run the browser installer utility from gleam like so:
+You can run the browser installer tool from gleam like so:
 
 ```sh
 gleam run -m browser_install
@@ -76,6 +81,25 @@ mix run -e :browser_install.main
 
 Please [check the `install` docs for more information](https://hexdocs.pm/chrobot/browser_install.html) – this installation method will not work everywhere and comes with some caveats!
 
+#### GitHub Actions
+
+If you want to use chrobot inside a Github Action, for example to run integration tests, 
+you can use the [setup-chrome](https://github.com/browser-actions/setup-chrome) action to get a Chrome installation, like so:
+
+```yml
+# -- snip --
+- uses: browser-actions/setup-chrome@v1
+  id: setup-chrome
+- run: |
+    ${{ steps.setup-chrome.outputs.chrome-path }} --version
+- run: gleam deps download
+- run: gleam test
+  env:
+    CHROBOT_BROWSER_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+```
+
+If you are using `launch` to start chrobot, it should pick up the Chrome executable from `CHROBOT_BROWSER_PATH`.
+
 ## Examples
 
 ### Take a screenshot of a website

gleam.toml

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

src/chrobot.gleam

@@ -90,6 +90,25 @@ pub fn launch() {
   }
 }
 
+/// Like [`launch`](#launch), but launches the browser with a visible window, not
+/// in headless mode, which is useful for debugging and development.  
+pub fn launch_window() {
+  let launch_result = validate_launch(chrome.launch_window())
+
+  // Some helpful logging for when the browser could not be found
+  case launch_result {
+    Error(chrome.CouldNotFindExecutable) -> {
+      utils.err("Chrobot could not find a chrome executable to launch!\n")
+      utils.hint(
+        "You can install a local version of chrome for testing with this command:",
+      )
+      utils.show_cmd("gleam run -m browser_install")
+      launch_result
+    }
+    other -> other
+  }
+}
+
 /// Launch a browser with the given configuration,
 /// to populate the arguments, use [`chrome.get_default_chrome_args`](/chrobot/chrome.html#get_default_chrome_args).
 /// This function will validate that the browser launched successfully, and the 

src/chrome.gleam

@@ -30,7 +30,7 @@ import gleam/string
 import gleam/string_builder as sb
 import simplifile as file
 
-const default_timeout: Int = 10_000
+pub const default_timeout: Int = 10_000
 
 // --- PUBLIC API ---
 
@@ -187,6 +187,56 @@ pub fn launch() -> Result(Subject(Message), LaunchError) {
   }
 }
 
+/// Like [`launch`](#launch), but launches the browser with a visible window, not
+/// in headless mode, which is useful for debugging and development.  
+pub fn launch_window() {
+  case resolve_env_cofig() {
+    Ok(env_config) -> {
+      // Env config vars are set, use them
+      utils.info(
+        "Launching windowed browser using config provided through environment variables",
+      )
+      launch_with_config(BrowserConfig(
+        path: env_config.path,
+        args: env_config.args
+          |> list.filter(fn(arg) {
+            case arg {
+              "--headless" -> False
+              _ -> True
+            }
+          }),
+        start_timeout: env_config.start_timeout,
+        log_level: env_config.log_level,
+      ))
+    }
+    Error(_) -> {
+      // Try local first, then a system installation
+      use resolved_chrome_path <- result.try(result.lazy_or(
+        get_local_chrome_path(),
+        get_system_chrome_path,
+      ))
+      // I think logging this is important to avoid confusion
+      utils.info(
+        "Launching windowed browser from dynamically resolved path: \""
+        <> resolved_chrome_path
+        <> "\"",
+      )
+      launch_with_config(BrowserConfig(
+        path: resolved_chrome_path,
+        args: get_default_chrome_args()
+          |> list.filter(fn(arg) {
+            case arg {
+              "--headless" -> False
+              _ -> True
+            }
+          }),
+        start_timeout: default_timeout,
+        log_level: LogLevelWarnings,
+      ))
+    }
+  }
+}
+
 /// Launch a browser, and read the configuration from environment variables.
 /// The browser path variable must be set, all others will fall back to a default.
 /// 
@@ -971,7 +1021,8 @@ fn get_first_existing_path(paths: List(String)) -> Result(String, LaunchError) {
   }
 }
 
-fn resolve_env_cofig() -> Result(BrowserConfig, Nil) {
+@internal
+pub fn resolve_env_cofig() -> Result(BrowserConfig, Nil) {
   use path <- result.try(os.get_env("CHROBOT_BROWSER_PATH"))
   let args = case os.get_env("CHROBOT_BROWSER_ARGS") {
     Ok(args_string) -> string.split(args_string, "\n")