QA Toolkit is a set of tools for Software and QA Engineers to verify design implementation. It consists of two components: QA Toolkit application and QA Toolkit Bridge module. Both can be downloaded from releases page.
Once you install application follow instructions to configure QA Toolkit.
-
First you need to allow app to display over other apps. Depending on Android OS version and manufacturer of your device instead of QA Toolkit application settings system might open the list of apps that can request this permission. Find QA Toolkit app and grant access.
-
Then enable QA Toolkit Accessibility Service. Once again depending on Android OS version and manufacturer of your device system may open different screen. Find list of installed (downloaded) services and click on QA Toolkit.
-
Once you enable Accessibility Service and return back you should see a message informing that everything configured correctly. Also QA Toolkit overlay will become visible.
Initial Toolkit Bar menu has such elements:
- Drag icon. It allows to drag Toolkit Bar over the screen.
- Inspector tool icon that launches Inspector Tool.
- Grid tool icon that launches Grid Tool.
- Ruler tool icon that launches Ruler Tool.
- Rotate bar icon. It changes orientation of bar.
Inspector tool allows you to verify UI elements size and position. In advanced inspection you can also verify view attributes.
General inspection mode enabled by default and uses layout information available to Accessibility Service.
Once you launched Inspector Tool and selected UI element you will see its bounds, size and relative distances within parent layout.
Sometimes applications might have layouts that recognized by Accessibility Service but not visible to users. They will intercept touches and block you from selecting UI elements behind them. In such cases you need to follow next steps:
- Click on UI element that you're interested in. Inspector Tool will select overlay (invisible) view.
- Cycle through hierarchy using Layer icon until required UI element is selected.
In this example Home tab was selected by clicking on it. Inspector Tool found all UI elements at touch coordinates and sort them using their z-index. The top most element is selected by default and it has a layer number 17. So to select Home tab we need to cycle through layers by clicking Layer icon. In this case Home tab has a layer number 16. Depending on layout hierarchy of inspected app you may need to click Layer icon multiple times.
To inspect distances between two UI elements follow next steps:
- Select the first UI element.
- Click Pin icon to remember selected UI element.
- Select the seconds UI element.
After that Inspector Tool will display relative distances between edges of selected UI elements.
In case if distance equals to zero it will not be displayed.
By default sizes and distances measured in DPs (density-independent pixels) but you can also view them in PXs by clicking DP/PX icon.
Sometimes you may need to verify that size or distance depends on device screen's width and/or height. In this case you can toggle percentage mode by clicking Percentage Mode icon. Note that this mode uses real screen size ignoring system insets such as status/navigation bars, display cutouts, etc.
Sometimes UI element bounds or distances between edges are so small that they can't be displayed. For such cases you can use pinch gesture to zoom layout in or out.
By default Accessibility Service provides few attributes that can be viewed by clicking Details icon. In General Inspection mode you'll always see a warning icon. By clicking it Inspector Tool will provide an additional information about the reason why inspectable app can be inspected in General Inspection mode.
Advanced inspection available only for those applications that added QA Toolkit Bridge module. You can determine if advanced inspection available by checking Drag Icon. Small chain icon in the corner means that currently inspected application has QA Toolkit Bridge and can provide additional view attributes.
In the sample below you can see some preconfigured TextView and list
of its attributes such as Auto Size, Shadow, Paragraph and Compound
Drawables.
Sometimes you may inspect views that have their own implementation of
Accessibility Delegate. Usually such views draw their content on Canvas
on their own so they need to provide additional information about
their "virtual" children to Accessibility Service
(for example, CalendarView). Such views can't be inspected even in
Advanced Inspection mode. You will see a warning icon and a message
explaining why.
Both dimension and color attributes have different display modes. By clicking an attribute you can cycle through available modes. Size dimensions (like width, height, margin, padding, etc.) can be displayed as DP or PX and font sizes as SP and PX.
Colors can be displayed as HEX string or ARGB values (both integer and float).
Note: advanced inspection supports only View-based layouts.
This means that Jetpack Compose layouts will have only basic information
(similar to General Inspection mode).
You can add support of advanced inspection for custom or 3rd party views
by implementing your own InspectorConfiguration.
Additional details TBD.
Grid tool allows you to verify alignment of UI elements within a grid.
You can pan grid in any direction to adjust cells position. By default cells will remain at position where you leave them, but also you can configure grid to snap cells to screen edges. To do so toggle modes for start/end and top/bottom edges using corresponding toggles in Toolkit Bar menu.
- Don't snap at edges (default, horizontal and vertical edges accordingly).
- Snap horizontally (start and end edges accordingly).
- Snap vertically (top and bottom edges accordingly).
You can change cell size using pinch-to-zoom gesture or via settings.
Ruler tool allows you to check distances between multiple UI elements within a single orientation (horizontal or vertical). Note that this tool is less accurate than Inspector as rulers are not stick to UI elements' bounds. Consider using Ruler Tool for measuring distances between elements that doesn't have their own bounds (for example, line spacing in text, distance between compound drawables and text, etc.).
By default sizes and distances measured in DPs (density-independent pixels) but you can also view them in PXs by clicking DP/PX icon.
Sometimes you may need to verify that size or distance depends on device screen's width and/or height. In this case you can toggle percentage mode by clicking Percentage Mode icon. Note that this mode uses real screen size ignoring system insets such as status/navigation bars, display cutouts, etc.
You can add a new ruler by clicking Plus icon. This will pin previous ruler and display a single distance to top/bottom screen edge or another ruler (depending on position of currently active ruler). To remove a ruler you can click Minus icon or press Back.
You can change position of measurements by swiping screen. Direction of swiping depends on ruler orientation and current measurements position.
You can change sensitivity of ruler sliding using pinch-to-zoom gesture or via settings.
Ruler orientation can be changed only if there is only one ruler on the screen using rotate gesture.
QA Toolkit supports dark mode according to device settings.
Each mode have its own settings allowing you to configure application in the way you want. Color settings stored per light/dark mode.
TBD
The MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.