Puppeteer Real Browser

https://github.com/zfc-digital/puppeteer-real-browser
Admin
Puppeteer Real Browser is a library that prevents Puppeteer from being detected as a bot in services...
Tokens:5,304
Snippets:53
Trust Score:6.7
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Puppeteer Real Browser

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Install the package using npm. If on Linux, ensure xvfb is installed.

```bash
npm i puppeteer-real-browser
```

```bash
sudo apt-get install xvfb
```

--------------------------------

### Install Puppeteer-extra Plugin

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Install a puppeteer-extra plugin using npm. Some plugins might be detected as bots.

```bash
npm i puppeteer-extra-plugin-click-and-wait
```

--------------------------------

### Clone the Repository

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Clone the puppeteer-real-browser repository from GitHub to get started.

```bash
git clone https://github.com/zfcsoftware/puppeteer-real-browser
```

--------------------------------

### Basic Usage Example

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Connect to the browser with default options and navigate to a URL. The 'headless' option defaults to false for stable operation.

```javascript
const { connect } = require("puppeteer-real-browser");

async function test() {
  const { browser, page } = await connect({
    headless: false,

    args: [],

    customConfig: {},

    turnstile: true,

    connectOption: {},

    disableXvfb: false,
    ignoreAllFlags: false,
    // proxy:{
    //     host:'<proxy-host>',
    //     port:'<proxy-port>',
    //     username:'<proxy-username>',
    //     password:'<proxy-password>'
    // }
  });
  await page.goto("<url>");
}

test();
```

--------------------------------

### ES Module Import Example

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Demonstrates using ES Module syntax for importing the `connect` function in modern JavaScript projects.

```javascript
import { connect } from "puppeteer-real-browser";

const { page, browser } = await connect({
  headless: false,
  turnstile: true,
  args: ["--start-maximized"],
  connectOption: {
    defaultViewport: null
  }
});

await page.goto("https://example.com");
const title = await page.title();
console.log("Page title:", title);

await browser.close();
```

--------------------------------

### Puppeteer Extra Plugin Example

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Example of using a puppeteer-extra plugin with the connect function. Ensure to configure defaultViewport if needed.

```javascript
const test = require("node:test");
const assert = require("node:assert");
const { connect } = require("puppeteer-real-browser");

test("Puppeteer Extra Plugin", async () => {
  const { page, browser } = await connect({
    args: ["--start-maximized"],
    turnstile: true,
    headless: false,
    // disableXvfb: true,
    customConfig: {},
    connectOption: {
      defaultViewport: null,
    },
    plugins: [require("puppeteer-extra-plugin-click-and-wait")()],
  });
  await page.goto("https://google.com", { waitUntil: "domcontentloaded" });
  await page.clickAndWaitForNavigation("body");
  await browser.close();
});
```

--------------------------------

### Include Puppeteer Real Browser (Module)

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Import the connect function using ES Module syntax to start using the library.

```javascript
import { connect } from "puppeteer-real-browser";

const { page, browser } = await connect();
```

--------------------------------

### Use Puppeteer-Extra Plugins

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Integrate puppeteer-extra plugins for extended functionality. This example uses the `puppeteer-extra-plugin-click-and-wait` plugin.

```javascript
const { connect } = require("puppeteer-real-browser");

async function pluginExample() {
  // First install: npm i puppeteer-extra-plugin-click-and-wait
  const clickAndWait = require("puppeteer-extra-plugin-click-and-wait");

  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
    args: ["--start-maximized"],
    connectOption: {
      defaultViewport: null
    },
    plugins: [clickAndWait()]  // Pass initialized plugin instances
  });

  await page.goto("https://google.com", { waitUntil: "domcontentloaded" });

  // Use the plugin's added method
  await page.clickAndWaitForNavigation('body');

  await browser.close();
}

pluginExample();
```

--------------------------------

### connect

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Launches a Chrome browser instance with enhanced features for bypassing bot detection. It handles initialization, proxy configuration, Xvfb setup on Linux, plugin loading, and automatic Turnstile solving. The returned page object includes `realCursor` and `realClick` for human-like interactions.

