Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
from datetime import UTC, datetime, timedelta
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from pydantic import ValidationError
from structlog.testing import capture_logs
from skyvern.exceptions import BrowserSessionClosed, BrowserSessionExpired, BrowserSessionStartupTimeout
from skyvern.forge.sdk.routes import browser_sessions as browser_sessions_routes
from skyvern.forge.sdk.schemas.persistent_browser_sessions import (
PersistentBrowserSession,
unusable_browser_session_error,
)
from skyvern.schemas.browser_session_close import BrowserSessionCloseReason
from skyvern.schemas.browser_session_timeouts import (
DEFAULT_TIMEOUT,
LIFETIME_END_TOLERANCE_SECONDS,
MAX_EXTENDED_LIFETIME_SECONDS,
MAX_EXTENDED_TIMEOUT,
MAX_LIFETIME_SECONDS,
MAX_TIMEOUT,
MAX_TIMEOUT_EXCEEDED_MESSAGE,
MIN_TIMEOUT,
creation_timeout_minutes,
lifetime_cap_seconds,
lived_full_lifetime,
max_lifetime_exceeded_warning,
max_timeout_exceeded_warning,
seconds_until_expiry,
session_is_active,
)
from skyvern.schemas.browser_sessions import CreateBrowserSessionRequest
from skyvern.webeye.schemas import BrowserSessionResponse
_BASE = 60 * 60 # 1h base timeout
_IDLE = 60 * 60 # idle out 1h after last activity
_CAP = MAX_LIFETIME_SECONDS
# Past the base timeout but well under the lifetime cap, so activity-renewal cases
# are decided by activity rather than by the cap.
_PAST_BASE = _BASE * 2
def _active(**overrides: float | bool | None) -> bool:
kwargs: dict[str, float | bool | None] = {
"seconds_since_start": 0.0,
"base_timeout_seconds": _BASE,
"seconds_since_last_activity": None,
"idle_timeout_seconds": _IDLE,
"max_lifetime_seconds": _CAP,
}
kwargs.update(overrides)
return session_is_active(**kwargs) # type: ignore[arg-type]
def test_within_base_timeout_is_active_without_activity() -> None:
assert _active(seconds_since_start=_BASE - 1, seconds_since_last_activity=None) is True
def test_past_base_timeout_without_activity_is_inactive() -> None:
# No activity ever recorded -> pre-activity behavior: dies at base timeout.
assert _active(seconds_since_start=_BASE + 1, seconds_since_last_activity=None) is False
def test_base_timeout_boundary_is_inactive_without_activity() -> None:
assert _active(seconds_since_start=_BASE, seconds_since_last_activity=None) is False
def test_past_base_timeout_with_recent_activity_stays_active() -> None:
assert _active(seconds_since_start=_PAST_BASE, seconds_since_last_activity=_IDLE - 1) is True
def test_past_base_timeout_with_stale_activity_is_inactive() -> None:
assert _active(seconds_since_start=_PAST_BASE, seconds_since_last_activity=_IDLE + 1) is False
def test_idle_boundary_is_inactive() -> None:
assert _active(seconds_since_start=_PAST_BASE, seconds_since_last_activity=_IDLE) is False
def test_hard_cap_overrides_recent_activity() -> None:
# Actively driven, but past the lifetime cap -> reaped regardless.
assert _active(seconds_since_start=_CAP, seconds_since_last_activity=0.0) is False
def test_just_under_hard_cap_with_activity_stays_active() -> None:
assert _active(seconds_since_start=_CAP - 1, seconds_since_last_activity=0.0) is True
def test_future_activity_timestamp_counts_as_recent() -> None:
# Clock skew can make last_activity slightly ahead of now -> negative elapsed.
# Treated as very recent (active), never as stale.
assert _active(seconds_since_start=_PAST_BASE, seconds_since_last_activity=-5.0) is True
def test_default_cap_is_max_timeout() -> None:
# Omitting max_lifetime_seconds falls back to the 4h MAX_TIMEOUT ceiling.
assert (
session_is_active(
seconds_since_start=_CAP,
base_timeout_seconds=_BASE,
seconds_since_last_activity=0.0,
idle_timeout_seconds=_IDLE,
)
is False
)
def test_seconds_until_expiry_uses_the_later_base_or_activity_deadline() -> None:
assert (
seconds_until_expiry(
seconds_since_start=_BASE + 120,
base_timeout_seconds=_BASE,
seconds_since_last_activity=120,
idle_timeout_seconds=_IDLE,
)
== _IDLE - 120
)
def test_activity_does_not_extend_a_deadline_the_infrastructure_fixes() -> None:
"""SKY-15044: a 20-minute vendor session five minutes in reported ~19:34 left rather than
14:46, because a CDP command 26s earlier renewed an activity lease its provider does not
honour. The provider killed it at 20:00.4 regardless."""
fixed_timeout = 20 * 60
assert (
seconds_until_expiry(
seconds_since_start=314,
base_timeout_seconds=fixed_timeout,
seconds_since_last_activity=26,
idle_timeout_seconds=fixed_timeout,
activity_extends_deadline=False,
)
== fixed_timeout - 314
)
assert (
seconds_until_expiry(
seconds_since_start=314,
base_timeout_seconds=fixed_timeout,
seconds_since_last_activity=26,
idle_timeout_seconds=fixed_timeout,
)
== fixed_timeout - 26
)
def test_seconds_until_expiry_is_capped_by_max_lifetime() -> None:
assert (
seconds_until_expiry(
seconds_since_start=_CAP - 30,
base_timeout_seconds=_BASE,
seconds_since_last_activity=0,
idle_timeout_seconds=_IDLE,
)
== 30
)
def test_an_extended_budget_lifts_the_hard_cap_only_where_the_caller_allows_it() -> None:
# A budget only exceeds the creation cap through an extension, and only a pod can serve one, so
# the lift is opt-in: first-party gates follow the mirrored budget past 4h, and a vendor row
# carrying an oversized budget still ends at the cap.
extended = MAX_EXTENDED_LIFETIME_SECONDS - 30 * 60
assert (
_active(
seconds_since_start=_CAP + 1,
base_timeout_seconds=extended,
idle_timeout_seconds=extended,
budget_may_lift_cap=True,
)
is True
)
assert _active(seconds_since_start=_CAP + 1, base_timeout_seconds=extended, idle_timeout_seconds=extended) is False
assert (
seconds_until_expiry(
seconds_since_start=_CAP,
base_timeout_seconds=extended,
seconds_since_last_activity=None,
idle_timeout_seconds=extended,
budget_may_lift_cap=True,
)
== extended - _CAP
)
def test_the_lifted_cap_never_exceeds_the_extended_maximum() -> None:
runaway = MAX_EXTENDED_LIFETIME_SECONDS * 2
assert lifetime_cap_seconds(runaway) == MAX_EXTENDED_LIFETIME_SECONDS
assert lifetime_cap_seconds(_BASE) == MAX_LIFETIME_SECONDS
assert (
seconds_until_expiry(
seconds_since_start=MAX_EXTENDED_LIFETIME_SECONDS - 30,
base_timeout_seconds=runaway,
seconds_since_last_activity=0,
idle_timeout_seconds=runaway,
budget_may_lift_cap=True,
)
== 30
)
def test_creation_is_capped_so_only_an_extension_can_exceed_the_creation_cap() -> None:
assert creation_timeout_minutes(MAX_TIMEOUT + 60) == MAX_TIMEOUT
assert creation_timeout_minutes(90) == 90
assert creation_timeout_minutes(None) is None
def test_max_lifetime_exceeded_warning_states_the_request_and_the_grant() -> None:
warning = max_lifetime_exceeded_warning(90, 20)
assert "90 minutes" in warning
assert "20 minutes" in warning
assert str(MAX_EXTENDED_TIMEOUT) in warning
assert MAX_TIMEOUT_EXCEEDED_MESSAGE in warning
def test_session_is_active_matches_positive_remaining_time() -> None:
cases = (
(_BASE - 1, None),
(_BASE, None),
(_PAST_BASE, _IDLE - 1),
(_PAST_BASE, _IDLE),
(_CAP, 0),
)
for seconds_since_start, seconds_since_last_activity in cases:
remaining = seconds_until_expiry(
seconds_since_start=seconds_since_start,
base_timeout_seconds=_BASE,
seconds_since_last_activity=seconds_since_last_activity,
idle_timeout_seconds=_IDLE,
)
assert _active(
seconds_since_start=seconds_since_start,
seconds_since_last_activity=seconds_since_last_activity,
) is (remaining > 0)
async def _create_session(timeout: int | None) -> tuple[MagicMock, BrowserSessionResponse]:
app_mock = MagicMock()
app_mock.AGENT_FUNCTION.validate_enterprise_feature_access = AsyncMock()
app_mock.PERSISTENT_SESSIONS_MANAGER.create_session = AsyncMock(
return_value=SimpleNamespace(persistent_browser_session_id="pbs_1")
)
built_response = BrowserSessionResponse(
browser_session_id="pbs_1",
organization_id="org_1",
created_at=datetime(2026, 1, 1),
modified_at=datetime(2026, 1, 1),
)
from_browser_session = AsyncMock(return_value=built_response)
with (
patch.object(browser_sessions_routes, "app", app_mock),
patch.object(browser_sessions_routes.BrowserSessionResponse, "from_browser_session", from_browser_session),
):
response = await browser_sessions_routes.create_browser_session(
CreateBrowserSessionRequest(timeout=timeout),
current_org=SimpleNamespace(organization_id="org_1"),
)
return app_mock, response
@pytest.mark.asyncio
@pytest.mark.parametrize("timeout", [MAX_TIMEOUT + 1, 1440])
async def test_requested_timeout_above_the_cap_is_capped_with_a_warning(timeout: int) -> None:
app_mock, response = await _create_session(timeout)
assert app_mock.PERSISTENT_SESSIONS_MANAGER.create_session.await_args.kwargs["timeout_minutes"] == MAX_TIMEOUT
assert response.warning == max_timeout_exceeded_warning(timeout)
assert str(timeout) in response.warning
assert MAX_TIMEOUT_EXCEEDED_MESSAGE in response.warning
@pytest.mark.asyncio
@pytest.mark.parametrize("timeout", [MAX_TIMEOUT, 90, None])
async def test_requested_timeout_within_the_cap_is_passed_through_without_a_warning(timeout: int | None) -> None:
app_mock, response = await _create_session(timeout)
assert app_mock.PERSISTENT_SESSIONS_MANAGER.create_session.await_args.kwargs["timeout_minutes"] == timeout
assert response.warning is None
def test_requested_timeout_at_or_below_the_cap_is_preserved() -> None:
assert CreateBrowserSessionRequest(timeout=MAX_TIMEOUT).timeout == MAX_TIMEOUT
assert CreateBrowserSessionRequest(timeout=MIN_TIMEOUT).timeout == MIN_TIMEOUT
assert CreateBrowserSessionRequest(timeout=90).timeout == 90
def test_requested_timeout_below_the_minimum_is_still_rejected() -> None:
with pytest.raises(ValidationError):
CreateBrowserSessionRequest(timeout=MIN_TIMEOUT - 1)
def test_timeout_defaults_and_explicit_none_are_untouched() -> None:
assert CreateBrowserSessionRequest().timeout == DEFAULT_TIMEOUT
assert CreateBrowserSessionRequest(timeout=None).timeout is None
@pytest.mark.parametrize(
("lived_seconds", "expected"),
[
(60 * 60, True),
(60 * 60 - LIFETIME_END_TOLERANCE_SECONDS, True),
(60 * 60 - LIFETIME_END_TOLERANCE_SECONDS - 1, False),
(60, False),
],
)
def test_a_session_lived_its_full_lifetime_only_within_the_end_tolerance(lived_seconds: int, expected: bool) -> None:
started_at = datetime(2026, 9, 28, 13, 0, tzinfo=UTC)
ended_at = started_at + timedelta(seconds=lived_seconds)
assert lived_full_lifetime(started_at=started_at, ended_at=ended_at, timeout_minutes=60) is expected
assert not lived_full_lifetime(started_at=None, ended_at=ended_at, timeout_minutes=60)
assert not lived_full_lifetime(started_at=started_at, ended_at=ended_at, timeout_minutes=None)
def _ended_session(**overrides: object) -> PersistentBrowserSession:
started_at = datetime(2026, 9, 28, 13, 0, tzinfo=UTC)
fields: dict[str, object] = {
"persistent_browser_session_id": "pbs_x",
"organization_id": "o_test",
"status": "timeout",
"timeout_minutes": 60,
"started_at": started_at,
"completed_at": started_at + timedelta(minutes=60),
"created_at": started_at,
"modified_at": started_at,
}
return PersistentBrowserSession(**{**fields, **overrides})
@pytest.mark.parametrize(
("overrides", "expected"),
[
pytest.param({}, BrowserSessionExpired, id="timeout"),
pytest.param({"started_at": None}, BrowserSessionStartupTimeout, id="timeout-before-start"),
pytest.param(
{"status": "completed", "close_reason": BrowserSessionCloseReason.expired},
BrowserSessionExpired,
id="oss-reaper-full-lifetime",
),
pytest.param(
{
"status": "completed",
"close_reason": BrowserSessionCloseReason.expired,
"completed_at": datetime(2026, 9, 28, 13, 10, tzinfo=UTC),
},
BrowserSessionClosed,
id="expired-reason-stamped-early",
),
pytest.param({"status": "completed"}, BrowserSessionClosed, id="completed-by-the-caller"),
pytest.param({"status": "failed"}, BrowserSessionClosed, id="failed"),
pytest.param(
{"status": "running", "completed_at": None, "close_requested_at": datetime(2026, 9, 28, 13, 5, tzinfo=UTC)},
BrowserSessionClosed,
id="close-requested",
),
pytest.param({"status": "running", "completed_at": None}, type(None), id="live"),
],
)
def test_unusable_browser_session_error_tells_expiry_from_an_early_close(
overrides: dict[str, object], expected: type
) -> None:
error = unusable_browser_session_error(_ended_session(**overrides))
assert type(error) is expected
def test_submission_refusal_emits_a_structured_countable_event() -> None:
with capture_logs() as logs:
error = unusable_browser_session_error(
_ended_session(), refused_at_submission=True, submission_path="workflow_run"
)
assert isinstance(error, BrowserSessionExpired)
assert len(logs) == 1
assert logs[0]["event"] == "browser_session_run_refused"
assert logs[0]["error_code"] == "browser_session_expired"
assert logs[0]["browser_session_id"] == "pbs_x"
assert logs[0]["submission_path"] == "workflow_run"