Browser Automation

Hrequests supports both Firefox and Chrome browsers, headless and headful sessions.

It is recommended to use Firefox instead. Chrome does not support fingerprint rotation, mocking human mouse movements, or browser extensions.

---

Usage

You can spawn a BrowserSession instance by calling it:

>>> page = hrequests.BrowserSession()  # headless=True by default

Parameters

Parameters:
    session (hrequests.session.TLSSession, optional): Session to use for headers, cookies, etc.
    resp (hrequests.response.Response, optional): Response to update with cookies, headers, etc.
    proxy (Union[str, BaseProxy], optional): Proxy to use for the browser. Example: http://1.2.3.4:8080
    mock_human (bool, optional): Whether to emulate human behavior. Defaults to False.
    engine (BrowserEngine, optional): Pass in an existing BrowserEngine instead of creating a new one
    verify (bool, optional): Whether to verify https requests
    headless (bool, optional): Whether to run the browser in headless mode. Defaults to True.
    os (Literal['win', 'mac', 'lin'], optional): Generate headers for a specific OS
    **kwargs: Additional arguments to pass to Playwright (or Camoufox parameters if using Firefox)

By default, BrowserSession returns a Firefox browser.

To create a Firefox session, use the chrome shortcut instead:

>>> page = hrequests.chrome.BrowserSession()

BrowserSession is entirely safe to use across threads.

---

Camoufox Integration

If you are using a Firefox BrowserSession, you can pass additional parameters to Camoufox:

>>> page = hrequests.BrowserSession(window=(1024, 768), block_images=True, addons=['/path/to/addon'], ...)

You can find a full list of parameters for Camoufox here.

Engine

The engine parameter allows you to pass in an existing BrowserEngine instance. This can be useful if you want to reuse a Playwright engine to save time on startup. It is completely threadsafe.

>>> engine = hrequests.BrowserEngine()

Use the same engine for multiple sessions:

>>> page1 = hrequests.BrowserSession(engine=engine)
>>> page2 = hrequests.BrowserSession(engine=engine)

---

Render an existing Response

Responses have a .render() method. This will render the contents of the response in a browser page.

Once the page is closed, the Response content and the Response's session cookies will be updated.

Simple usage

Rendered browser sessions will use the browser set in the initial request.

You can set a request's browser with the browser parameter in the hrequests.get method:

>>> resp = hrequests.get('https://example.com')

Or by setting the browser parameter of the hrequests.Session object:

>>> session = hrequests.Session()
>>> resp = session.get('https://example.com')

Example - submitting a login form:

>>> session = hrequests.Session()
>>> resp = session.get('https://www.somewebsite.com/')
>>> with resp.render(mock_human=True) as page:
...     page.find('.input#username').type('myuser')
...     page.find('.input#password').type('p4ssw0rd')
...     page.click('#submit')
# `session` & `resp` now have updated cookies, content, etc.

Or, without a context manager

>>> session = hrequests.Session()
>>> resp = session.get('https://www.somewebsite.com/')
>>> page = resp.render(mock_human=True)
>>> page.find('.input#username').type('myuser')
>>> page.find('.input#password').type('p4ssw0rd')
>>> page.click('#submit')
>>> page.close()  # Must close the page when done!

The mock_human parameter will emulate human-like behavior. This includes easing and randomizing mouse movements, and randomizing typing speed.

Parameters

Parameters:
    headless (bool, optional): Whether to run the browser in headless mode. Defaults to False.
    mock_human (bool, optional): Whether to emulate human behavior. Defaults to False.
    extensions (Union[str, Iterable[str]], optional): Path to a folder of unpacked extensions, or a list of paths to unpacked extensions
    engine (BrowserEngine, optional): Pass in an existing BrowserEngine instead of creating a new one
    **kwargs: Additional arguments to pass to Camoufox (see https://camoufox.com/python/usage)

---

Other ways to create a Browser Session

You can use .render to spawn a BrowserSession object directly from a url:

# Using a Session:
>>> page = session.render('https://google.com')
# Or without a session at all:
>>> page = hrequests.render('https://google.com')

Make sure to close all BrowserSession objects when done!

>>> page.close()