{"record":{"id":"0e6a6eb512ee6aec","repo":"Textualize/textual","slug":"target-offset-is-outside-of-currently-visible-scre","errorCode":null,"errorMessage":"Target offset is outside of currently-visible screen region.","messagePattern":"Target offset is outside of currently-visible screen region\\.","errorType":"exception","errorClass":"OutOfBounds","httpStatus":null,"severity":"error","filePath":"src/textual/pilot.py","lineNumber":442,"sourceCode":"        if widget is None:\n            target_widget = screen\n        elif isinstance(widget, Widget):\n            target_widget = widget\n        else:\n            target_widget = screen.query_one(widget)\n\n        message_arguments = _get_mouse_message_arguments(\n            target_widget,\n            offset,\n            button=button,\n            shift=shift,\n            meta=meta,\n            control=control,\n        )\n\n        offset = Offset(message_arguments[\"x\"], message_arguments[\"y\"])\n        if offset not in screen.size.region:\n            raise OutOfBounds(\n                \"Target offset is outside of currently-visible screen region.\"\n            )\n\n        widget_at = None\n        for chain in range(1, times + 1):\n            for mouse_event_cls in events:\n                await self.pause()\n                # Get the widget under the mouse before the event because the app might\n                # react to the event and move things around. We override on each iteration\n                # because we assume the final event in `events` is the actual event we care\n                # about and that all the preceding events are just setup.\n                # E.g., the click event is preceded by MouseDown/MouseUp to emulate how\n                # the driver works and emits a click event.\n                kwargs = message_arguments\n                if mouse_event_cls is Click:\n                    kwargs = {**kwargs, \"chain\": chain}\n\n                if widget_at is None:","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/Textualize/textual/blob/06dbeef4bb70fb718236aa418ed658ef4667a126/src/textual/pilot.py#L424-L460","documentation":"Raised by Textual's Pilot when simulating mouse events at coordinates that fall outside the visible screen region. It is a test-time guard ensuring synthesized clicks target an actual on-screen position.","triggerScenarios":"Calling pilot.click(), pilot.mouse_down(), pilot.mouse_up(), or pilot.hover() with x/y offsets (or an offset plus a widget whose combined position) that exceeds the screen size (default 80x24 in tests).","commonSituations":"Clicking a widget near the right/bottom edge of a small default test terminal, or passing absolute coordinates larger than the test console dimensions without setting a custom size in run_test().","solutions":["Pass a selector or widget instead of raw coordinates and let Pilot compute the offset","Clamp coordinates to within screen.size","Run the test with a larger terminal: app.run_test(size=(100, 40))"],"exampleFix":"// before\nawait pilot.click(90, 30)\n// after\nasync with app.run_test(size=(120, 50)) as pilot:\n    await pilot.click(90, 30)","handlingStrategy":"validation","validationCode":"if Offset(x, y) in app.screen.size.region:\n    await pilot.click(x, y)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer selector-based clicks over raw coordinates","Set explicit test terminal sizes in run_test(size=...)","Assert widget regions before clicking near edges"],"tags":["testing","pilot","mouse","coordinates","textual"],"backgroundTag":"out-of-bounds-coordinates","analyzedSha":"06dbeef4bb70fb718236aa418ed658ef4667a126","analyzedAt":"2026-08-27T02:36:57.214Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}