[MattL1989]

Problem

start_recording_screen() is annotated -> bytes | str and stop_recording_screen() is annotated -> bytes. Both return the response value, which is decoded from JSON, so it can never be bytes. The drivers return the base64 video as a string. On Windows and macOS, start_recording_screen() returns nothing, which the Appium server sends as null.

With the old annotations, mypy accepts driver.stop_recording_screen().decode(), which raises AttributeError at runtime.

Several documented keyword arguments also differ from the keys the drivers read:

• The docstring says forcedRestart. All drivers read forceRestart.
• It says captureClick. The Windows and Mac2 drivers read captureClicks.
• It lists videoFilters for iOS, Windows and macOS. Only XCUITest reads videoFilters; Windows and Mac2 read videoFilter. The table at the top listed videoFilter for all three.
• It types bugReport as str. The Android driver types it as boolean.
• It says the maximum timeLimit is 3 minutes on Android and 10 minutes on iOS. The drivers allow 1800 s and 4200 s. It also says macOS allows up to 10000 s, but Mac2 enforces no maximum.

I checked each point against the driver source:

• Android (UiAutomator2 and Espresso both extend AndroidDriver): appium-android-driver/lib/commands/recordscreen.ts reads forceRestart, sets MAX_TIME_SEC = 60 * 30 and returns Promise<string>. lib/commands/types.ts has bugReport?: boolean.
• iOS: appium-xcuitest-driver/lib/commands/recordscreen.ts reads forceRestart and videoFilters, sets MAX_RECORDING_TIME_SEC = 4200 and returns Promise<string>.
• Windows: appium-windows-driver/lib/commands/record-screen.ts reads videoFilter, captureClicks and forceRestart (default true), sets a 600 s default and returns Promise<void> from startRecordingScreen.
• macOS: appium-mac2-driver/lib/commands/record-screen.ts reads the same keys as Windows, has no maximum and returns Promise<void> from startRecordingScreen.
• The Appium server turns an undefined result into null: formatResponseValue in packages/base-driver/lib/protocol/helpers.ts.

Fix

• Annotate start_recording_screen() as -> str | None and stop_recording_screen() as -> str, and update the Returns: sections to match.
• Rename forcedRestart to forceRestart and captureClick to captureClicks. Note that Windows and macOS default forceRestart to True.
• Mark videoFilters as iOS only, and add a videoFilter entry and table row for Windows and macOS.
• Type bugReport as bool.
• Correct the timeLimit maximums and remove the macOS maximum.

There is no runtime change. The stop_recording_screen edits do not touch the Usage block, so this merges cleanly with #1334.

Behaviour change: type-checker results change. Code that treats either result as bytes is now flagged, and code that uses the result of start_recording_screen() without handling None is flagged too.

Tests

• On master, mypy reveals bytes | str for start_recording_screen() and bytes for stop_recording_screen(), and accepts driver.stop_recording_screen().decode(). With this change it reveals str | None and str, and reports "str" has no attribute "decode".
• The existing unit tests already expect a str from stop and None from start.
• The edited RST table still parses with docutils.
• ruff check, ruff format --check, mypy appium and the full unit test suite pass.

🤖 Generated with Claude Code