appium-webdriveragent 16.1.3 → 16.1.4

package/WebDriverAgent.xcodeproj/xcshareddata/xcschemes/IntegrationTests_tvOS.xcscheme

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2600"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "NO"
+            buildForArchiving = "NO"
+            buildForAnalyzing = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "DE52ACA4B43F527189E374EE"
+               BuildableName = "IntegrationTests_tvOS.xctest"
+               BlueprintName = "IntegrationTests_tvOS"
+               ReferencedContainer = "container:WebDriverAgent.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "DE52ACA4B43F527189E374EE"
+               BuildableName = "IntegrationTests_tvOS.xctest"
+               BlueprintName = "IntegrationTests_tvOS"
+               ReferencedContainer = "container:WebDriverAgent.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "DE52ACA4B43F527189E374EE"
+            BuildableName = "IntegrationTests_tvOS.xctest"
+            BlueprintName = "IntegrationTests_tvOS"
+            ReferencedContainer = "container:WebDriverAgent.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "DE52ACA4B43F527189E374EE"
+            BuildableName = "IntegrationTests_tvOS.xctest"
+            BlueprintName = "IntegrationTests_tvOS"
+            ReferencedContainer = "container:WebDriverAgent.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

package/WebDriverAgentLib/Categories/XCUIElement+FBTVFocuse.m

