Skip to content

Commit

Permalink
Address comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@mykola-mokhnach
mykola-mokhnach committed Nov 23, 2024
1 parent 4500ec4 commit b334f4c
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 76 deletions.
35 changes: 30 additions & 5 deletions docs/guides/elements-lookup-troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ each section contains visible symptoms with the list of their possible resolutio

## Symptom #1

The desired element is shown as part of a bigger container and is not distinguable in the page source tree.
The desired element is shown as part of a bigger container and is not distinguishable in the page source tree.
Sometimes the whole application view with all elements in it is visible as one single container.

## Resolutions To Symptom #1
Expand All @@ -26,6 +26,12 @@ with it in your applications from the official
Bear in mind, that this tutorial only describes apps based on official Apple frameworks, like UIKit or SwiftUI. If you
use a different framework to build the application's user interface, for example
[React Native](https://reactnative.dev/), then consider looking for framework-specific accessibility guidelines.
It is also possible that the source tree displayed in Xcode accessibility inspector differs from the tree geneerated
by XCTest. The best possible way to verify the page source generated by the latter is to check the output of the
[debugDescription](https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription) attribute
of the corresponding XCUIApplication element. XCUITest driver allows to perform a direct forwarding for this API by
using the [mobile: source](../reference/execute-methods.md#mobile-source) execute method with `format` set
to `description`.

### Check if this is a hybrid application

Expand Down Expand Up @@ -53,6 +59,25 @@ under test by flattening nested views. Check the corresponding [issue](https://g
for more details.
Deeply nested hierarchies might also be the reason for the element lookup slowness. Read the [Diagnosing WebDriverAgent Slowness](./wda-slowness.md) article to troubleshoot the latter.

### Make sure a valid active application is selected in WebDriverAgent

Sometimes, even if visually it looks like UI elements belong to the same application, they are referenced by
absolutely different apps. Moreover, the operating system
may change elements ownership in different versions. In the UI inspector it looks like visually the element
is visible, but no "real" accessibility control relies on it. Most frequent candidates for such behavior are:
- System alerts, for example camera or geolocation permission requests
- Quick access toolbars, for example the one where Wi-Fi or Bluetooth state could be changed
- Various RPC sheets, for example the Share To collection

WebDriverAgent is designed the way it only interacts with a single app hierarchy at the particular
moment of time. Such application is called `active`.
It is possible to switch between applications in runtime using
[mobile: activateApp](../reference/execute-methods.md#mobile-activateapp) API or
to provide a hint for WebDriverAgent on which application to prefer if multiple apps are running
using the [defaultActiveApplication setting](../reference/settings.md).
Check the [Troubleshooting guide](./troubleshooting.md) and/or
[Switching Between iOS Apps During a Test](https://appiumpro.com/editions/13-switching-between-ios-apps-during-a-test)
article for more details on how to make such elements available.

## Symptom #2

Expand All @@ -70,7 +95,7 @@ If the automation is too slow, e.g. the desired element disappears faster than `
then make sure your script is optimized for the maximum performance, e.g. optimal/fast element locators are used,
the application itself and driver settings are [adjusted](./wda-slowness.md) to perform optimally, etc.
There might be situations where the automation framework is already optimized, although the desired element is
a short-living one, for example some notification popup that only appears for a second and then is immidiely hidden.
a short-living one, for example some notification popup that only appears for a second and then is immediately hidden.
For such "special" elements consider using approaches different from `findElement`, for example post-test video recording analysis (video FPS should usually be enough to catch all short-living elements), or introducing special
application debug settings to change the behavior for such elements and make them stay visible for longer time, or
using non-UI-related assertions, like logs analysis or direct API calls.
Expand All @@ -85,8 +110,8 @@ is as close as possible to the environment where automated tests are being execu

## Symptom #3

The desired element is shown in the page tree, but its property value is not what expect it to be, for example it
is shown as visible while I don't see it or vice versa.
The desired element is shown in the page tree, but its property value is not as expected, for example, it
is shown as visible while one does not see it in the application interface or vice versa.

## Resolutions To Symptom #3

Expand Down Expand Up @@ -118,6 +143,6 @@ The final recommendation there would be:
[issue](https://github.com/appium/WebDriverAgent/issues) to its maintainers.
- If the value of an attribute that is a "custom" XCUITest attribute, like `visible` or `accessible`,
is different from what you expect then we, most likely, won't be able to help you. You may try
to improve the corresponding WebDrivergent sources, but keep in mind there are many automation
to improve the corresponding WebDriverAgent sources, but keep in mind there are many automation
tests around that rely on the current way these attributes are calculated, and we probably don't
want to break them.
138 changes: 70 additions & 68 deletions docs/guides/hybrid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,71 +65,73 @@ the web view context on session initialization by setting the `autoWebview`

### Examples


```java
// java
// assuming we have a set of capabilities
driver = new AppiumDriver(new URL("http://127.0.0.1:4723/"), options);

Set<String> contextNames = driver.getContextHandles();
for (String contextName : contextNames) {
System.out.println(contextName); //prints out something like NATIVE_APP \n WEBVIEW_1
}
driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1

//do some web testing
String myText = driver.findElement(By.cssSelector(".green_button")).click();

driver.context("NATIVE_APP");

// do more native testing if we want

driver.quit();
```

```ruby
# ruby_lib_core
# assuming we have a set of capabilities
@driver = Appium::Core.for(url: SERVER_URL, desired_capabilities: capabilities).start_driver
# ruby_lib
# opts = { caps: capabilities, appium_lib: { custom_url: SERVER_URL }}
# @driver = Appium::Driver.new(opts, true).start_driver

# I switch to the last context because its always the webview in our case, in other cases you may need to specify a context
# View the appium logs while running @driver.contexts to figure out which context is the one you want and find the associated ID
# Then switch to it using @driver.switch_to.context("WEBVIEW_6")

Given(/^I switch to webview$/) do
webview = @driver.available_contexts.last
@driver.switch_to.context(webview)
end

Given(/^I switch out of webview$/) do
@driver.switch_to.context(@driver.contexts.first)
end

# Now you can use CSS to select an element inside your webview

And(/^I click a webview button $/) do
@driver.find_element(:css, ".green_button").click
end
```

```python
# python
# assuming we have an initialized `driver` object for an app

# switch to webview
webview = driver.contexts.last
driver.switch_to.context(webview)

# do some webby stuff
driver.find_element(By.CSS, ".green_button").click

# switch back to native view
driver.switch_to.context(driver.contexts.first)

# do more native testing if we want

driver.quit()
```
=== "Java"
```java
// java
// assuming we have a set of capabilities
driver = new AppiumDriver(new URL("http://127.0.0.1:4723/"), options);

Set<String> contextNames = driver.getContextHandles();
for (String contextName : contextNames) {
System.out.println(contextName); //prints out something like NATIVE_APP \n WEBVIEW_1
}
driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1

//do some web testing
String myText = driver.findElement(By.cssSelector(".green_button")).click();

driver.context("NATIVE_APP");

// do more native testing if we want

driver.quit();
```

=== "Ruby"
```ruby
# ruby_lib_core
# assuming we have a set of capabilities
@driver = Appium::Core.for(url: SERVER_URL, desired_capabilities: capabilities).start_driver
# ruby_lib
# opts = { caps: capabilities, appium_lib: { custom_url: SERVER_URL }}
# @driver = Appium::Driver.new(opts, true).start_driver

# I switch to the last context because its always the webview in our case, in other cases you may need to specify a context
# View the appium logs while running @driver.contexts to figure out which context is the one you want and find the associated ID
# Then switch to it using @driver.switch_to.context("WEBVIEW_6")

Given(/^I switch to webview$/) do
webview = @driver.available_contexts.last
@driver.switch_to.context(webview)
end

Given(/^I switch out of webview$/) do
@driver.switch_to.context(@driver.contexts.first)
end

# Now you can use CSS to select an element inside your webview

And(/^I click a webview button $/) do
@driver.find_element(:css, ".green_button").click
end
```

=== "Python"
```python
# python
# assuming we have an initialized `driver` object for an app

# switch to webview
webview = driver.contexts.last
driver.switch_to.context(webview)

# do some webby stuff
driver.find_element(By.CSS, ".green_button").click

# switch back to native view
driver.switch_to.context(driver.contexts.first)

# do more native testing if we want

driver.quit()
```
7 changes: 4 additions & 3 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,20 +63,21 @@ nav:
- guides/run-prebuilt-wda.md
- guides/attach-to-running-wda.md
- guides/wda-custom-server.md
- guides/wda-slowness.md
- Driver Actions:
- guides/audio-capture.md
- guides/file-transfer.md
- guides/install-certificate.md
- guides/clipboard.md
- guides/touch-id.md
- guides/gestures.md
- Troubleshooting:
- guides/troubleshooting.md
- guides/elements-lookup-troubleshooting.md
- guides/wda-slowness.md
- Other:
- guides/tvos.md
- guides/input-events.md
- guides/troubleshooting.md
- guides/capability-sets.md
- guides/elements-lookup-troubleshooting.md
- guides/hybrid.md
- contributing.md

Expand Down

0 comments on commit b334f4c

Please sign in to comment.