# Session

A CDP session representing a single browser tab.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L12-L270)

``` python
Session(
    cdp,
    width=992,
    height=744,
)
```

Provides methods for navigation, viewport control, JavaScript evaluation, and DOM queries needed for screenshot capture.

## Parameters

`cdp: SyncCDP`  
The SyncCDP connection to use.

`width: int = 992`  
Initial viewport width in pixels.

`height: int = 744`  
Initial viewport height in pixels.

## Methods

| Name | Description |
|----|----|
| [close()](#close) | Close this session (tab). |
| [evaluate()](#evaluate) | Evaluate a JavaScript expression and return the result. |
| [get_element_bounds()](#get_element_bounds) | Get the bounding box of an element matched by a CSS selector. |
| [get_elements_union_bounds()](#get_elements_union_bounds) | Get the union bounding box of all elements matched by the given selectors. |
| [navigate()](#navigate) | Navigate to a URL and wait for the page to load. |
| [set_user_agent()](#set_user_agent) | Set a custom User-Agent string. |
| [set_viewport()](#set_viewport) | Set the viewport dimensions. |

### close()

Close this session (tab).

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L255-L264)

``` python
close()
```

### evaluate()

Evaluate a JavaScript expression and return the result.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L135-L158)

``` python
evaluate(expression)
```

#### Parameters

`expression: str`  
JavaScript expression to evaluate.

#### Returns

`Any`  
The result value from the JavaScript evaluation.

### get_element_bounds()

Get the bounding box of an element matched by a CSS selector.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L160-L202)

``` python
get_element_bounds(selector)
```

#### Parameters

`selector: str`  
CSS selector to match.

#### Returns

`ClipRect`  
The bounding rectangle of the element.

#### Raises

`ValueError`  
If the selector matches no elements.

### get_elements_union_bounds()

Get the union bounding box of all elements matched by the given selectors.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L204-L248)

``` python
get_elements_union_bounds(selectors)
```

#### Parameters

`selectors: list[str]`  
List of CSS selectors to match.

#### Returns

`ClipRect`  
The union bounding rectangle encompassing all matched elements.

### navigate()

Navigate to a URL and wait for the page to load.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L67-L99)

``` python
navigate(
    url,
    timeout=30.0,
)
```

#### Parameters

`url: str`  
The URL to navigate to.

`timeout: float = 30.0`  
Maximum seconds to wait for the page to load.

### set_user_agent()

Set a custom User-Agent string.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L250-L253)

``` python
set_user_agent(user_agent)
```

### set_viewport()

Set the viewport dimensions.

Usage

[Source](https://github.com/posit-dev/nokap/blob/main/nokap/_session.py#L101-L133)

``` python
set_viewport(
    width,
    height,
    device_scale_factor=1.0,
    mobile=False,
)
```

#### Parameters

`width: int`  
Viewport width in pixels.

`height: int`  
Viewport height in pixels.

`device_scale_factor: float = 1.0`  
Device scale factor (e.g., 2 for retina).

`mobile: bool = False`  
Whether to emulate a mobile device.