Queries

Queries APIs

The queries APIs are probably where you'll spend most of your time, since the project's philosophy is to write a test as close as possible yo what a user see and does, these are the ways you can query the view hierarchy:

• *ByText - Filters the views based on their Text content.
  • Very useful to find labels and buttons.
• *ByAutomationId - Filters the views based on their AutomationId content.
  • Very useful when there is no easy way to differentiate elements on the screen. Also useful to make sure your app is accessible for people who use screen readers.
• *ByType - Filters the views based only on their type.
  • Useful when there are few elements of the same type on the screen.

Types of Queries

All the above queries can be combined with operators related to the number of elements that you expect on the screen. For example: if you are sure there is only 1 element with a given text on the screen, you can use GetByText. These are the available types of queries at the moment:

• Get* - Returns exactly 1 matching element, throws an exception if no element, or more than 1 element is found.
• Query* - Returns exactly 1 matching element, returns null if no element is found. Throws an exception if more than 1 element is found.
• GetAll* - Returns all matching elements on the screen, throws an exception if no element is found.
• QueryAll* - Returns all matching elements on the screen, returns an empty array if no element is found.

To make it easier to find the correct type of query, refer to this table:

Type of Query	0 Matches	1 Match	2+ Matches
GetBy*	Throws Exception	Returns the View	Throws exception
QueryBy*	Returns null	Returns the View	Throws exception
GetAllBy*	Throws Exception	Returns a List with the Views	Returns a List with the Views
QueryAllBy*	Returns an empty List	Returns a List with the Views	Returns a List with the Views

The single queries return a Xamarin.Forms View object, and the multiple queries return is a .NET List, so you can do anything you want with the result, like checking for a specific property (e.g.: IsVisible) or do more filtering (e.g.: First, Last, Skip, etc.).