```APIDOC
## connect

### Description
Launches a Chrome browser instance and returns Puppeteer browser and page objects, enhanced for anti-bot detection evasion.

### Method
`connect(options)`

### Parameters
#### Options Object
- **headless** (boolean | "new" | "shell") - Optional - Controls whether the browser runs in headless mode. `false` is recommended for stability.
- **args** (string[]) - Optional - Additional Chrome command-line flags.
- **customConfig** (object) - Optional - Options for `chrome-launcher` (e.g., `userDataDir`, `chromePath`).
- **turnstile** (boolean) - Optional - Enables automatic solving of Cloudflare Turnstile captchas. Defaults to `true`.
- **connectOption** (object) - Optional - Options for `puppeteer.connect()`.
  - **defaultViewport** (object | null) - Optional - Sets the default viewport. `null` uses the browser window size.
- **disableXvfb** (boolean) - Optional - Set to `true` on Linux if you want to see the browser window. Defaults to `false`.
- **ignoreAllFlags** (boolean) - Optional - Set to `true` to override all default Chrome flags.
- **plugins** (array) - Optional - An array of Puppeteer Extra plugins.

### Returns
An object containing:
- **browser**: The Puppeteer browser instance.
- **page**: The enhanced Puppeteer page object with `realCursor` and `realClick`.

### Request Example
```javascript
const { connect } = require("puppeteer-real-browser");

async function main() {
  const { browser, page } = await connect({
    headless: false,           
    args: ["--start-maximized"],
    customConfig: {},
    turnstile: true,
    connectOption: {
      defaultViewport: null
    },
    disableXvfb: false,
    ignoreAllFlags: false,
    plugins: []
  });

  await page.goto("https://example.com");
  console.log("Page title:", await page.evaluate(() => document.title));
  await browser.close();
}

main();
```
```

--------------------------------

### Include Puppeteer Real Browser (CommonJS)

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Import the connect function using CommonJS syntax to start using the library.

```javascript
const { connect } = require("puppeteer-real-browser");

const start = async () => {
  const { page, browser } = await connect();
};
```

--------------------------------

### Test Against Bot Detection Services

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

This example demonstrates testing against multiple bot detection services, including FingerprintJS Bot Detector and Recaptcha V3. It utilizes `page.evaluate` to extract detection results and scores. Ensure a delay is included after navigation to allow detection scripts to execute.

```javascript
const { connect } = require("puppeteer-real-browser");

async function botDetectionTest() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
    args: ["--start-maximized"],
    connectOption: {
      defaultViewport: null
    }
  });

  // Test against FingerprintJS Bot Detector
  await page.goto("https://fingerprint.com/products/bot-detection/");
  await new Promise(r => setTimeout(r, 5000));

  const isDetected = await page.evaluate(() => {
    const subtitle = document.querySelector('.HeroSection-module--botSubTitle--2711e');
    return subtitle ? subtitle.textContent.includes("not") : false;
  });

  console.log("Bot detection result:", isDetected ? "PASSED (not detected)" : "FAILED (detected as bot)");

  // Test Recaptcha V3 Score
  await page.goto("https://antcpt.com/score_detector/");
  await page.realClick("button");
  await new Promise(r => setTimeout(r, 5000));

  const score = await page.evaluate(() => {
    return document.querySelector('big').textContent.replace(/[^0-9.]/g, '');
  });

  console.log("Recaptcha V3 Score:", score, score >= 0.7 ? "(GOOD)" : "(LOW)");

  await browser.close();
}

botDetectionTest();
```

--------------------------------

### Bypass Cloudflare WAF Challenges

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Navigate through Cloudflare's Web Application Firewall challenge pages. This example waits for the challenge to be passed before proceeding.

