== Handling shadow DOM ==
TBD === What is shadow DOM? ===Basically, shadow DOM enables to encapsulate a DOM subtree in a document, without exposing its inner working to the main DOM tree. This makes marionette unable to see the elements under the shadow DOM, even if you can see it on WebIDE. For a concise explanation of shadow DOM, refer to [http://glazkov.com/2011/01/14/what- njparkthe-heck-is-shadow-dom/ this page]. === Python Marionette Methods ===Python Marionette handles shadow DOM issues by changing the frame with the command [http://marionette-client.readthedocs.org/en/latest/reference.html?highlight=shadow_root#marionette_driver.marionette.Marionette.switch_to_shadow_root switch_to_shadow_root()]. What this command does is to change the context into the shadow DOM, so you can view the elements within. Once you're done with shadow DOM elements, you have to return to the standard app frame by either switch_to_shadow_root() call without parameter, or self.apps.switch_to_displayed_app()<br><br>Note that a shadow DOMs can be nested, in which case you have to call switch_to_shadow_root() multiple times. Refer to [https://bugzilla.mozilla.org/show_bug.cgi?id=1194224#c9 this comment] for such case.<br><br>It's not always straightforward to see which ones are shadow DOM elements. Sure way to know it is when marionette cannot find the element that is being shown on WebIDE, then one of the parent element is a shadow DOM element. Also, when you call switch_to_shadow_root() method on a non-shadow DOM element, it will throw an error. === Example ===[http://mxr.mozilla.org/gaia/source/tests/python/gaia-ui-tests/gaiatest/apps/music/regions/ Music helper methods] contain a number of examples of shadow DOM usage. <source python> def tap_cover_in_player_view(self): # here, we switch to the active iframe view, and then switch into the shadow DOM within # because self._rating_view_locator is within the shadow DOM self.marionette.switch_to_frame(self.marionette.find_element(*self._active_view_locator)) self.marionette.switch_to_shadow_root(self.marionette.find_element(*self._cover_image_shadow_dom_locator)) # wait until the overlay disappears, and once the check is done, get out of the shadow root # but you'll be still inside the self._active_view_locator frame Wait(self.marionette).until(expected.element_not_displayed(*self._rating_view_locator)) self.marionette.switch_to_shadow_root() # after tapping the element, re-enter into the shadow DOM, and check for the self._rating_view_locator being displayed # self.apps.switch_to_displayed_app() exits both shadow DOM and the active iframe view self.marionette.find_element(*self._cover_image_shadow_dom_locator).tap() self.marionette.switch_to_shadow_root(self.marionette.find_element(*self._cover_image_shadow_dom_locator)) Wait(self.marionette).until(expected.element_displayed( Wait(self.marionette).until(expected.element_present(*self._rating_view_locator)))) self.apps.switch_to_displayed_app()</source>
== Switching frames and system frame ==
TBD - mwargers
