# Browser Automation

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:

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

<details>

<summary>Parameters</summary>

```
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)
```

</details>

By default, `BrowserSession` returns a Firefox browser.

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

```py
>>> 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:

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

You can find a full list of parameters for Camoufox [here](https://camoufox.com/python/usage).

## 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.

```python
>>> engine = hrequests.BrowserEngine()
```

Use the same engine for multiple sessions:

```python
>>> 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:

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

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

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

#### **Example - submitting a login form:**

```py
>>> 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**

```py
>>> 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.

<details>

<summary>Parameters</summary>

```
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)
```

</details>

***

## **Other ways to create a Browser Session**

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

```py
# 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!

```py
>>> page.close()
```