```javascript
const { connect } = require("puppeteer-real-browser");

async function cloudflareWafExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
    args: ["--start-maximized"],
    connectOption: {
      defaultViewport: null
    }
  });

  // Navigate to Cloudflare-protected page
  await page.goto("https://nopecha.com/demo/cloudflare");

  // Wait for the challenge to be solved and page to load
  let verified = null;
  const startTime = Date.now();

  while (!verified && (Date.now() - startTime) < 30000) {
    verified = await page.evaluate(() => {
      return document.querySelector('.link_row') ? true : null;
    }).catch(() => null);
    await new Promise(r => setTimeout(r, 1000));
  }

  if (verified) {
    console.log("Cloudflare WAF challenge passed!");
    // Continue with page interaction
    const content = await page.content();
    console.log("Page loaded successfully, content length:", content.length);
  }

  await browser.close();
}

cloudflareWafExample();
```

--------------------------------

### Enable Cloudflare Turnstile Auto-Solver

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Automatically detect and solve Cloudflare Turnstile captchas by enabling the `turnstile` option. This example waits for the Turnstile token to be generated.

```javascript
const { connect } = require("puppeteer-real-browser");

async function turnstileExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,  // Enable automatic Turnstile solving
    connectOption: {
      defaultViewport: null
    }
  });

  // Navigate to a page with Cloudflare Turnstile
  await page.goto("https://turnstile.zeroclover.io/");
  await page.waitForSelector('[type="submit"]');

  // Wait for the Turnstile token to be generated (auto-solved)
  let token = null;
  const startTime = Date.now();

  while (!token && (Date.now() - startTime) < 30000) {
    token = await page.evaluate(() => {
      try {
        const value = document.querySelector('[name="cf-turnstile-response"]').value;
        return value && value.length > 20 ? value : null;
      } catch (e) {
        return null;
      }
    });
    await new Promise(r => setTimeout(r, 1000));
  }

  if (token) {
    console.log("Turnstile solved! Token:", token.substring(0, 50) + "...");
  }

  await browser.close();
}

turnstileExample();
```

--------------------------------

### Configure HTTP Proxy with Authentication

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Set up an HTTP proxy with optional username and password. The proxy configuration is passed directly to the connect function.

```javascript
const { connect } = require("puppeteer-real-browser");

async function proxyExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
    proxy: {
      host: "proxy.example.com",
      port: 8080,
      username: "proxy_user",      // Optional: for authenticated proxies
      password: "proxy_password"   // Optional: for authenticated proxies
    }
  });

  // All requests will go through the proxy
  await page.goto("https://httpbin.org/ip");

  const ip = await page.evaluate(() => {
    return JSON.parse(document.body.innerText).origin;
  });
  console.log("Proxy IP:", ip);

  await browser.close();
}

proxyExample();
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Change the current directory to the cloned puppeteer-real-browser project.

```bash
cd puppeteer-real-browser
```

--------------------------------

### Build Docker Image

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Build a Docker image tagged as 'puppeteer-real-browser-project' using the provided Dockerfile.

```bash
docker build -t puppeteer-real-browser-project .
```

--------------------------------

### Connect to Puppeteer Real Browser

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Launches a Chrome browser instance with anti-bot measures. Configure options like headless mode, arguments, and Turnstile solving. Use `defaultViewport: null` to match browser window size.

```javascript
const { connect } = require("puppeteer-real-browser");

async function main() {
  const { browser, page } = await connect({
    headless: false,           // false for best stability, can be "new", true, or "shell"
    args: ["--start-maximized"], // Additional Chrome flags
    customConfig: {},          // chrome-launcher options (userDataDir, chromePath, etc.)
    turnstile: true,           // Auto-solve Cloudflare Turnstile captchas
    connectOption: {           // puppeteer.connect() options
      defaultViewport: null    // null = use browser window size
    },
    disableXvfb: false,        // Set true on Linux to see the browser window
    ignoreAllFlags: false,     // Set true to override all default Chrome flags
    plugins: []                // puppeteer-extra plugins array
  });

  await page.goto("https://example.com");

  // Use standard Puppeteer methods
  await page.waitForSelector("h1");
  const title = await page.evaluate(() => document.title);
  console.log("Page title:", title);

  await browser.close();
}

main();

