choose

Class: matlab.uitest.TestCase
Package: matlab.uitest

Perform choose gesture on UI component

Syntax

choose(testcase,comp,option) choose(testcase,compNoOpts)

Description

choose(testcase,comp,option) performs a choose gesture on the specified item on the UI component comp.

choose(testcase,compNoOpts) performs a choose gesture on a UI component that does not require additional information, such as a tab or a tree node. For example, use this syntax to choose a specific tab, but use the previous syntax to choose a particular tab from a tab group.

Input Arguments

expand all

`testcase` — Instance of test case
`matlab.uitest.TestCase` object

Instance of the test case, specified as a matlab.uitest.TestCase object.

`comp` — Component to choose
UI component object

Component to choose during test, specified as a UI component object that supports a choose gesture. Components that support choose gestures include check boxes, knobs, switches, and drop-down lists.

Supported Component	Typical Creation Function
Button Group	`uibuttongroup`
Check Box	`uicheckbox`
Discrete Knob	`uiknob`
Drop Down	`uidropdown`
Knob	`uiknob`
List Box	`uilistbox`
Radio Button	`uiradiobutton`
Slider	`uislider`
State Button	`uibutton`
Switch (Rocker, Slider, Toggle)	`uiswitch`
Tab Group	`uitabgroup`
Toggle Button	`uitogglebutton`
Toggle Tool	`uitoggletool`

`option` — Item in UI component to choose
depends on component

Item in the UI component to choose. The data type of option depends on the type of component being tested. For example, if comp is a switch, option is a text or numeric value from the Items property of the switch. If comp is a check box or toggle tool, option is a logical value.

When a component has an Items property, option can be the value of an element in Items or an index to an element in Items. For example, for a default discrete knob, you can choose 'Medium' using a value for option that is either 'Medium' or 3.

`compNoOpts` — Component to choose without options
UI component object

Component to choose, specified as a UI component object that supports a choose gesture and does not require additional information. Components that support choose gestures include tabs and tree nodes.

Supported Component	Typical Creation Function
Tab	`uitab`
Tree Node	`uitreenode`

Examples

expand all

Choose Value on Discrete Knob

Create a discrete knob.

knob = uiknob('discrete');

A figure with a discrete knob. The knob value is 'Off'.

Create an interactive test case and choose the 'High' knob value. An animated blue dot performs the programmatic choose gesture.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(knob,'High')

A figure with a discrete knob. The knob value is 'High'.

View the value of the Items property on the knob.

knob.Items

ans =

  1×4 cell array

    {'Off'}    {'Low'}    {'Medium'}    {'High'}

Choose the 'Low' knob value by index. The knob moves from 'High' to 'Low'.

tc.choose(knob,2)

A figure with a discrete knob. The knob value is 'Low'.

Choose Multiple Items in List Box

Create a list box and enable multiple node selection.

listbox = uilistbox('Multiselect','on')

listbox = 

  ListBox (Item 1) with properties:

              Value: {'Item 1'}
              Items: {'Item 1'  'Item 2'  'Item 3'  'Item 4'}
          ItemsData: []
        Multiselect: 'on'
    ValueChangedFcn: ''
           Position: [100 100 100 74]

  Show all properties

A figure with a list box that has four items. Item 1 is chosen.

Create an interactive test case and choose items 1 through 3.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.choose(listbox,1:3)

A figure with a list box that has four items. Items 1 through 3 are chosen.

Choose items 1 and 3 using the values of the Items property.

tc.choose(listbox,{'Item 1','Item 3'})

A figure with a list box that has four items. Items 1 and 3 are chosen.

Choose Slider Value and Verify Change

Create a slider.

s = uislider;

Create an interactive test case and verify that the value of the slider button is 0.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifyEqual(s.Value,0)

Verification passed.

Choose a new slider value and verify the slider value changes. Since the framework mimics a user manipulating the component to an arbitrarily precisioned value, it is a best practice to use a tolerance to compare the actual and expected slider values.

expVal = 42;
tc.choose(s,expVal)
tc.verifyEqual(s.Value,expVal,'AbsTol',0.1)

Verification passed.

Choose Tab from Group and Verify Change

Create a figure with two tabs.

fig = uifigure;
group = uitabgroup(fig);
tab1 = uitab(group,'Title','Tab #1');
tab2 = uitab(group,'Title','Tab #2');

Create an interactive test case and verify that the selected tab title contains the substring '#1'.

tc = matlab.uitest.TestCase.forInteractiveUse;
tc.verifySubstring(group.SelectedTab.Title,'#1')

verification passed.

Choose tab 2 and verify that the selected tab changes.

tc.choose(group,'Tab #2')
tc.verifyEqual(group.SelectedTab,tab2)

Verification passed.

Compatibility Considerations

expand all

Indexing order has changed in choose gestures within button groups

Behavior changed in R2020b

You can choose a radio button or toggle button using the button label or its index inside the button group. Starting in R2020b, when you choose a radio button or toggle button using an index, the app testing framework indexes into the Buttons property of the ButtonGroup object. In previous releases, the framework indexes into the Children property of the ButtonGroup object. For example, create a button group that has six toggle buttons:

f = uifigure;
bg = uibuttongroup(f);
tb1 = uitogglebutton(bg,'Position',[11 165 140 22],'Text','One');
tb2 = uitogglebutton(bg,'Position',[11 140 140 22],'Text','Two');
tb3 = uitogglebutton(bg,'Position',[11 115 140 22],'Text','Three');
tb4 = uitogglebutton(bg,'Position',[11 90 140 22],'Text','Four');
tb5 = uitogglebutton(bg,'Position',[11 65 140 22],'Text','Five');
tb6 = uitogglebutton(bg,'Position',[11 40 140 22],'Text','Six');

This table shows the outcome of the choose gesture on a toggle button that is specified with index 2:

Test	Starting in R2020b	R2020a and Earlier
tc = matlab.uitest.TestCase.forInteractiveUse; tc.choose(bg,2)	MATLAB^® chooses toggle button `tb2`, which is the second element of the `bg.Buttons` array. The `tc.choose(bg,2)` syntax is equivalent to `tc.choose(bg,'Two')`.	MATLAB chooses toggle button `tb5`, which is the second element of the `bg.Children` array. The `tc.choose(bg,2)` syntax is equivalent to `tc.choose(bg,'Five')`.

Documentation

choose

Syntax

Description

Input Arguments

`testcase` — Instance of test case
`matlab.uitest.TestCase` object

`comp` — Component to choose
UI component object

`option` — Item in UI component to choose
depends on component

`compNoOpts` — Component to choose without options
UI component object

Examples

Choose Value on Discrete Knob

Choose Multiple Items in List Box

Choose Slider Value and Verify Change

Choose Tab from Group and Verify Change

Compatibility Considerations

Indexing order has changed in choose gestures within button groups

See Also

Topics

MATLAB Documentation

Support

Documentation

choose

Syntax

Description

Input Arguments

testcase — Instance of test case matlab.uitest.TestCase object

comp — Component to choose UI component object

option — Item in UI component to choose depends on component

compNoOpts — Component to choose without options UI component object

Examples

Choose Value on Discrete Knob

Choose Multiple Items in List Box

Choose Slider Value and Verify Change

Choose Tab from Group and Verify Change

Compatibility Considerations

Indexing order has changed in choose gestures within button groups

See Also

Topics

MATLAB Documentation

Support

`testcase` — Instance of test case
`matlab.uitest.TestCase` object

`comp` — Component to choose
UI component object

`option` — Item in UI component to choose
depends on component

`compNoOpts` — Component to choose without options
UI component object