npm package: @requestly/rq-automation
Description: Package for using Requestly in automation testing frameworks like Selenium, Playwright, and Puppeteer.
Author: Requestly
Latest version: 1.0.0

# Requestly For Automation

A npm package for integrating Requestly with automation testing frameworks like Selenium, Playwright, and Puppeteer. This package allows you to modify network requests during automated testing by leveraging Requestly's browser extension capabilities. You can modify headers, user agents, and import your Requestly rules for a seamless testing experience.

## Installation

```bash
npm install @requestly/rq-automation
```

## Requirements

- Node.js >= v18.20.8
- A peer dependency for your chosen framework:
  - `selenium-webdriver`
  - `playwright`
  - `puppeteer`

## Core Concept

The library works by generating special URLs. When your automated browser session navigates to one of these URLs, the Requestly extension intercepts it and configures the required rules. For example, to add a request header, you navigate to a URL generated by `addRequestHeaderUrl()`.

## API Reference

Here are the core functions provided by the package:

- `getExtension(type)`: Gets the path to the Requestly extension. `type` can be `'crx'`, `'xpi'`, or `'unpacked'`.
- `closeWelcomePage(driver)`: Closes the Requestly welcome page that opens on the first run.

### Request Headers

- `addRequestHeaderUrl(name, value)`: Adds a single request header.
- `addRequestHeadersUrl(headers)`: Adds multiple request headers from an object.
- `removeRequestHeaderUrl(name)`: Removes a single request header.
- `removeRequestHeadersUrl(headerNames)`: Removes multiple request headers from an array of names.

### Response Headers

- `addResponseHeaderUrl(name, value)`: Adds a single response header.
- `addResponseHeadersUrl(headers)`: Adds multiple response headers from an object.
- `removeResponseHeaderUrl(name)`: Removes a single response header.
- `removeResponseHeadersUrl(headerNames)`: Removes multiple response headers from an array of names.

### Importing Rules

- `importRules(apiKey)`: Import all rules from your Requestly account using API key.

## Usage with Selenium WebDriver

### Setup

```javascript
const { Builder } = require("selenium-webdriver");
const chrome = require("selenium-webdriver/chrome");
const { getExtension } = require("@requestly/rq-automation");

async function setupDriver() {
  const options = new chrome.Options();

  // Load Requestly extension
  const extensionPath = getExtension("unpacked");
  options.addArguments(`--load-extension=${extensionPath}`);
  options.addArguments(`--disable-extensions-except=${extensionPath}`);

  const driver = await new Builder()
    .forBrowser("chrome")
    .setChromeOptions(options)
    .build();

  return driver;
}
```

### Examples

```javascript
const {
  addRequestHeaderUrl,
  addRequestHeadersUrl,
  removeRequestHeaderUrl,
  removeRequestHeadersUrl,
  addResponseHeaderUrl,
  addResponseHeadersUrl,
  removeResponseHeaderUrl,
  removeResponseHeadersUrl,
  importRules,
  closeWelcomePage,
} = require("@requestly/rq-automation");

async function seleniumExample() {
  const driver = await setupDriver();
  await closeWelcomePage(driver);

  // Add a single request header
  await driver.get(addRequestHeaderUrl("X-Custom-Header", "MyValue"));

  // Add multiple request headers
  await driver.get(
    addRequestHeadersUrl({
      Authorization: "Bearer token123",
      "X-Another-Header": "AnotherValue",
    })
  );

  // Remove a request header
  await driver.get(removeRequestHeaderUrl("X-Another-Header"));

  // Remove multiple request headers
  await driver.get(
    removeRequestHeadersUrl(["Authorization", "X-Custom-Header"])
  );

  // Add a response header
  await driver.get(addResponseHeaderUrl("Access-Control-Allow-Origin", "*"));

  // Add multiple response headers
  await driver.get(
    addResponseHeadersUrl({
      "X-Response-Header": "ResponseValue",
      "X-Another-Response-Header": "AnotherResponseValue",
    })
  );

  // Remove a response header
  await driver.get(removeResponseHeaderUrl("X-Another-Response-Header"));

  // Remove multiple response headers
  await driver.get(
    removeResponseHeadersUrl(["X-Response-Header", "X-Another-Response-Header"])
  );

  // Import a shared list of rules
  await driver.get(importRules("YOUR_API_KEY"));

  // Your test code here
  await driver.get("https://example.com");

  await driver.quit();
}

seleniumExample();
```

