Puppeteer icon

Puppeteer

Automate browser interactions using Puppeteer

Actions4

Overview

The Run Custom Script operation of the Puppeteer node allows you to execute custom JavaScript code in a headless browser environment using Puppeteer. This is particularly useful for advanced web automation, scraping, or testing scenarios where you need full control over browser actions. You can interact with web pages, extract data, automate form submissions, or perform any browser-based task that can be scripted in JavaScript.

Practical examples:

  • Scraping dynamic content from websites that require JavaScript rendering.
  • Automating login flows and extracting session data.
  • Testing website behavior under different device emulations or network conditions.
  • Filling out and submitting forms programmatically.

Properties

Supported Input Properties

Display Name Type Description
Script Code string (JavaScript code editor) JavaScript code to execute with Puppeteer. You have access to the $browser and $page objects, which represent the Puppeteer browser and page.
Options collection Additional configuration for browser launch and behavior. Includes:
  Batch Size number Maximum number of pages to open simultaneously. More pages will consume more memory and CPU.
  Browser WebSocket Endpoint string The WebSocket URL of the browser to connect to. When set, Puppeteer connects to an existing browser instance instead of launching a new one.
  Emulate Device options Emulate a specific device (e.g., mobile, tablet).
  Executable path string Path to the browser executable. Ignored if Browser WebSocket Endpoint is set.
  Extra Headers fixedCollection HTTP headers to send with requests.
  File Name string File name for binary output (not applicable to Run Custom Script).
  Launch Arguments fixedCollection Additional command line arguments for the browser instance.
  Protocol Timeout number Maximum time in milliseconds to wait for a protocol response.
  Page Caching boolean Enable or disable page-level caching. Defaults to true.
  Headless mode boolean Run browser in headless mode. Defaults to true.
  Use Chrome Headless Shell boolean Use chrome-headless-shell. Requires headless mode enabled and shell in $PATH.
  Stealth mode boolean Makes detection of headless Puppeteer harder.
  Human typing mode boolean Simulates human-like typing on input elements.
  Human Typing Options collection Fine-tune delays and typo chances for human typing simulation. Only shown if Human typing mode is enabled.
  Proxy Server string Use a custom proxy configuration (e.g., localhost:8080, socks5://localhost:1080).
  Add Container Arguments boolean Add recommended arguments for container environments. Defaults to true.

Note: Some options (like File Name, Timeout, Wait Until) are not relevant for the "Run Custom Script" operation.

Output

  • The output is determined by your custom script. Your script must return an array of objects, each representing an item.
  • Each object returned by your script will become an output item with its properties available in the json field.

Example output structure:

[
  {
    "json": {
      "ip": "203.0.113.42",
      // ...any other fields added by your script or passed through from input
    }
  }
]
  • If your script does not return an array, the node will throw an error.
  • Binary data output is not directly supported in this operation; only JSON objects are expected.

Dependencies

  • External Service: None required unless your script interacts with external APIs or services.
  • API Keys: Not required by default, but may be needed depending on your script's logic.
  • n8n Configuration: No special configuration required unless connecting to a remote browser via WebSocket or using proxies.
  • Environment Variables:
    • NODE_FUNCTION_ALLOW_BUILTIN, NODE_FUNCTION_ALLOW_EXTERNAL, CODE_ENABLE_STDOUT can affect script execution and logging.

Troubleshooting

Common Issues:

  • Script does not return an array:
    Error: "Custom script must return an array of items. Please ensure your script returns an array, e.g., return [{ key: value }]."
    Resolution: Make sure your script ends with a statement like return [{...}];.

  • Browser fails to launch/connect:
    Error: "Failed to launch/connect to browser: ..."
    Resolution: Check your Puppeteer installation, browser executable path, and permissions. If using a remote browser, verify the WebSocket endpoint.

  • Invalid device emulation or launch arguments:
    Error messages related to unknown devices or invalid arguments.
    Resolution: Ensure device names and arguments are valid and supported.

  • Resource limitations:
    Opening too many pages at once (high batch size) may exhaust system resources.
    Resolution: Lower the batch size in Options.

  • Network/proxy issues:
    If using a proxy, ensure the server is reachable and credentials (if any) are correct.

Links and References

Discussion