@@ -36,12 +36,13 @@ int const MAX_ITERATIONS_COUNT = 100;
 
   FBTVNavigationTracker *tracker = [FBTVNavigationTracker trackerWithTargetElement:self];
   for (int i = 0; i < MAX_ITERATIONS_COUNT; i++) {
-    // Here hasFocus works so far. Maybe, it is because it is handled by `XCUIRemote`...
-    if (self.hasFocus) {
+    FBTVDirection direction = FBTVDirectionNone;
+    FBTVFocusState focusState = [tracker pollFocusState:&direction];
+    if (focusState == FBTVFocusStateFocused) {
       return YES;
     }
 
-    if (!self.exists) {
+    if (focusState == FBTVFocusStateGone) {
       if (error) {
         *error = [[FBErrorBuilder.builder withDescription:
                    [NSString stringWithFormat:@"'%@' element is not reachable because it does not exist. Try to use XCUIRemote commands.", self.description]] build];
@@ -49,7 +50,6 @@ int const MAX_ITERATIONS_COUNT = 100;
       return NO;
     }
 
-    FBTVDirection direction = tracker.directionToFocusedElement;
     if (direction != FBTVDirectionNone) {
       [[XCUIRemote sharedRemote] pressButton: (XCUIRemoteButton)direction];
     }

package/WebDriverAgentLib/Commands/FBElementCommands.m

@@ -346,15 +346,15 @@
 
 + (id<FBResponsePayload>)handlePressAndDragCoordinateWithVelocity:(FBRouteRequest *)request
 {
-  FBSession *session = request.session;
+  XCUIApplication *application = request.session.activeApplication;
   CGVector startOffset = CGVectorMake((CGFloat)[request.arguments[@"fromX"] doubleValue],
                                      (CGFloat)[request.arguments[@"fromY"] doubleValue]);
   XCUICoordinate *startCoordinate = [self.class gestureCoordinateWithOffset:startOffset
-                                                                    element:session.activeApplication];
+                                                                    element:application];
   CGVector endOffset = CGVectorMake((CGFloat)[request.arguments[@"toX"] doubleValue],
                                     (CGFloat)[request.arguments[@"toY"] doubleValue]);
   XCUICoordinate *endCoordinate = [self.class gestureCoordinateWithOffset:endOffset
-                                                                  element:session.activeApplication];
+                                                                  element:application];
   [startCoordinate pressForDuration:[request.arguments[@"pressDuration"] doubleValue]
                thenDragToCoordinate:endCoordinate
                        withVelocity:[request.arguments[@"velocity"] doubleValue]

package/WebDriverAgentLib/Info.plist

@@ -15,11 +15,11 @@
     <key>CFBundlePackageType</key>
     <string>FMWK</string>
     <key>CFBundleShortVersionString</key>
-    <string>16.1.3</string>
+    <string>16.1.4</string>
     <key>CFBundleSignature</key>
     <string>????</string>
     <key>CFBundleVersion</key>
-    <string>16.1.3</string>
+    <string>16.1.4</string>
     <key>NSPrincipalClass</key>
     <string/>
   </dict>

package/WebDriverAgentLib/Utilities/FBTVNavigationTracker-Private.h

@@ -7,6 +7,7 @@
  */
 
 #import <Foundation/Foundation.h>
+#import "FBXCElementSnapshot.h"
 
 #if TARGET_OS_TV
 
@@ -22,6 +23,15 @@
 
 - (FBTVDirection)horizontalDirectionWithItem:(FBTVNavigationItem *)item andDelta:(CGFloat)delta;
 - (FBTVDirection)verticalDirectionWithItem:(FBTVNavigationItem *)item andDelta:(CGFloat)delta;
+- (FBTVDirection)directionWithItem:(FBTVNavigationItem *)item
+                              delta:(CGFloat)delta
+                  positiveDirection:(FBTVDirection)positiveDirection
+                  negativeDirection:(FBTVDirection)negativeDirection;
+
+// Exposed for testing: the pure direction-math core of `-pollFocusState:`,
+// parameterized on the already-resolved focused element's snapshot so tests
+// can supply a fake one instead of a live query result.
+- (FBTVDirection)directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot;
 @end
 
 #endif

package/WebDriverAgentLib/Utilities/FBTVNavigationTracker.h

@@ -22,6 +22,19 @@ typedef NS_ENUM(NSUInteger, FBTVDirection) {
   FBTVDirectionNone   = 4
 };
 
+/**
+ Represents where the tracked target element currently stands with respect
+ to keyboard/remote focus, as of the last `-pollFocusState:` call.
+ */
+typedef NS_ENUM(NSUInteger, FBTVFocusState) {
+  // The target element currently has focus
+  FBTVFocusStateFocused,
+  // The target element could not be located in the accessibility tree anymore
+  FBTVFocusStateGone,
+  // The target element exists, but does not have focus yet
+  FBTVFocusStatePending,
+};
+
 NS_ASSUME_NONNULL_BEGIN
 
 @interface FBTVNavigationItem : NSObject
@@ -38,12 +51,24 @@ NS_ASSUME_NONNULL_BEGIN
 + (instancetype)trackerWithTargetElement: (XCUIElement *) targetElement;
 
 /**
- Determine the correct direction to move the focus to the tracked target
- element from the currently focused one
+ Determines whether the tracked target element currently has focus, whether
+ it still exists, and - if neither - which direction the focus should move
+ to get closer to it. Each of these is resolved with the cheapest available
+ accessibility round trip for what it's checking: `hasFocus`/`exists` are
+ single already-known-element checks, and the currently focused element (if
+ any) is found via a targeted `hasFocus == true` query rather than a whole-app
+ snapshot walk, whose cost scales with total app size/depth instead of with
+ the (typically 0-1) number of matches.
 
- @return FBTVDirection to move the focus to
+ @param direction Always reset to `FBTVDirectionNone` first, then set to the
+   suggested direction to move the focus to when the return value is
+   `FBTVFocusStatePending`. It is left as `FBTVDirectionNone` when the return
+   value is `FBTVFocusStateFocused`/`FBTVFocusStateGone`, or when the
+   currently focused element could not be determined yet - in the latter
+   case the caller should just retry on the next iteration.
+ @return The current focus state of the tracked target element
  */
-- (FBTVDirection)directionToFocusedElement;
+- (FBTVFocusState)pollFocusState:(FBTVDirection *)direction;
 
 @end
 

package/WebDriverAgentLib/Utilities/FBTVNavigationTracker.m

@@ -10,6 +10,7 @@
 #import "FBTVNavigationTracker-Private.h"
 
 #import "FBMathUtils.h"
+#import "FBXCElementSnapshotWrapper.h"
 #import "XCUIElement+FBCaching.h"
 #import "XCUIElement+FBUtilities.h"
 #import "XCUIElement+FBWebDriverAttributes.h"
@@ -56,17 +57,49 @@
   self = [super init];
   if (self) {
     _targetElement = targetElement;
-    CGRect frame = targetElement.wdFrame;
-    _targetCenter = FBRectGetCenter(frame);
+    _targetCenter = FBRectGetCenter(targetElement.wdFrame);
     _navigationItems = [NSMutableDictionary dictionary];
   }
   return self;
 }
 
-- (FBTVDirection)directionToFocusedElement
+- (FBTVFocusState)pollFocusState:(FBTVDirection *)direction
 {
-  XCUIElement *focused = XCUIApplication.fb_activeApplication.fb_focusedElement;
+  *direction = FBTVDirectionNone;
 
+  // `hasFocus`/`exists` are cheap, single-element live checks - each round
+  // trip only has to serialize the state of one already-known element, not
+  // an unbounded subtree, so there's no snapshot-walk win to be had here.
+  if (self.targetElement.hasFocus) {
+    return FBTVFocusStateFocused;
+  }
+  if (!self.targetElement.exists) {
+    return FBTVFocusStateGone;
+  }
+
+  // Likewise, a `hasFocus == true` predicate query only has to serialize its
+  // (typically 0-1) matches back over the round trip, unlike a whole-app
+  // snapshot walk, whose cost scales with total app size/depth.
+  XCUIElement *focusedElement = (XCUIElement *)XCUIApplication.fb_activeApplication.fb_focusedElement;
+  if (nil == focusedElement) {
+    // Nothing is focused yet (e.g. right after the app became active) - let
+    // the caller retry on the next iteration.
+    return FBTVFocusStatePending;
+  }
+
+  // The snapshot was already taken as a side effect of resolving the query
+  // above, so grab it for free instead of paying for a new round trip.
+  id<FBXCElementSnapshot> focusedSnapshot = focusedElement.lastSnapshot
+    ?: focusedElement.fb_cachedSnapshot
+    ?: [focusedElement fb_customSnapshot];
+  *direction = [self directionTowardsTargetFromFocusedElementSnapshot:focusedSnapshot];
+
+  return FBTVFocusStatePending;
+}
+
+- (FBTVDirection)directionTowardsTargetFromFocusedElementSnapshot:(id<FBXCElementSnapshot>)focusedSnapshot
+{
+  FBXCElementSnapshotWrapper *focused = [FBXCElementSnapshotWrapper ensureWrapped:focusedSnapshot];
   CGPoint focusedCenter = FBRectGetCenter(focused.wdFrame);
   FBTVNavigationItem *item = [self navigationItemWithElement:focused];
   CGFloat yDelta = self.targetCenter.y - focusedCenter.y;
@@ -83,7 +116,6 @@
       direction = [self verticalDirectionWithItem:item andDelta:yDelta];
     }
   }
-
   return direction;
 }
 
@@ -99,7 +131,7 @@
   if (nil != item) {
     return item;
   }
-  
+
   item = [FBTVNavigationItem itemWithUid:uid];
   [self.navigationItems setObject:item forKey:uid];
   return item;
@@ -107,32 +139,35 @@
 
 - (FBTVDirection)horizontalDirectionWithItem:(FBTVNavigationItem *)item andDelta:(CGFloat)delta
 {
-  // GCFloat is double in 64bit. tvOS is only for arm64
-  if (delta > DBL_EPSILON &&
-      ![item.directions containsObject: [NSNumber numberWithInteger: FBTVDirectionRight]]) {
-    [item.directions addObject: [NSNumber numberWithInteger: FBTVDirectionRight]];
-    return FBTVDirectionRight;
-  }
-  if (delta < -DBL_EPSILON &&
-      ![item.directions containsObject: [NSNumber numberWithInteger: FBTVDirectionLeft]]) {
-    [item.directions addObject: [NSNumber numberWithInteger: FBTVDirectionLeft]];
-    return FBTVDirectionLeft;
-  }
-  return FBTVDirectionNone;
+  return [self directionWithItem:item
+                            delta:delta
+                positiveDirection:FBTVDirectionRight
+                negativeDirection:FBTVDirectionLeft];
 }
 
 - (FBTVDirection)verticalDirectionWithItem:(FBTVNavigationItem *)item andDelta:(CGFloat)delta
 {
-  // GCFloat is double in 64bit. tvOS is only for arm64
-  if (delta > DBL_EPSILON &&
-      ![item.directions containsObject: [NSNumber numberWithInteger: FBTVDirectionDown]]) {
-    [item.directions addObject: [NSNumber numberWithInteger: FBTVDirectionDown]];
-    return FBTVDirectionDown;
+  return [self directionWithItem:item
+                            delta:delta
+                positiveDirection:FBTVDirectionDown
+                negativeDirection:FBTVDirectionUp];
+}
+
+- (FBTVDirection)directionWithItem:(FBTVNavigationItem *)item
+                              delta:(CGFloat)delta
+                  positiveDirection:(FBTVDirection)positiveDirection
+                  negativeDirection:(FBTVDirection)negativeDirection
+{
+  // CGFloat is double in 64bit. tvOS is only for arm64
+  NSNumber *positiveDirectionNumber = [NSNumber numberWithInteger:positiveDirection];
+  NSNumber *negativeDirectionNumber = [NSNumber numberWithInteger:negativeDirection];
+  if (delta > DBL_EPSILON && ![item.directions containsObject:positiveDirectionNumber]) {
+    [item.directions addObject:positiveDirectionNumber];
+    return positiveDirection;
   }
-  if (delta < -DBL_EPSILON &&
-      ![item.directions containsObject: [NSNumber numberWithInteger: FBTVDirectionUp]]) {
-    [item.directions addObject: [NSNumber numberWithInteger: FBTVDirectionUp]];
-    return FBTVDirectionUp;
+  if (delta < -DBL_EPSILON && ![item.directions containsObject:negativeDirectionNumber]) {
+    [item.directions addObject:negativeDirectionNumber];
+    return negativeDirection;
   }
   return FBTVDirectionNone;
 }

package/WebDriverAgentTests/IntegrationApp_tvOS/AppDelegate.h

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <UIKit/UIKit.h>
+
+@interface AppDelegate : UIResponder <UIApplicationDelegate>
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/AppDelegate.m

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "AppDelegate.h"
+#import "SceneDelegate.h"
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
+{
+  return YES;
+}
+
+- (UISceneConfiguration *)application:(UIApplication *)application configurationForConnectingSceneSession:(UISceneSession *)connectingSceneSession options:(UISceneConnectionOptions *)options
+{
+  UISceneConfiguration *configuration = [[UISceneConfiguration alloc] initWithName:@"Default Configuration" sessionRole:connectingSceneSession.role];
+  configuration.delegateClass = SceneDelegate.class;
+  return configuration;
+}
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/Info.plist

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>UILaunchScreen</key>
+	<dict/>
+	<key>UIApplicationSceneManifest</key>
+	<dict>
+		<key>UIApplicationSupportsMultipleScenes</key>
+		<false/>
+		<key>UISceneConfigurations</key>
+		<dict>
+			<key>UIWindowSceneSessionRoleApplication</key>
+			<array>
+				<dict>
+					<key>UISceneConfigurationName</key>
+					<string>Default Configuration</string>
+				</dict>
+			</array>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/WebDriverAgentTests/IntegrationApp_tvOS/SceneDelegate.h

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <UIKit/UIKit.h>
+
+@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>
+
+@property (strong, nonatomic) UIWindow *window;
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/SceneDelegate.m

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "SceneDelegate.h"
+#import "ViewController.h"
+
+@implementation SceneDelegate
+
+- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions
+{
+  UIWindowScene *windowScene = (UIWindowScene *)scene;
+  self.window = [[UIWindow alloc] initWithWindowScene:windowScene];
+  self.window.rootViewController = [ViewController new];
+  [self.window makeKeyAndVisible];
+}
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/ViewController.h

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <UIKit/UIKit.h>
+
+@interface ViewController : UIViewController
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/ViewController.m

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import "ViewController.h"
+
+static NSInteger const FBGridSize = 3;
+static CGFloat const FBCellSide = 200;
+static CGFloat const FBCellSpacing = 60;
+
+@interface ViewController ()
+@property (nonatomic, strong) UILabel *lastSelectedLabel;
+@end
+
+@implementation ViewController
+
+- (void)viewDidLoad
+{
+  [super viewDidLoad];
+  self.view.backgroundColor = UIColor.whiteColor;
+
+  UIStackView *rows = [UIStackView new];
+  rows.axis = UILayoutConstraintAxisVertical;
+  rows.spacing = FBCellSpacing;
+  rows.alignment = UIStackViewAlignmentCenter;
+  rows.translatesAutoresizingMaskIntoConstraints = NO;
+  [self.view addSubview:rows];
+
+  for (NSInteger row = 0; row < FBGridSize; row++) {
+    UIStackView *columns = [UIStackView new];
+    columns.axis = UILayoutConstraintAxisHorizontal;
+    columns.spacing = FBCellSpacing;
+    for (NSInteger column = 0; column < FBGridSize; column++) {
+      UIButton *cell = [self newCellWithIdentifier:[NSString stringWithFormat:@"cell_%ld_%ld", (long)row, (long)column]];
+      [columns addArrangedSubview:cell];
+    }
+    [rows addArrangedSubview:columns];
+  }
+
+  UIButton *disabledButton = [self newCellWithIdentifier:@"disabledButton"];
+  disabledButton.enabled = NO;
+  [rows addArrangedSubview:disabledButton];
+
+  self.lastSelectedLabel = [UILabel new];
+  self.lastSelectedLabel.accessibilityIdentifier = @"lastSelectedLabel";
+  self.lastSelectedLabel.text = @"none";
+  self.lastSelectedLabel.translatesAutoresizingMaskIntoConstraints = NO;
+  [self.view addSubview:self.lastSelectedLabel];
+
+  [NSLayoutConstraint activateConstraints:@[
+    [rows.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+    [rows.centerYAnchor constraintEqualToAnchor:self.view.centerYAnchor],
+    [self.lastSelectedLabel.centerXAnchor constraintEqualToAnchor:self.view.centerXAnchor],
+    [self.lastSelectedLabel.bottomAnchor constraintEqualToAnchor:self.view.bottomAnchor constant:-FBCellSpacing],
+  ]];
+}
+
+- (UIButton *)newCellWithIdentifier:(NSString *)identifier
+{
+  UIButton *cell = [UIButton buttonWithType:UIButtonTypeSystem];
+  cell.accessibilityIdentifier = identifier;
+  [cell setTitle:identifier forState:UIControlStateNormal];
+  cell.translatesAutoresizingMaskIntoConstraints = NO;
+  [cell.widthAnchor constraintEqualToConstant:FBCellSide].active = YES;
+  [cell.heightAnchor constraintEqualToConstant:FBCellSide].active = YES;
+  [cell addTarget:self action:@selector(didSelectCell:) forControlEvents:UIControlEventPrimaryActionTriggered];
+  return cell;
+}
+
+- (void)didSelectCell:(UIButton *)cell
+{
+  self.lastSelectedLabel.text = cell.accessibilityIdentifier;
+}
+
+@end

package/WebDriverAgentTests/IntegrationApp_tvOS/main.m

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <UIKit/UIKit.h>
+
+#import "AppDelegate.h"
+
+int main(int argc, char * argv[]) {
+  @autoreleasepool {
+      return UIApplicationMain(argc, argv, nil, NSStringFromClass(AppDelegate.class));
+  }
+}

package/WebDriverAgentTests/IntegrationTests_tvOS/FBTVFocusIntegrationTests.m

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <XCTest/XCTest.h>
+
+#if TARGET_OS_TV
+
+// `XCUIElement+FBTVFocuse` is a project-internal category (not exposed as a
+// Public framework header), so its two entry points are forward-declared
+// here rather than imported. The real implementation - the one this suite
+// exercises end to end against a live tvOS Simulator - is still the one
+// linked in from WebDriverAgentLib_tvOS.framework.
+@interface XCUIElement (FBTVFocuseForTesting)
+- (BOOL)fb_setFocusWithError:(NSError **)error;
+- (BOOL)fb_selectWithError:(NSError **)error;
+@end
+
+@interface FBTVFocusIntegrationTests : XCTestCase
+@property (nonatomic, strong) XCUIApplication *app;
+@end
+
+@implementation FBTVFocusIntegrationTests
+
+- (void)setUp
+{
+  [super setUp];
+  self.continueAfterFailure = NO;
+  self.app = [XCUIApplication new];
+  [self.app launch];
+  XCTAssertTrue([self.app.buttons[@"cell_0_0"] waitForExistenceWithTimeout:15]);
+}
+
+- (void)testSetFocusMovesFocusToADistantElement
+{
+  XCUIElement *target = self.app.buttons[@"cell_2_2"];
+  XCTAssertTrue(target.exists);
+  XCTAssertFalse(target.hasFocus);
+
+  NSError *error;
+  BOOL result = [target fb_setFocusWithError:&error];
+
+  XCTAssertTrue(result);
+  XCTAssertNil(error);
+  XCTAssertTrue(target.hasFocus);
+}
+
+- (void)testSelectMovesFocusAndTriggersTheElementsAction
+{
+  XCUIElement *target = self.app.buttons[@"cell_1_2"];
+  XCUIElement *statusLabel = self.app.staticTexts[@"lastSelectedLabel"];
+
+  NSError *error;
+  BOOL result = [target fb_selectWithError:&error];
+
+  XCTAssertTrue(result);
+  XCTAssertNil(error);
+  XCTAssertTrue(target.hasFocus);
+
+  NSPredicate *labelUpdated = [NSPredicate predicateWithFormat:@"label == %@", @"cell_1_2"];
+  XCTNSPredicateExpectation *expectation = [[XCTNSPredicateExpectation alloc] initWithPredicate:labelUpdated object:statusLabel];
+  [self waitForExpectations:@[expectation] timeout:5];
+}
+
+- (void)testSetFocusOnADisabledElementFails
+{
+  XCUIElement *disabled = self.app.buttons[@"disabledButton"];
+  XCTAssertTrue(disabled.exists);
+
+  NSError *error;
+  BOOL result = [disabled fb_setFocusWithError:&error];
+
+  XCTAssertFalse(result);
+  XCTAssertNotNil(error);
+  XCTAssertFalse(disabled.hasFocus);
+}
+
+@end
+
+#endif