feat: allow passing args to evaluate

docs/pages/examples/evaluate.md

@@ -0,0 +1,41 @@
+---
+title: 2.3 - Evaluate
+description: A small example on how to do complex evaluation in Astral
+index: 1
+---
+
+## Running
+
+```bash
+deno run -A https://deno.land/x/astral/examples/evaluate.ts
+```
+
+## Code
+
+```ts
+// Import Astral
+import { launch } from "https://deno.land/x/astral/mod.ts";
+
+// Launch the browser
+const browser = await launch();
+
+// Open a new page
+const page = await browser.newPage("https://deno.land");
+
+// Run code in the context of the browser
+const value = await page.evaluate(() => {
+  return document.body.innerHTML;
+});
+console.log(value);
+
+// Run code with args
+const result = await page.evaluate((x, y) => {
+  return `The result of adding ${x}+${y} = ${x + y}`;
+}, {
+  args: [10, 15],
+});
+console.log(result);
+
+// Close the browser
+await browser.close();
+```

examples/evaluate.ts

@@ -15,5 +15,13 @@ const value = await page.evaluate(() => {
 });
 console.log(value);
 
+// Run code with args
+const result = await page.evaluate((x, y) => {
+  return `The result of adding ${x}+${y} = ${x + y}`;
+}, {
+  args: [10, 15],
+});
+console.log(result);
+
 // Close the browser
 await browser.close();

src/page.ts

@@ -37,7 +37,15 @@ export type WaitForNetworkIdleOptions = {
   idleConnections?: number;
 };
 
-export type EvalFunc<T> = string | (() => T);
+type AnyArray = readonly unknown[];
+
+export type EvaluateFunction<T, R extends AnyArray> =
+  | string
+  | ((...args: R) => T);
+
+export interface EvaluateOptions<T> {
+  args: Readonly<T>;
+}
 
 /**
  * Page provides methods to interact with a single tab in the browser
@@ -207,9 +215,15 @@ export class Page {
    * const innerHTML = await page.evaluate(()=>document.body.innerHTML)
    * ```
    */
-  async evaluate<T>(func: EvalFunc<T>) {
+  async evaluate<T, R extends AnyArray>(
+    func: EvaluateFunction<T, R>,
+    evaluateOptions?: EvaluateOptions<R>,
+  ) {
     if (typeof func === "function") {
-      func = `(${func.toString()})()`;
+      const args = evaluateOptions?.args ?? [];
+      func = `(${func.toString()})(${
+        args.map((arg) => `${JSON.stringify(arg)}`).join(",")
+      })`;
     }
     const { result, exceptionDetails } = await retryDeadline(
       this.#celestial.Runtime.evaluate({
@@ -319,12 +333,15 @@ export class Page {
   /**
    * Runs a function in the context of the page until it returns a truthy value.
    */
-  async waitForFunction<T>(func: EvalFunc<T>) {
+  async waitForFunction<T, R extends AnyArray>(
+    func: EvaluateFunction<T, R>,
+    evaluateOptions?: EvaluateOptions<R>,
+  ) {
     // TODO(lino-levan): Make this easier to read
     await deadline(
       (async () => {
         while (true) {
-          const result = await this.evaluate(func);
+          const result = await this.evaluate(func, evaluateOptions);
 
           if (result) {
             return result;

tests/evaluate_test.ts

@@ -0,0 +1,21 @@
+import { assertEquals } from "https://deno.land/[email protected]/assert/assert_equals.ts";
+import { launch } from "../mod.ts";
+
+Deno.test("Testing evaluate", async () => {
+  // Launch browser
+  const browser = await launch();
+
+  // Open the webpage
+  const page = await browser.newPage("http://example.com");
+
+  // passing arguments to evaluate
+  const result = await page.evaluate((x, y) => {
+    return x + y;
+  }, {
+    args: ["string", "concat"] as const,
+  });
+  assertEquals(result, "stringconcat");
+
+  // Close browser
+  await browser.close();
+});