chore: migrate addScriptTag (#8878)

docs/api/puppeteer.frame.addscripttag.md

@@ -26,4 +26,4 @@ class Frame {
 
 Promise<[ElementHandle](./puppeteer.elementhandle.md)<HTMLScriptElement>>
 
-a promise that resolves to the added tag when the script's `onload` event fires or when the script content was injected into the frame.
+An [element handle](./puppeteer.elementhandle.md) to the injected `<script>` element.

docs/api/puppeteer.frameaddscripttagoptions.content.md

@@ -4,7 +4,7 @@ sidebar_label: FrameAddScriptTagOptions.content
 
 # FrameAddScriptTagOptions.content property
 
-Raw JavaScript content to be injected into the frame.
+JavaScript to be injected into the frame.
 
 **Signature:**
 

docs/api/puppeteer.frameaddscripttagoptions.id.md

@@ -0,0 +1,15 @@
+---
+sidebar_label: FrameAddScriptTagOptions.id
+---
+
+# FrameAddScriptTagOptions.id property
+
+Sets the `id` of the script.
+
+**Signature:**
+
+```typescript
+interface FrameAddScriptTagOptions {
+  id?: string;
+}
+```

docs/api/puppeteer.frameaddscripttagoptions.md

@@ -12,9 +12,10 @@ export interface FrameAddScriptTagOptions
 
 ## Properties
 
-| Property                                                    | Modifiers | Type   | Description                                                                                                      |
-| ----------------------------------------------------------- | --------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
-| [content?](./puppeteer.frameaddscripttagoptions.content.md) |           | string | <i>(Optional)</i> Raw JavaScript content to be injected into the frame.                                          |
-| [path?](./puppeteer.frameaddscripttagoptions.path.md)       |           | string | <i>(Optional)</i> The path to a JavaScript file to be injected into the frame.                                   |
-| [type?](./puppeteer.frameaddscripttagoptions.type.md)       |           | string | <i>(Optional)</i> Set the script's <code>type</code>. Use <code>module</code> in order to load an ES2015 module. |
-| [url?](./puppeteer.frameaddscripttagoptions.url.md)         |           | string | <i>(Optional)</i> the URL of the script to be added.                                                             |
+| Property                                                    | Modifiers | Type   | Description                                                                                                            |
+| ----------------------------------------------------------- | --------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| [content?](./puppeteer.frameaddscripttagoptions.content.md) |           | string | <i>(Optional)</i> JavaScript to be injected into the frame.                                                            |
+| [id?](./puppeteer.frameaddscripttagoptions.id.md)           |           | string | <i>(Optional)</i> Sets the <code>id</code> of the script.                                                              |
+| [path?](./puppeteer.frameaddscripttagoptions.path.md)       |           | string | <i>(Optional)</i> Path to a JavaScript file to be injected into the frame.                                             |
+| [type?](./puppeteer.frameaddscripttagoptions.type.md)       |           | string | <i>(Optional)</i> Sets the <code>type</code> of the script. Use <code>module</code> in order to load an ES2015 module. |
+| [url?](./puppeteer.frameaddscripttagoptions.url.md)         |           | string | <i>(Optional)</i> URL of the script to be added.                                                                       |

docs/api/puppeteer.frameaddscripttagoptions.path.md

@@ -4,7 +4,7 @@ sidebar_label: FrameAddScriptTagOptions.path
 
 # FrameAddScriptTagOptions.path property
 
-The path to a JavaScript file to be injected into the frame.
+Path to a JavaScript file to be injected into the frame.
 
 **Signature:**
 

docs/api/puppeteer.frameaddscripttagoptions.type.md

@@ -4,7 +4,7 @@ sidebar_label: FrameAddScriptTagOptions.type
 
 # FrameAddScriptTagOptions.type property
 
-Set the script's `type`. Use `module` in order to load an ES2015 module.
+Sets the `type` of the script. Use `module` in order to load an ES2015 module.
 
 **Signature:**
 

docs/api/puppeteer.frameaddscripttagoptions.url.md

@@ -4,7 +4,7 @@ sidebar_label: FrameAddScriptTagOptions.url
 
 # FrameAddScriptTagOptions.url property
 
-the URL of the script to be added.
+URL of the script to be added.
 
 **Signature:**
 

docs/api/puppeteer.page.addscripttag.md

@@ -10,27 +10,23 @@ Adds a `<script>` tag into the page with the desired URL or content.
 
 ```typescript
 class Page {
-  addScriptTag(options: {
-    url?: string;
-    path?: string;
-    content?: string;
-    type?: string;
-    id?: string;
-  }): Promise<ElementHandle<HTMLScriptElement>>;
+  addScriptTag(
+    options: FrameAddScriptTagOptions
+  ): Promise<ElementHandle<HTMLScriptElement>>;
 }
 ```
 
 ## Parameters
 
-| Parameter | Type                                                                           | Description |
-| --------- | ------------------------------------------------------------------------------ | ----------- |
-| options   | { url?: string; path?: string; content?: string; type?: string; id?: string; } |             |
+| Parameter | Type                                                                | Description             |
+| --------- | ------------------------------------------------------------------- | ----------------------- |
+| options   | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md) | Options for the script. |
 
 **Returns:**
 
 Promise&lt;[ElementHandle](./puppeteer.elementhandle.md)&lt;HTMLScriptElement&gt;&gt;
 
-Promise which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
+An [element handle](./puppeteer.elementhandle.md) to the injected `<script>` element.
 
 ## Remarks
 

src/common/Frame.ts

@@ -49,24 +49,29 @@ export interface FrameWaitForFunctionOptions {
  */
 export interface FrameAddScriptTagOptions {
   /**
-   * the URL of the script to be added.
+   * URL of the script to be added.
    */
   url?: string;
   /**
-   * The path to a JavaScript file to be injected into the frame.
+   * Path to a JavaScript file to be injected into the frame.
+   *
    * @remarks
    * If `path` is a relative path, it is resolved relative to the current
    * working directory (`process.cwd()` in Node.js).
    */
   path?: string;
   /**
-   * Raw JavaScript content to be injected into the frame.
+   * JavaScript to be injected into the frame.
    */
   content?: string;
   /**
-   * Set the script's `type`. Use `module` in order to load an ES2015 module.
+   * Sets the `type` of the script. Use `module` in order to load an ES2015 module.
    */
   type?: string;
+  /**
+   * Sets the `id` of the script.
+   */
+  id?: string;
 }
 
 /**
@@ -736,14 +741,75 @@ export class Frame {
    * Adds a `<script>` tag into the page with the desired url or content.
    *
    * @param options - Options for the script.
-   * @returns a promise that resolves to the added tag when the script's
-   * `onload` event fires or when the script content was injected into the
-   * frame.
+   * @returns An {@link ElementHandle | element handle} to the injected
+   * `<script>` element.
    */
   async addScriptTag(
     options: FrameAddScriptTagOptions
   ): Promise<ElementHandle<HTMLScriptElement>> {
-    return this.worlds[MAIN_WORLD].addScriptTag(options);
+    let {content = '', type} = options;
+    const {path} = options;
+    if (+!!options.url + +!!path + +!!content !== 1) {
+      throw new Error(
+        'Exactly one of `url`, `path`, or `content` may be specified.'
+      );
+    }
+
+    if (path) {
+      let fs;
+      try {
+        fs = (await import('fs')).promises;
+      } catch (error) {
+        if (error instanceof TypeError) {
+          throw new Error(
+            'Can only pass a file path in a Node-like environment.'
+          );
+        }
+        throw error;
+      }
+      content = await fs.readFile(path, 'utf8');
+      content += `//# sourceURL=${path.replace(/\n/g, '')}`;
+    }
+
+    type = type ?? 'text/javascript';
+
+    return this.worlds[MAIN_WORLD].transferHandle(
+      await this.worlds[PUPPETEER_WORLD].evaluateHandle(
+        async ({url, id, type, content}) => {
+          const script = document.createElement('script');
+          script.type = type;
+          script.text = content;
+          if (url) {
+            script.src = url;
+          }
+          if (id) {
+            script.id = id;
+          }
+          let resolve: undefined | ((value?: unknown) => void);
+          const promise = new Promise((res, rej) => {
+            if (url) {
+              script.addEventListener('load', res, {once: true});
+            } else {
+              resolve = res;
+            }
+            script.addEventListener(
+              'error',
+              event => {
+                rej(event.message ?? 'Could not load script');
+              },
+              {once: true}
+            );
+          });
+          document.head.appendChild(script);
+          if (resolve) {
+            resolve();
+          }
+          await promise;
+          return script;
+        },
+        {...options, type, content}
+      )
+    );
   }
 
   /**

src/common/IsolatedWorld.ts

@@ -117,7 +117,7 @@ export class IsolatedWorld {
   #frame: Frame;
   #injected: boolean;
   #document?: ElementHandle<Document>;
-  #contextPromise = createDeferredPromise<ExecutionContext>();
+  #context = createDeferredPromise<ExecutionContext>();
   #detached = false;
 
   // Set of bindings that have been registered in the current context.
@@ -165,22 +165,22 @@ export class IsolatedWorld {
 
   clearContext(): void {
     this.#document = undefined;
-    this.#contextPromise = createDeferredPromise();
+    this.#context = createDeferredPromise();
   }
 
   setContext(context: ExecutionContext): void {
     if (this.#injected) {
       context.evaluate(injectedSource).catch(debugError);
     }
     this.#ctxBindings.clear();
-    this.#contextPromise.resolve(context);
+    this.#context.resolve(context);
     for (const waitTask of this._waitTasks) {
       waitTask.rerun();
     }
   }
 
   hasContext(): boolean {
-    return this.#contextPromise.resolved();
+    return this.#context.resolved();
   }
 
   _detach(): void {
@@ -199,10 +199,10 @@ export class IsolatedWorld {
         `Execution context is not available in detached frame "${this.#frame.url()}" (are you trying to evaluate?)`
       );
     }
-    if (this.#contextPromise === null) {
+    if (this.#context === null) {
       throw new Error(`Execution content promise is missing`);
     }
-    return this.#contextPromise;
+    return this.#context;
   }
 
   async evaluateHandle<
@@ -334,105 +334,6 @@ export class IsolatedWorld {
     }
   }
 
-  /**
-   * Adds a script tag into the current context.
-   *
-   * @remarks
-   * You can pass a URL, filepath or string of contents. Note that when running Puppeteer
-   * in a browser environment you cannot pass a filepath and should use either
-   * `url` or `content`.
-   */
-  async addScriptTag(options: {
-    url?: string;
-    path?: string;
-    content?: string;
-    id?: string;
-    type?: string;
-  }): Promise<ElementHandle<HTMLScriptElement>> {
-    const {
-      url = null,
-      path = null,
-      content = null,
-      id = '',
-      type = '',
-    } = options;
-    if (url !== null) {
-      try {
-        const context = await this.executionContext();
-        return await context.evaluateHandle(addScriptUrl, url, id, type);
-      } catch (error) {
-        throw new Error(`Loading script from ${url} failed`);
-      }
-    }
-
-    if (path !== null) {
-      let fs;
-      try {
-        fs = (await import('fs')).promises;
-      } catch (error) {
-        if (error instanceof TypeError) {
-          throw new Error(
-            'Can only pass a filepath to addScriptTag in a Node-like environment.'
-          );
-        }
-        throw error;
-      }
-      let contents = await fs.readFile(path, 'utf8');
-      contents += '//# sourceURL=' + path.replace(/\n/g, '');
-      const context = await this.executionContext();
-      return await context.evaluateHandle(addScriptContent, contents, id, type);
-    }
-
-    if (content !== null) {
-      const context = await this.executionContext();
-      return await context.evaluateHandle(addScriptContent, content, id, type);
-    }
-
-    throw new Error(
-      'Provide an object with a `url`, `path` or `content` property'
-    );
-
-    async function addScriptUrl(url: string, id: string, type: string) {
-      const script = document.createElement('script');
-      script.src = url;
-      if (id) {
-        script.id = id;
-      }
-      if (type) {
-        script.type = type;
-      }
-      const promise = new Promise((res, rej) => {
-        script.onload = res;
-        script.onerror = rej;
-      });
-      document.head.appendChild(script);
-      await promise;
-      return script;
-    }
-
-    function addScriptContent(
-      content: string,
-      id: string,
-      type = 'text/javascript'
-    ) {
-      const script = document.createElement('script');
-      script.type = type;
-      script.text = content;
-      if (id) {
-        script.id = id;
-      }
-      let error = null;
-      script.onerror = e => {
-        return (error = e);
-      };
-      document.head.appendChild(script);
-      if (error) {
-        throw error;
-      }
-      return script;
-    }
-  }
-
   /**
    * Adds a style tag into the current context.
    *