feat: support ASTRAL_BIN_PATH

docs/pages/advanced/env_vars.md

@@ -0,0 +1,46 @@
+---
+title: Env vars
+description:
+index: 5
+---
+
+Astral lets you configure some of its behavior using environment variables.
+
+## `ASTRAL_QUIET_INSTALL`
+
+By default, if Astral needs to install a browser binary, it will print progress
+information to the console. You can disable this behavior by setting the
+`ASTRAL_QUIET_INSTALL` environment variable to `1`.
+
+If `CI` is set to `true`, Astral will assume `ASTRAL_QUIET_INSTALL`.
+
+## `ASTRAL_BIN_PATH`
+
+If you already installed a supported browser binary, you can force Astral to use
+it by setting the `ASTRAL_BIN_PATH` environment variable.
+
+The `getBinary()` function will then always return that path.
+
+This is especially useful in containerized environments where you might reuse an
+existing base image or pre-install the browser binary yourself.
+
+```dockerfile
+RUN apt-get install -y google-chrome-stable
+ENV ASTRAL_BIN_PATH=/usr/bin/google-chrome-stable
+```
+
+## `ASTRAL_BIN_ARGS`
+
+You may want to pass additional arguments to the browser binary when launching
+it without having to change your Astral `launch()` calls.
+
+It can be achieved by setting the `ASTRAL_BIN_ARGS` environment variable.
+Arguments passed via this variable will be appended to any arguments passed to
+the `launch()` function.
+
+This is especially useful in containerized environments where you might need to
+pass specific arguments to make the browser work properly.
+
+```dockerfile
+ENV ASTRAL_BIN_ARGS="--no-sandbox"
+```

src/cache.ts

@@ -169,6 +169,15 @@ export async function getBinary(
   browser: "chrome" | "firefox",
   { cache = getDefaultCachePath(), timeout = 60000 } = {},
 ): Promise<string> {
+  if (
+    (await Deno.permissions.query({
+        name: "env",
+        variable: "ASTRAL_BIN_PATH",
+      })).state === "granted" && (Deno.env.get("ASTRAL_BIN_PATH"))
+  ) {
+    return Deno.env.get("ASTRAL_BIN_PATH")!;
+  }
+
   // TODO(lino-levan): fix firefox downloading
   const VERSION = SUPPORTED_VERSIONS[browser];
   const product = `${browser}-${SUPPORTED_VERSIONS[browser]}`;

src/debug.ts

@@ -10,6 +10,7 @@ if (!querySync) {
     env: "granted",
     sys: "denied",
     ffi: "denied",
+    import: "denied",
   } as const;
 
   querySync = ({ name }) => {

tests/get_binary_test.ts

@@ -1,4 +1,9 @@
-import { assertMatch, assertRejects, assertStringIncludes } from "@std/assert";
+import {
+  assertEquals,
+  assertMatch,
+  assertRejects,
+  assertStringIncludes,
+} from "@std/assert";
 import { assert } from "@std/assert/assert";
 import { resolve } from "@std/path/resolve";
 import { cleanCache, getBinary, launch } from "../mod.ts";
@@ -75,3 +80,22 @@ Deno.test("Test download after failure", { permissions }, async () => {
 Deno.test("Clean cache after tests", async () => {
   await cleanCache({ cache });
 });
+
+Deno.test(
+  "Use path from environment variable if specified",
+  { permissions: { env: true } },
+  async () => {
+    const env = Deno.env.get("ASTRAL_BIN_PATH");
+    try {
+      const path = "/usr/bin/google-chrome-stable";
+      Deno.env.set("ASTRAL_BIN_PATH", path);
+      assertEquals(await getBinary("chrome"), path);
+    } finally {
+      if (typeof env === "string") {
+        Deno.env.set("ASTRAL_BIN_PATH", env);
+      } else {
+        Deno.env.delete("ASTRAL_BIN_PATH");
+      }
+    }
+  },
+);