diff --git a/docs/pages/advanced/env_vars.md b/docs/pages/advanced/env_vars.md new file mode 100644 index 0000000..4224f8a --- /dev/null +++ b/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" +``` diff --git a/src/cache.ts b/src/cache.ts index 83dda93..d6e2b64 100644 --- a/src/cache.ts +++ b/src/cache.ts @@ -169,6 +169,15 @@ export async function getBinary( browser: "chrome" | "firefox", { cache = getDefaultCachePath(), timeout = 60000 } = {}, ): Promise { + 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]}`; diff --git a/src/debug.ts b/src/debug.ts index e76ca04..2109900 100644 --- a/src/debug.ts +++ b/src/debug.ts @@ -10,6 +10,7 @@ if (!querySync) { env: "granted", sys: "denied", ffi: "denied", + import: "denied", } as const; querySync = ({ name }) => { diff --git a/tests/get_binary_test.ts b/tests/get_binary_test.ts index 7b5a6a2..137bf36 100644 --- a/tests/get_binary_test.ts +++ b/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"); + } + } + }, +);