```

--------------------------------

### Configure Custom Chrome Launch Options

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Use `chrome-launcher` options to specify custom Chrome paths, persistent user data directories for sessions, and other launch configurations. Ensure `headless` is set to `false` and `turnstile` to `true` for these options to be effective.

```javascript
const { connect } = require("puppeteer-real-browser");

async function customConfigExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
    customConfig: {
      // Specify custom Chrome executable path
      chromePath: "/usr/bin/google-chrome-stable",
      // Use persistent user data directory for cookies/sessions
      userDataDir: "/path/to/chrome/profile",
      // Additional chrome-launcher options
      logLevel: "silent"
    },
    args: [
      "--start-maximized",
      "--disable-notifications"
    ],
    connectOption: {
      defaultViewport: null
    }
  });

  await page.goto("https://example.com");
  await browser.close();
}

customConfigExample();
```

--------------------------------

### Run Docker Container

Source: https://github.com/zfc-digital/puppeteer-real-browser/blob/main/README.md

Run a Docker container from the 'puppeteer-real-browser-project' image.

```bash
docker run puppeteer-real-browser-project
```

--------------------------------

### Advanced Cursor Control with page.realCursor

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Provides direct access to the ghost-cursor instance for custom mouse movements, hovering, and dragging with natural motion paths. Use `move`, `click`, and `moveTo` for precise control.

```javascript
const { connect } = require("puppeteer-real-browser");

async function cursorExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true
  });

  await page.goto("https://example.com");

  // Access ghost-cursor directly for advanced operations
  const cursor = page.realCursor;

  // Move to an element with natural motion
  await cursor.move("#target-element");

  // Click with the cursor
  await cursor.click("#button");

  // Move to specific coordinates
  await cursor.moveTo({ x: 500, y: 300 });

  await browser.close();
}

cursorExample();

```

--------------------------------

### page.realClick

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Provides a human-like click method that simulates natural mouse cursor movement to the target element before clicking, aiding in bypassing bot detection.

```APIDOC
## page.realClick

### Description
Simulates a human-like click on an element using natural mouse cursor movement, powered by `ghost-cursor`.

### Method
`page.realClick(selector)`

### Parameters
#### Path Parameters
- **selector** (string) - Required - The CSS selector of the element to click.

### Request Example
```javascript
const { connect } = require("puppeteer-real-browser");

async function clickExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true
  });

  await page.goto("https://example.com/login");

  await page.realClick("#username-input");
  await page.type("#username-input", "user@example.com");

  await page.realClick("#password-input");
  await page.type("#password-input", "password123");

  await page.realClick('button[type="submit"]');

  await browser.close();
}

clickExample();
```
```

--------------------------------

### page.realCursor

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Grants direct access to the `ghost-cursor` instance, allowing for advanced and customizable mouse cursor operations with human-like motion paths.

```APIDOC
## page.realCursor

### Description
Provides direct access to the `ghost-cursor` instance for advanced control over mouse cursor movements and actions.

### Method
`page.realCursor`

### Returns
A `ghost-cursor` instance.

### Request Example
```javascript
const { connect } = require("puppeteer-real-browser");

async function cursorExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true
  });

  await page.goto("https://example.com");

  const cursor = page.realCursor;

  await cursor.move("#target-element");
  await cursor.click("#button");
  await cursor.moveTo({ x: 500, y: 300 });

  await browser.close();
}

cursorExample();
```
```

--------------------------------

### Perform Human-like Clicks with page.realClick

Source: https://context7.com/zfc-digital/puppeteer-real-browser/llms.txt

Simulates realistic mouse movements to click elements, aiding in bypassing bot detection. Use CSS selectors to target elements for clicking and typing.

```javascript
const { connect } = require("puppeteer-real-browser");

async function clickExample() {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true
  });

  await page.goto("https://example.com/login");

  // Human-like click that moves cursor naturally to the element
  await page.realClick("#username-input");
  await page.type("#username-input", "user@example.com");

  await page.realClick("#password-input");
  await page.type("#password-input", "password123");

  // Click the submit button with realistic mouse movement
  await page.realClick('button[type="submit"]');

  await browser.close();
}

clickExample();

```
Tokens:
Raw