## Usage with Playwright

### Setup

```javascript
const { chromium } = require("playwright");
const { getExtension } = require("@requestly/rq-automation");
const path = require("path");

async function playwrightExample() {
  const extensionPath = getExtension("unpacked");
  const userDataDir = path.join(__dirname, "user-data");

  const browser = await chromium.launchPersistentContext(userDataDir, {
    headless: false,
    args: [
      `--load-extension=${extensionPath}`,
      `--disable-extensions-except=${extensionPath}`,
    ],
  });

  const page = await browser.newPage();

  // ... see examples below

  await browser.close();
}
```

### Examples

```javascript
const { chromium } = require("playwright");
const { getExtension } = require("@requestly/rq-automation");
const path = require("path");
const {
  addRequestHeaderUrl,
  // ... import other functions
  importRules,
  closeWelcomePage,
} = require("@requestly/rq-automation");

async function playwrightExample() {
  const extensionPath = getExtension("unpacked");
  const userDataDir = path.join(__dirname, "user-data");

  const browser = await chromium.launchPersistentContext(userDataDir, {
    headless: false,
    args: [
      `--load-extension=${extensionPath}`,
      `--disable-extensions-except=${extensionPath}`,
    ],
  });
  await closeWelcomePage(browser);

  const page = await browser.newPage();

  // Add a request header
  await page.goto(addRequestHeaderUrl("X-Request-By", "Puppeteer"));

  // Import a shared list of rules
  await page.goto(importRules("YOUR_API_KEY"));

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

playwrightExample();
```

## Usage with Puppeteer

### Setup

```javascript
const puppeteer = require("puppeteer");
const { getExtension } = require("@requestly/rq-automation");

async function puppeteerExample() {
  const extensionPath = getExtension("unpacked");

  const browser = await puppeteer.launch({
    headless: false,
    args: [
      `--load-extension=${extensionPath}`,
      `--disable-extensions-except=${extensionPath}`,
    ],
  });

  const page = await browser.newPage();

  // ... see examples below

  await browser.close();
}
```

### Examples

```javascript
const puppeteer = require("puppeteer");
const { getExtension } = require("@requestly/rq-automation");
const {
  addRequestHeaderUrl,
  // ... import other functions
  importRules,
  closeWelcomePage,
} = require("@requestly/rq-automation");

async function puppeteerExample() {
  const extensionPath = getExtension("unpacked");

  const browser = await puppeteer.launch({
    headless: false,
    args: [
      `--load-extension=${extensionPath}`,
      `--disable-extensions-except=${extensionPath}`,
    ],
  });
  await closeWelcomePage(browser);

  const page = await browser.newPage();
  await page.goto(addRequestHeaderUrl("X-Request-By", "Puppeteer"));

  // Import a shared list of rules
  await page.goto(importRules("YOUR_API_KEY"));

  // Navigate to your application
  await page.goto("https://example.com");

  await browser.close();
}
puppeteerExample();
```

## Support

- [Documentation](https://docs.requestly.io)
- [Report Issues](https://github.com/requestly/requestly-automation/issues)
- [Contact Us](mailto:contact@requestly.io)

## Keywords

`requestly` `selenium` `playwright` `puppeteer` `webdriver` `chrome` `modify` `headers` `request headers` `response headers` `redirect` `delay` `throttle` `automation` `testing`