## Summary of the Pull Request Updates our `UiaTextRange` to no longer treat the end of the buffer as the "document end". Instead, we consider the "document end" to be the line beneath the cursor or last legible character (whichever is further down). In the event where the last legible character is on the last line of the buffer, we use the "end exclusive" position (left-most point on a line one past the end of the buffer). When movement of any kind occurs, we clamp each endpoint to the document end. Since the document end is an actual spot in the buffer (most of the time), this should improve stability because we shouldn't be pointing out-of-bounds anymore. The biggest benefit is that this significantly improves the performance of word navigation because screen readers no longer have to take into account the whitespace following the end of the prompt. Word navigation tests were added to the `TestTableWriter` (see #10886). 24 of the 85 tests were failing, however, they don't seem to interact with the document end, so I've marked them as skip and will fix them in a follow-up. This PR is large enough as-is, so I'm hoping I can take time in the follow-up to clean some things on the side (aka `preventBoundary` and `allowBottomExclusive` being used interchangeably). ## References #7000 - Epic Closes #6986 Closes #10925 ## Validation Steps Performed - [X] Tests pass - [X] @codeofdusk has been personally testing this build (and others)
5.8 KiB
author | created on | last updated |
---|---|---|
Carlos Zamora @carlos-zamora | 2021-08-05 | 2021-08-05 |
Test Table Writer
The Test Table Writer was written as a method to generate UI Automation tests for OpenConsole. UI Automation has a lot of corner cases, so we developed this workflow to simplify storing and updating these test cases (particularly revolving around movement).
How to use it
- Update
UiaTests.csv
:- This file is used to store the tests in a compact format. The defined columns include...
- Degenerate: is this a degenerate range?
- Position: see the position chart below
- TextUnit: what text unit to move by
- MoveAmount: how many times to move
- Start: the start endpoint of the text range. Represented by a variable name used to signify a position in the buffer. See the variable heuristics section below.
- End: the start endpoint of the text range. Represented by a variable name used to signify a position in the buffer. See the variable heuristics section below.
- Result_MoveAmount: the expected amount to have moved by
- Result_Start: the expected position of the start endpoint after executing the move operation
- Result_End: the expected position of the end endpoint after executing the move operation
- Skip: skip the test. Can be used for failing tests.
- Each row represents a new test in a compact format.
- Use the position chart and the variable heuristics below to add more tests easily.
- This file is used to store the tests in a compact format. The defined columns include...
- Run
GenerateTests.ps1
GenerateTests.ps1
will loadUiaTests.csv
and export the tests and any necessary variables to "src\interactivity\win32\ut_interactivity_win32\GeneratedUiaTextRangeMovementTests.g.cpp".
- Build and run the tests
- Build UiaTextRangeTests
- Go to bin\x64\Debug
- Run
clear; .\TE.exe /name:*UiaTextRangeTests*GeneratedMovementTests* .\Conhost.Interactivity.Win32.Unit.Tests.dll
in PowerShell
- If the tests pass, upload any changes to
UiaTests.csv
andGeneratedUiaTextRangeMovementTests.g.cpp
. Be sure to run the code formatter.
Helpful tips
- How to verify a test is authored correctly
- use MS Word to generate some text (try typing "=lorem(5,5)" then pressing enter to generate text)
- use Accessibility Insights to run the UIA API on MS Word's ITextProvider
- if you create a selection (or move the cursor), then tell Accessibility Insights to get the "Selection" range (or refresh it), you can easily set up a test case
- Run the tests via Visual Studio
- In the Solution Explorer, right-click Interactivity.Win32.Tests.Unit and select "Set as Startup Project"
- right-click it again and select "Properties"
- In the Debugging section, set..
- "Command" -->
$(OutDir)/TE.exe
- "Command Arguments" -->
$(TargetPath) /name:*uiatextrange*generated* /inproc
- "Command" -->
Position chart
The text buffer is assumed to be partially filled. Specifically, the top half of the text buffer contains text, and each row is filled with 10 segments of alternating text. For visualization, the ascii diagram below shows what the text buffer may look like.
+------------------------------+
|1XX XXX X2X XXX XXX |
|XXX XXX XXX XXX XXX |
|XXX XXX X3X XXX XXX |
|XXX XXX XXX XXX XXX |
|XXX XXX X4X XXX XX5 |
|6 |
| |
| 7 |
| |
| 8|
+------------------------------+
9
The following positions are being tested:
origin
: buffer originmidTop
: middle of the top linemidHistory
: middle of the historymidDocEnd
: middle of the last line of textlastCharPos
: last character in the bufferdocEnd
: one past the last line of textmidEmptySpace
: middle of the empty space in the bufferbufferEnd
: end of the bufferendExclusive
: exclusive end of the buffer
This is intended to provide adequate testing coverage for GH#6986.
Variable Heuristics
Each position above already has a predefined variable name. However, a few heuristics are used to define new variables based on the standard variables above.
<name>Left
: the left-most position on the same line as<name>
<name>P<number>C
,<name>M<number>C
:<name>
: start at the position of<name>
P
(orM
): move forwards (aka "plus") by a certain amount (M
is used to move backwards [aka "minus"])<number>
: how much to move forwards byC
: move by character. For simplicity, assumes that each character is one-cell wide.
<name>P<number>L
,<name>M<number>L
:- same as above, except move by line. For simplicity, assumes that you won't hit a buffer boundary.
segment#L<name>
- This is mainly used for word navigation to target a segment of text in the buffer.
segment#
refers to the beginning of a segment of text in a row. The leftmost run of text issegment0
, whereas the rightmost run of text issegment4
.L<name>
refers to the line number we're targeting, relative to the<name>
variable. For example,Lorigin
means that the y-position should be that oforigin
.- Overall, this allows us to target the beginning of segments of text.
segment0Lorigin
andsegment0LmidTop
both refer to the beginning of the first segment of text on the top line (akaorigin
).
Helpful terms and concepts
- degenerate: the text range encompasses no text. Also, means the start and end endpoints are the same.
- TextUnit: a heuristic for how much to move by. Possible values include
TextUnit_Character
,TextUnit_Word
, andTextUnit_Line
. See https://docs.microsoft.com/en-us/windows/win32/winauto/uiauto-uiautomationtextunits for more details.