fix: support appium_lib_core 13.x snake_case capabilities

[rishigupta1599]

Problem

appium_lib_core 13.x returns the session capabilities as an Appium::Core::Base::Capabilities object whose keys are snake_case (platform_name, device_screen_size, platform_version, …) instead of the camelCase keys (platformName, deviceScreenSize, platformVersion) that 12.x and earlier returned.

This silently broke Percy on core 13.x:

• MetadataResolver.resolve looked for platformName, didn't find it, and raised PlatformNotSupported.
• os_name, os_version, device_name, orientation, and deviceScreenSize all read nil.
• Net effect: the build was created but no snapshot was taken ("Snapshot command was not called").

Fix

Introduce two helpers on Percy::Metadata:

• normalize_capability_key(key) — lowercases and strips _/: and the leading appium vendor prefix, so platformName, platform_name, PLATFORM_NAME and appium:platformName all normalize to platformname.
• normalized_capabilities(driver) — coerces the capabilities object to a plain Hash (as_json/to_h) and builds a {normalized_key => value} view. First key wins, preserving the previous resolver precedence of platformName over platform_name.

The affected metadata reads (MetadataResolver, os_name, os_version, get_orientation, Android device_screen_size/_device_name, iOS device_name) now go through get_capability_value, which reads fresh on every call (no memoization — same call semantics as before).

The Android viewportRect / viewport reads are intentionally left unchanged — that path already falls back to driver.get_system_bars consistently across all appium versions, so it's out of scope for this fix.

Compatibility

• ✅ Backward compatible with appium_lib_core ≤ 12.x (camelCase).
• ✅ Forward compatible with appium_lib_core 13.x (snake_case).

Verification

• All 15 spec files pass (specs/*.rb).
• Real BrowserStack App Automate Percy build under appium_lib 16.3.0 (core 13.x) now takes the snapshot and finalizes green (previously failed with PlatformNotSupported / "Snapshot command was not called").

🤖 Generated with Claude Code

[rishigupta1599]

Claude Code PR Review

PR: #37 • Head: 600dd5a • Reviewers: stack:code-reviewer

Summary

Adds a casing/prefix-insensitive capability lookup (normalize_capability_key / normalize_hash / normalized_capabilities / get_capability_value) to Percy::Metadata and routes the metadata reads in metadata.rb, android_metadata.rb, ios_metadata.rb, and metadata_resolver.rb through it, fixing appium_lib_core 13.x which returns snake_case capability keys (platform_name, device_screen_size, …) instead of camelCase. Without the fix, resolution raised PlatformNotSupported and no snapshot was taken.

Review Table

Priority	Category	Check	Status	Notes
High	Security	No hardcoded secrets or credentials	Pass	None introduced
High	Security	Authentication/authorization checks present	N/A	SDK metadata code, no authz surface
High	Security	Input validation and sanitization	Pass	Caps coerced to Hash defensively (as_json/to_h/`
High	Security	No IDOR — resource ownership validated	N/A	No resource access
High	Security	No SQL injection (parameterized queries)	N/A	No DB access
High	Correctness	Logic is correct, handles edge cases	Pass	First-key-wins preserves platformName>platform_name precedence; nil-safe
High	Correctness	Error handling is explicit, no swallowed exceptions	Pass	os_version rescue is intentional and pre-existing
High	Correctness	No race conditions or concurrency issues	N/A	No shared mutable state added
Medium	Testing	New code has corresponding tests	Pass	Added normalize_capability_key + snake_case regression tests (Android/iOS/metadata)
Medium	Testing	Error paths and edge cases tested	Pass	camelCase, snake_case, SCREAMING, appium: prefix, symbol key all covered
Medium	Testing	Existing tests still pass (no regressions)	Pass	All 15 spec files green (32 metadata assertions)
Medium	Performance	No N+1 queries or unbounded data fetching	Pass	driver.capabilities is a local property; no remote calls
Medium	Performance	Long-running tasks use background jobs	N/A
Medium	Quality	Follows existing codebase patterns	Pass	Mirrors existing metadata helper style
Medium	Quality	Changes are focused (single concern)	Pass	Scoped to capability key resolution
Low	Quality	Meaningful names, no dead code	Pass
Low	Quality	Comments explain why, not what	Pass	Added rationale for viewportRect retention + colon-strip
Low	Quality	No unnecessary dependencies added	Pass	No new deps

Findings

All reviewer findings were either addressed in follow-up commit 600dd5a or are intentional/non-blocking:

• [Medium] android_metadata.rb viewportRect lookup left as capabilities.to_json[...] — Intentional and now documented in code. This path already degrades to driver.get_system_bars consistently across all appium_lib_core versions (the rect read yields a non-Hash, so the rect arithmetic rescues to nil and falls back), so it is out of scope for the snake_case fix. Addressed: clarifying comment added.
• [Low] Nested desired hash not normalized (device key missed for snake_case) — Fixed: _device_name now normalizes the nested desired hash via Percy::Metadata.normalize_hash, covering devicename and device regardless of casing.
• [Low] No memoization in get_capability_value — Intentional (documented): reads fresh each call to match prior behaviour. driver.capabilities is a local property, not a remote round-trip, so the cost is negligible.
• [Low] Test coverage gap for snake_case paths — Fixed: added regression tests for normalize_capability_key, os_name/os_version (snake_case platform_version), Android device_screen_size and nested desired device_name, and iOS device_name.
• [Info] normalize_capability_key strips all colons, not only the vendor-prefix one — Addressed: documented as intentional; safe for all known Appium capabilities.

Verification

• All 15 spec files pass (6 new regression tests added).
• Four real BrowserStack App Automate Percy builds under appium_lib 16.3.0 (core 13.x) take the snapshot and finalize green: #75, #76, #77, #78 (post-review-changes).

---

Verdict: PASS — correct, focused, backward-compatible fix with regression coverage; all review feedback addressed.