uitest(1) General Commands Manual uitest(1)
NAME
uitest - a script to run GUI tests against Etomo using JFCUnit
SYNOPSIS
scripts/uitest Test_Section_name
make -f tests/uitest.make [target ...]
etomo.uitest.JfcUnitTests
DESCRIPTIONf
Uitest is a script that runs JfcUnitTests. JfcUnitTests runs the etomo
application and interacts with it by using JfcUnit to grab named GUI
elements. Etomo automatically names most of its GUI elements.
JfcUnitTests gets its instructions from a set of autodoc files which
are read sequentially.
JfcUnits is the library used to manipulate GUI elements in Etomo. It
is an extension of JUnit which interacts with Java GUI elements.
JfcUnit is not adequate for demos or automation. It finds an element's
location on the screen and then accesses the element using its physical
location. If the element was moved during the lag time these two
events, manipulating the element will fail. Also, since JfcUnitTests
is not part of Etomo, it does not wait until a task is finished in
Etomo and can easily go too fast.
ENVIRONMENT
The IMOD environment that allows Etomo to be run must be in place.
IMOD_UITEST_DATA
Should be set to the directory where files that will be copied into
a test dataset are stored.
IMOD_UITEST_IMAGE_DATA
Should be set to the directory where images files that will be
copied into a test dataset are stored.
IMOD_UITEST_SOURCE
should be set the Etomo/tests directory.
Used by the Uitest Script
IMOD_JUNIT_HOME
Should be set to the directory containing the JUnit jar file.
IMOD_JUNIT_JAR
Should be set to the name of the JUnit jar file.
IMOD_JFCUNIT_HOME
Should be set to the directory containing the JfcUnit jar file.
IMOD_JFCUNIT_JAR
Should be set to the name of the JfcUnit jar file.
IMOD_JAKARTA_REGEXP_HOME
Should be set to the directory containing the Jakarta regexp jar
file.
IMOD_JAKARTA_REGEXP_JAR
Should be set to the Jakarta regexp jar file.
Used in Uitest.make
IMOD_UITEST_SCRIPT
Should be set the directory containing uitest.
Used by JfcUnitTests
IMOD_TEST_SECTION
Only needs to be set if JfcUnitTests is being run directly. It
should be set to the name of Test section that will be run (see
Section Relationships below).
FILES
Autodocs
The main uitest autodoc file is uitest.adoc. Test autodocs are
referred to by uitest.adoc. Function autodocs are referred to by Test
autodocs.
File Name Standardization
In order to use standard naming conventions and still keep backwards
compatibility Etomo sets an image file naming style. This can be set
for a new dataset with the Etomo parameter --namingstyle which
overrides the primary source: the IMOD_IMAGE_FORMAT environment
variable. File names will be automatically standardized when the old
style is not in force. Only the old-style names should be used when
writing tests. Files with a single backup suffix "~" are standardized
but files with more then one "~" suffix are currently not supported.
USAGE
Section Relationships
The uitest.adoc file contains Test, dataset, and interface sections. A
Test section contains descriptions of tests that will be run together.
A Test section refers to a single dataset section for information on
the dataset being tested. Each dataset section refers to one interface
section. A Test section also refers to at least one Test autodoc and
specifies a section type to be accessed in it. Sections specified by a
Test section are called Dialog sections, and are accessed one after
another. Sections may also be called like functions. Subsections with
a section type of if or ifnot act as simple if clauses.
Testing
The TestRunner class picks a Test Section based on the
IMOD_TEST_SECTION environment variable (set by uitest). Each Test
Section is associated with one dataset. A list of autodocs are added
to the section using the adoc command. Each autodoc is associated with
one Axis. The etomo.uitest.TestRunner class runs a test on each
autodoc in turn, based on the order they appear in the Test Section.
Each test will run until it starts to wait for a process, then it will
return control to TestRunner. The TestRunner will keep running tests
on each autodoc in turn until all tests in the autodoc have been
completed. This allows uitest to mimic the way a person might work
with Etomo - moving from one axis to another.
Grammer
Every possible combination of the grammer has not been implemented.
See individual commands in the following sections.
command
action = [value]
action[.modifier].field = [value]
action[.modifier].field.subcommand = [value]
action[.modifier].subject = [value]
action[.modifier].subject.field = [value]
action[.modifier].subject.subcommand = [value]
field = [value]
A field command has an implied action; for instance the
implied action for a button (bn) is to push it.
subcommand
subcommand_action[.modifier].field = [value]
subcommand_action[.modifier].subject = [value]
subcommand_action[.modifier].subject.field = [value]
action
assert, copy, end, format, if, get, goto, open, pause, print,
return, run, set, skipto, sleep, start, touch, unset, use, wait,
write
subcommand_action
assert, end, return, run, set, wait
modifier
always, contains, disabled, enabled, equals, exists, external, ge,
keep, le, not, not-equals, not-exists, optional, same, single, wait
subject
subject_type[.subject_name][.axis]
subject_type
adoc, axis, dataset, debug, dialog, dir, file,
frame, function, index, instance, image-file, interface,
param, process, section, test, testdir, tool, var
subject_name
Name of the subject. May contain variables. May not be a, b,
an subcommand_action string, or a field string.
axis
a or b. Default is single axis or all axes (depending on
context).
field
field_type.field_name[.index]
field_type
bn A button; the implied action is to press the button.
cb A check box; the implied action is to check the check box.
cbb A combo box; the implied action is to add an item to the
combo box and select it.
ctb.associated-field-name-(clear|select-file)
A control button; the implied action is to click the
control button. Control buttons have specific functions
donoted by the latter portion of their names.
cttb.associated-field-name-override
A control button; the implied action is to click the
control button. Control buttons have specific functions
donoted by the latter portion of their names.
ef An external function; the implied action is to run the
function.
file-chooser
A file chooser; the implied action is to open the file
chooser and fill in the file name.
hc A header cell. These are disabled, non-focusable buttons
used both in the header of a table and for text display in
table rows. There is no implied action for this field
type.
image-file-chooser
A file chooser that chooses an image file that must conform
to the current image filename style. The implied action is
to open the file chooser and fill in the file name.
l A label. A JLabel widget. There is no implied action for
this field type.
mb A mini-button; the implied action is to press the mini-
button.
mn A menu item; the implied action is to click on the menu
item.
pnl A panel; the implied action is to go to the panel.
popup
A popup; the implied action is to press a button on the
popup (specified by the value).
sp A spinner; the implied action is to either enter a number
into the spinner's text field or press one of its arrows.
ta A text area; the implied action is to enter text with
single/multiple line(s) into the text area.
tb A tab; the implied action is to click on the tab.
tf A text field; the implied action is to enter a string into
the text field.
field_name
Name of the field. May contain variables. See Naming.
index
An integer. Default: 0. Used when multiples fields of the
same type and name are present on a panel.
value
May contain a single value or a list divided by "|". May contain a
directory, file name, process result, command line parameter,
button state, or field value. See the Variables section.
text
number
boolean
Booleans are case insensitive
1
0
t
f
true
false
y
n
yes
no
on
off
mini-button_labels
+
-
A
B
>
<
spinner_arrow
up
down
Operators
| List separator. Only valid in values. Whitespace surrounding
separator is stripped.
" " Ignore variable operator. Valid everywhere.
%{ }
Reference to a variable. The current value of the variable is
substituted. Valid everywhere.
Precedence
|, " ", %{ }
Scope
Autodocs, sections, and subsections have scope. Settings defined in a
section are in force in that section and in any sections or autodocs
that are run from that section. So variables in a Test section are
global for the entire test. Variables set in a dataset section also
global for the entire test; as if they where set in a Test section.
The scope for settings in the global section of an autodoc is all the
sections in the autodoc and any sections or autodocs that are run from
them.
Variables
Variable are created by the set.var command and removed by the
unset.var command. They are refered to with the format
%{variable_name}. Variables set in uitest.adoc are global, except for
variables in the dataset that have axis a or b in the their subject;
these variables are global but limited to a single axis. Variable
references cannot exist inside of other variable references, but
variables references can be placed in variable values.
To avoid variable substitution, use double quotes (" "). The area
inside the quotes will no be changed and the quotes will be removed.
Examples:
set.var.axisbob = robert%{axis}
When the axis is b, %{axisbob} equals robertb.
assert.contains.file=log%{axis}.txt|"%{axis} is a variable"
When the axis is b, the assert statement becomes:
assert.contains.file=logb.txt|%{axis} is a variable
Built in variables
testdir
A global variable containing the test directory path, which is
created when the set.testdir command executed in a Test
section.
testdir-name
A global variable containing the test directory name, which is
created when the set.testdir command executed in a Test
section.
dataset
A global variable created when the set.var.dataset command is
executed in a Test section.
keep-dataset-dir
A global variable created when the set.keep.dataset command is
executed in a Test section.
axis
A variable created when a Test autodoc is executed. It is
global to the Test autodoc.
hdf This variable is created when the Etomo parameter namingstyle
is set to 2 in the current Test section. See the set.param
command. This variable is global to the Test autodoc.
Wildcards
"*" can be used to replace 0 or more characters in the literal_string
in assert.contains.file. "*" cannot match the end of the line.
Relative paths
The "/" separator must always be used for relative file paths. ".."
can be used to describe a file that is not in a subdirectory of the
test directory.
Waiting
The wait command creates a wait state in a tester and causes the tester
to wait until the situation specified in the wait command occurs. If
multiple Dialog autodocs where specified in the Test section, the
tester for the current Dialog autodoc will cease testing and the tester
for the next Dialog autodoc will continue where it left off whenever
there is a wait in the current tester.
Naming
To name a field in etomo, its associated label is changed to all lower
case, one "-" is substituted for each space or contiguious group of
spaces, everything from ":" or ";" on is truncated, and parenthesis and
angle brackets are removed, along with the string they enclose. Other
punctuation are also removed (quotes, periods, and commas). Dashes in
the original label are treated as whitespace, unless they're likely to
be minus signs.
The number of sections in a name is unlimited, except for separate
labels, which are limited to seven sections. To see the field names in
etomo, run etomo with the --names option. Field names will be printed
in the out log.
Panels with headers or boundary titles are named in the same way. The
exceptions are the top-level panels for the frames, which are always
called main-frame and sub-frame. Popups are identified by their
titles, which are turned into names the same way a label is.
Naming buttons with symbol labels
Buttons labeled with single characters or symbols such as >, B, or
+ are called mini-buttons (mb). They are labeled with the name
taken from panel or text field they are associated with. If there
are multiple buttons with the same name, for instance a +/- button
and an A/B button on the same dialog, use an index for all but the
first one, going left to right. The left-most mini-button has a
default index of 0.
Indexing
Multiple fields of the same type and name can be referred to with
an index. The index defaults to 0.
Order
Commands are always read in the order they are written, so order is
always meaningful. Don't use variables before setting them. In the
Test sections, always set the test directory and the autodocs before
setting the dataset. The only exception to this is the Interface
Section, where order does not count, except in its subsections.
The B Axis
The B axis is tested in the sub-frame (the second window). Tests will
automatically try to open their frame if an open.frame command is
placed in the interface section that is being used. If the frame can't
be opened the test will fail.
UITest Autodoc
uitest.adoc
Global Section
The area above all the sections. Commands are global to the test.
set.var.variable_name = [value]
Causes a variable called variable_name to be set to value.
Variables can be set anywhere in the this section and will be
available for use immediately. Variables set in the global Section
are in force for all tests. See Variables and Scope above.
Test Section
[Test = test_suite_name]
command
.
.
.
Required. Only valid in uitest.adoc. A section describing a suite
of tests which will run against a single dataset. Put
test_suite_name in the environment variable IMOD_TEST_SECTION to
run the test suite. There is one test directory and one dataset
per test. There can be multiple Test Autodocs per test suite (see
below). Order counts in this section. For best results order the
commands as they are ordered in this man page.
set.var.variable_name = [value]
Causes a variable called variable_name to be set to value.
Variables can be set anywhere in the this section and will be
available for use immediately. Variables set in the Test Section
are in force for the entire test. See Variables and Scope above.
It is usually important to create a global variable called dataset.
Set this variable before setting the dataset because it is usually
used in the Dataset section.
set[.keep].testdir = test_directory
Required. Only one is allowed. Give the location where the test
suites will be run. Test_Directory will be created under
./UITests. If the directory already exists and the keep modifier
was not used, the directory will be deleted and re-added. The keep
modifier makes it possible to test a partially completed dataset by
keeping the test_directory from being deleted. This command also
causes two global variables to be created: testdir, which contains
the directory path of the test directory, and testdir-name, which
contains the name of the test directory.
set.adoc.test_section_type[.(a|b)] = test_autodoc_name.adoc
Required. Creates a test. Sets a test autodoc for the test, and a
section type to be tested. It is also used to set the axis for the
test (a or b - the default is single axis). If more then one test
is being done, the axis letter will serve as a test name and must
be unique in the set.adoc commands in the Test section. The test
can be refered to by the axis letter set here. This axis letter is
also used in the Dataset section to copy the correct files for the
axis. test_autodoc_name.adoc should be placed in the directory
pointed to by the environment variable IMOD_UITEST_SOURCE.
set.dataset = dataset_dir
Required. Only one allowed. Causes the Dataset Section for this
test suite to be read and executed. See the Dataset Section below.
copy.file[.(a|b)] = file_name
Causes a file called file_name to be copied from dataset_dir (see
the Dataset Section header) to the testdir (see Test Section
above). The file will only be copied if the axis matches the axis
of one of the autodocs listed in the Test Section. If the
set.dataset command in the Test Section used the keep modifier,
then the file is only copied if it is not already in the testdir.
Must appear after the set.dataset command.
set.interface.interface_section_name =
Required to be in either the Test section or the Dataset section.
Sets the Interface Section associated with the dataset. Must
appear after the set.dataset command.
set.param = parameter
Causes etomo to be run with parameter added to the commmand line.
More then one set.param command can be used. Parameters will be
added to the command line in the order they appear in the Test
Section.
Examples
# Send the names of fields to the out log.
set.param = --names
# Open a existing dataset.
set.param = BB.edf
Dataset Section
[dataset = dataset_dir]
command
.
.
.
Required. Only valid in uitest.adoc. The section that describes
the dataset settings and files that will be copied into the
directory where the suite of tests will be run. Dataset_dir is a
set of two directories containing files that can be copied to the
test_directory (see set.testdir under Test Section). One directory
(the directory pointed to by the environment variable
IMOD_UITEST_IMAGE_DATA) contains the image files. The other
directory (the directory pointed to by the environment variable
IMOD_UITEST_DATA) contains non-image files. Order counts in this
section. For best results order the commands as they are ordered
in this man page.
copy.file[.(a|b)] = file_name
Causes a file called file_name to be copied from dataset_dir
(see the Dataset Section header) to the testdir (see Test
Section above). The file will only be copied if the axis
matches the axis of one of the autodocs listed in the Test
Section. If the set.dataset command in the Test Section used
the keep modifier, then the file is only copied if it is not
already in the testdir.
set.var.variable_name[.(a|b)]] = [value]
Causes a variable called variable_name to be set to value.
Variables set in the Dataset Section are in force for the
entire test. See Variables and Scope above. If the axis
letter is used then the variable is only set for that axis.
set.interface.interface_section_name =
Required to be in either the Test section or the Dataset
section. Sets the Interface Section associated with the
dataset.
use.dataset = dataset_dir
Take all the settings, except the dataset_dir, from another dataset
section.
Interface Section
[interface = interface_section_name]
command
.
.
.
Required. Only valid in uitest.adoc. A section describing an
interface. Currently there are four interface: Reconstruction,
PEET, Parallel-Processing, and Join. An Interface Section
describes how to open an interface. It also describes how to open
and go to the frames and dialogs used with the interface. The
commands in this section are not run in order; they are run when it
is time to manipulate an interface, frame, or dialog. This means
the commands are retrieved with a unique key. The portion of each
command which is used as the key (and must be unique in its
section) is enclosed in "<>" below.
<goto.frame[.(a|b)]>.field =
At least one goto.frame command is required. Contains the
field command to grab the main-frame or the sub-frame. This
command is run every time control is passed to an Autodoc
Tester once the open = interface subsection has been run once.
Only the command which matches the Autodoc Tester's axis will
be run, but If the axis is set, the version of goto-frame that
does not have an axis letter will be run first, and the the
axis version will be run. See Grammer above.
Example
goto.frame.pnl.main-frame =
<goto.frame[.(a|b)]>.run.optional.field =
At least one goto.frame command is required. Contains the
field command to grab or open the main-frame or the sub-frame.
This command is run every time control is passed to an Autodoc
Tester once the open = interface subsection has been run once.
Only the command which matches the Autodoc Tester's axis will
be run, but If the axis is set, the version of goto-frame that
does not have an axis letter will be run first (if it exists),
and the the axis version will be run. See Grammer above.
Example
goto.frame.a.run.optional.bn.axis-a =
goto.frame.b.run.optional.bn.axis-b =
<open.dialog.dialog_name>.field =
Optional. A command to open a dialog. Dialog_name is a
section name in a Test Autodoc (see below). The rest of the
command is the field command that must be executed to open the
dialog.
Example: open.dialog.PreProc.bn.pre =
open.tool.tool-name =
Opens a popup tool and returns the manager of the tool to the
test language interpretor. Tools should be opened this way
rather then via the menu field command, or the wrong manager
will be used in the test. Only one tool should be opened per
test. The manager associated with the last tool opened will be
used.
<[[open = interface]]>
command
.
.
.
[[]]
The Open Interface Subsection. Optional. Provides a way to
open interfaces which don't open automatically. The subsection
is automatically run one time when A axis or single axis test
loop starts. It does not use goto.frame command to grab the
panel, so a pnl field command should be the first command in
the subsection.
Example
[[open = interface]]
pnl.main-frame =
mn.tools =
mn.flatten-volume =
[[]]
Other Autodocs
autodoc_file_name.adoc
Test Autodoc
Test Autodocs are refered to by the set.adoc.test_section_type
command in the uitest.adoc Test Sections. Sections of
test_section_type will be tested in the order in which they appear
in a Test Autodoc. The tester is called the Autodoc Tester. The
sections being tested in this way are called Dialog Sections. A
variable called axis is created for each Test Autodoc.
Dialog Section
[test_section_type = dialog_section_name]
command
.
.
.
Required in a Test Autodoc. A Dialog Section describes a test
against a dialog or tab panel. Test_section_type must match a
set.adoc command placed in the Test Section being used. The
test_section_type/dialog_section_name combination must be unique in
the autodoc. This is because dialog_section_names are recorded
when their section is finished (see the wait.test command below).
Dialog Sections have their own scope. Order counts in this
section.
Function Section
[function_section_type = function_section_name]
command
.
.
.
A Function Section has its own scope and is called like a function;
the Autodoc Tester jumps to it, executes it, and then goes back to
the location where the call was made and continues from there. A
Function Section may be in the same autodoc as the Dialog Sections,
or it can be in a different autodoc. A Dialog Section can also be
called as a Function Section. See set.adoc and run.function,
below, for information on how to jump to a Function Section. Order
counts in this section.
assert.(bn|cb|cttb|rb).name[.index] = boolean
Tests whether boolean matches the state of the button, check box,
or radio button. Boolean refers to whether the button has been
pressed (a button that has been pressed is dark), the check box is
checked, or the radio button is selected.
assert.contains.(file|image-file) =
(file_name|relative_path)|literal_string
Tests whether a file in the test_directory called file_name
contains literal_string. All or part of the literal_string can be
quoted with double quotes (" ") to prevent variable substitution.
The wildcard (*) will work in literal_string. The literal_string
can only contain one line. Literal_string doesn't have to start at
the beginning of the line, or go on until the end of the line.
Note that the "|" is part of the command. It is used for making a
list of values. Using image-file will cause the file name to be
standardized if the Etomo parameter --namingstyle is set to 1 or 2.
assert.contains.(ccb|tf).text_field_name[.index] = search_pattern
Tests whether the text field or combo box value matches a search
pattern. The only special character valid for this search pattern
is *, which matches zero or more characters. It is not necessary
to put * at the beginning or end of the search pattern: partial
matches are allowed.
assert.(enabled|disabled).(bn|cb|cbb|ctb|cttb|l|mn|mb|rb|sp|tb|tf) =
Tests whether the field is enabled or disabled. Panels are not
valid for this command.
Example: assert.enabled.bn.compute-alignment =
assert.exists.(bn|cb|cttb|cbb|hc|l|l|mn|mb|rb|sp|tb|tf).field_name =
Tests whether the field exists and is visible.
assert.not-exists.(cb|cbb|cttb|hc|l|rb|sp|tf).field_name =
Tests whether the field doesn't exist, or isn't visible. Only
works with specified field types.
assert.(exists|not-exists).(file|image-file) =
(file_name|relative_path)
Tests whether a file exists or does not exist. File_name or
relative_path is assumed to be in the test_directory. See
set.testdir in UITest Autodoc. Using image-file will cause the
file name to be standardized if the Etomo parameter --namingstyle
is set to 1 or 2.
assert.(ge|le).tf.text_field_name[.index] = value
Tests whether the text field value is greater or equal to or less
then or equal to value.
assert.mb.associated_name[.index] = mini-button_label
Tests whether mini-button_label matches the current label of the
mini-button.
assert.not-equals.tf.text_field_name[.index] = [value]
Succeeds when the text field value is not equal to value. If
value is missing, succeedds when the text field is not empty.
assert.same.(file|image-file) =
(file_name|relative_path)[|compare_to_file_name]
Compare a file to another file. If compare_to_file_name is not
used, the file is compared to another file of the same name stored
in $IMOD_UITEST_DATA. If compare_to_file_name is used, the file is
compared to a file called compare_to_file_name, which is stored in
$IMOD_UITEST_DATA. Files are sorted and then compared line by
line, with comments and blank lines being ignored. File_name or
relative_path is assumed to be in the test_directory. See
set.testdir in UITest Autodoc. Using image-file will cause both
file names to be standardized if the Etomo parameter --namingstyle
is set to 1 or 2.
assert.hc.header_cell_name[.index] = [value]
Tests whether the text of the header cell is equal to value. If
value is missing, tests whether the header cell has no text.
assert.sp.spinner_name[.index] = number
Tests whether number equals the number in the text field of the
spinner.
assert.ta.text_area_name[.index] = [substring]
Tests whether a single line in the text area contains the
substring. If substring is missing, tests whether the text area is
empty.
assert.tf.text_field_name[.index] = [value]
Tests whether the text field value is equal to value. If value is
missing, tests whether the text field is empty.
bn.button_name[.index] =
Press a button called button_name. See Naming above.
(cb|cttb).name[.index] = [boolean]
Click a check box or control button called check_box_name. If
boolean is present, the check box will only be clicked if it is NOT
the same as boolean.
Example
# Turn on parallel processing if it not already on.
cb.parallel-processing = on
cbb.combo_box_name[.index] = value
Add a new value in a combo box and select it.
copy[.always].file = file_name[|to_file_name]
Causes a file called file_name to be copied from dataset_dir (see
UITest Autodoc - Dataset Section) to test_directory (see
set.testdir). If the set.testdir command in the Test Section used
the keep modifier, and always is not used in this command, then
only copy the file if it is not already in the test_directory.
end =
Ends the test of an axis. For a single axis test, the test
succeeds immediately. For dual axis, the other axis will continue.
If the other axis was waiting for the axis that ended, if will stop
waiting and start executing commands. So the end command can
violate dependencies created by wait.test. If an end command is
called for both axes, the test will succeed as soon as both axes
have reached the command.
file-chooser.file_chooser_name = file
Open a file chooser named file_chooser_name. Identifies the file
chooser by its title, which is converted to a name (see Naming).
When the file chooser appears, choose file and close the file
chooser.
Example
# Open a file chooser and add a section
bn.add-section =
wait.file-chooser.choose-a-section = %{dataset}3.rec
format[.field] =
Has Etomo format itself and then, optionally, executes field.
get.instance.class_tag =
Gets and saves an instance of a class that implements
ExternalUITestSuite. This instance will be used for all subsequent
external function calls. If the instance is newly constructed, it
will be initialized. Class_tag is a string used to identify the
class.
[[if[not] = variable_name]]
command
.
.
.
[[]]
If and Ifnot Subsections function like simple, non-nestable if
statements. They have their own scope. If Subsections are only
executed if the variable called variable_name has been defined.
Ifnot Subsections are only executed if the variable called
variable_name has not been defined. Variable_name may not start
with "=". The indentation is for readability and is not required.
if.enabled.field = [field_value]
Do the implied field action only if the field is enabled.
if.(enabled|disabled).field.subcommand = [subcommand_value]
If field is enabled/disabled, execute the subcommand.
if.(equals|not-equal).var.variable_name.subcommand = [variable_value]
Compares a variable called variable_name to variable_value using
either equals or not-equals. If the result is true, execute the
subcommand. If the result is false, continue without executing the
subcommand. Only subcommands without values can be used in this
statement.
if.not-exists.cb.field_name.subcommand =
Checks for the existance of a checkbox and executes the subcommand
if it does not exist. Currently not built out to handle exists or
other fields. Warning: this is not implemented for panels.
if[.not].var.variable_name.field = [field_value]
Execute a field command if a variable called variable_name has
either been defined or not been defined, depending on whether not
is used.
if[.not].var.variable_name.subcommand = [subcommand_value]
Execute a subcommand if a variable called variable_name has either
been defined or not been defined, depending on whether not is used.
image-file-chooser.file_chooser_name = image_file
Open a file chooser named file_chooser_name. Identifies the file
chooser by its title, which is converted to a name (see Naming).
When the file chooser appears, chooses image_file, modifying the
name to conform to the current image file name style, and closes
the file chooser.
mb.associated_name[.index] = [mini-button_label]
Press a mini-button. The mini-buttons are small, square
buttons with one of the following symbols on them: >, <, +, -,
A, or B. They are refered to by their associated_name, which
is the name of the panel they are on, or the field they are
related to. See Naming. Use index if there is more then one
mini-button with the same associated_name of the same name.
Mini-button are two-state buttons. If mini-button_label is
used, the button is only pressed if the button's current label
matches mini-button_label.
Examples
# Open the Parallel Processing panel.
mb.parallel-process = +
# Show less of the Parallel Processing panel.
mb.parallel-process.1 = <
# Show advanced fields in the Tilt panel
mb.tilt.1 = A
# Close the Trial Tilt panel
mb.trial-tilt = -
mn.menu_choice =
Click on a pull-down menu choice.
Examples
# Open a new PEET interface
mn.file =
mn.new-peet =
open.dialog.dialog_name =
Tells the autodoc tester that it must call the
open.dialog.dialog_name command in the current interface
section.
pause[.axis(a|b)] =
When pause pause is encountered a dialog will be popped up.
Both axes will be halted. The dialog will give three options:
ending the test and exiting, ending the test and leaving etomo
running, and continuing the test. When .axis.a or b is
included this will only happen on the matching axis - but both
axes will be halted.
print.var.variable_name = [variable_value]
Prints the value of a variable called variable_name to the
error log. See Variables above.
pnl.panel_name =
Go to a panel named panel_name. See Naming. It is usually
only a good idea to go to a panel associated with one of the
frames. The other panels are usually too limiting. For
instance a Done button will be outside of a dialog panel and
therefore unreachable.
Examples
pnl.main-frame =
pnl.sub-frame =
rb.radio_button_name[.index] =
Press a radio button called radio_button_name. If there are
multiple radio buttons of the same name, use index. See Naming
above.
return[.var.variable_name] =
Closes the current scope. If the return is used in a Dialog
Section, the current Dialog Section will end and the Autodoc
Tester will go on to the next Dialog section. If the return is
used in function section, the Autodoc Tester will leave the
section and go to the command following the function call. If
the return is used in a subsection, the Autodoc Tester will go
to the command after the end of the subsection. When
var.variable_name is used it also passes a local variable up to
the enclosing scope when it returns.
run.external.function.external_test_suite_function_name =
[string_parameter]
Runs the function called external_test_suite_function_name with
one optional String parameter in the current class instance set
by most recent get.instance command. IF the string parameter
is not used, a null parameter will be passed.
run.function.function_section_name =
Executes a section like a function; jumps to the other section,
executes it, and then jumps back. The function will be in the
file specified by the most recent set.adoc command. The
section type of the function must be set by a set.adoc command
prior to running the function. Functions contain the same
commands used in Dialog Sections. For exampes see set.adoc.
run.optional.field = field_value
Works just like a field command by itself, except that the
field command will not throw an exception. run.field is also
valid, but it does the same thing as the field command by
itself.
save =
Saves the dataset. Equivalent to mn.file followed by mn.save,
but more reliable for when it is the result of the save and not
the menu functionality that is being tested. Command is
ignored if the "Save" menu option is disabled.
set.adoc.function_section_type = [file_name.adoc]
Sets an autodoc containing sections that will be called like
functions using the run.function command. If file_name.adoc is
not used, then the command refers to the current autodoc.
function_section_type set the type of section that can be
called. Only the most recent set.adoc command in the current
scope remains in force. The Autodoc Tester looks for autodocs
in the directory pointed to by the environment variable
IMOD_UITEST_SOURCE.
Examples
# Call [dialog = PreProc] in current autodoc.
set.adoc.dialog =
run.function.PreProc =
# Call [function = main] in setup-recon.adoc.
set.adoc.function = setup-recon.adoc
run.function.main =
set.debug = boolean
Turns debug on and off. Debug causes any debug statements
available in the the test software and in Etomo to print.
Turning debug off may not completely stop debug prints because
class instances may have been created with debug while it was
on. Debug in Etomo can also be turned on by using the
set.param command in the Test Section. Turning debug off with
the set.debug command will always turn off debug in Etomo.
set.index.cbb.combo_box_name[.index] = index
Select an existing index in a combo box.
set.file.tf.text_field_name[.index] = file_name
Set the absolute path of file_name in a text field. Location
is the current directory and based on the Java user.dir
property, so it should be the same as the dataset directory.
set.var.variable_name = [variable_value]
Sets a variable called variable_name to variable value. To
refer to the variable later, use %{variable_name}. See
Variables above.
skipto.section.dialog_section_name =
For Dialog Sections only. Immediately exits the current Dialog
Section and jumps to a later Dialog Section called
dialog_section_name.
sleep = [time_in_milliseconds]
Tells the tester to sleep for time_in_milliseconds. The
default time is 1000.
sp.spinner_name[.index] = (number|spinner_arrow)
Changes the number in the spinner's editor panel or presses an
up or down arrow one time.
(sp|tf).table_label-row_label-
top_column_label[.index_within_column] = [value]
Works just like a regular field command and can be used in the
same places, except that the name and index refer to a field in
a table. Table_label is the name of the table. Row_label is
the name of the left most column in the table.
Top_column_label is the name of the header in the top row. See
Naming to learn how these names are created from the text
displayed on the dialog. The index_within_column is used when
columns share a top row header. The first column on the left
will have a default index of 0. This functionality has not
been implemented for all columns and tables.
Examples
# Fill in the rotation angles in the third row.
tf.section-table-3-rotation-angles.0 = 0
tf.section-table-3-rotation-angles.1 = 180
tf.section-table-3-rotation-angles.2 = 0
# Adjust the boundary between sections 2 and 3.
sp.boundary-table-2-&-3-adjusted = up
tb.first_tab_name[.index] =
Click on a tab. Tabs are all named after the first tab. The
rest must be referred to with index. See Naming above.
tf.text_field_name[.index] = [text|number]
Write value to a text field called text_field_name. If there
are multiple text fields of the same name, use index. See
Naming above.
popup.popup_name = popup_button_name
Use to identify a popup and dismiss it. Identifies the popup
by its title, which is converted to a name (see Naming).
Presses the button on the popup identified by
popup_button_name.
touch.dir = directory_name
Causes the last modified date of the directory called
directory_name in the test_directory (see set.testdir) to be
changed to the current date and time. If the directory doesn't
exist, this command creates an empty directory called
directory_name in the test_directory.
touch.file = file_name
Causes the last modified date of the file called file_name in
the test_directory (see set.testdir) to be changed to the
current date and time. If the file doesn't exist, this command
creates an empty file called file_name in the test_directory.
unset.var.variable_name =
Removes a variable called variable_name. A variable can only
be removed in the scope where it was created.
wait.popup.popup_name = popup_button_name
Used to wait for a popup dialog which will take some time to
appear. Good for finding popups that come up during a process.
Identifies the popup by its title, which is converted to a name
(see Naming). Presses the button on the popup identified by
popup_button_name.
wait.process.process_name = done|failed|killed|paused
Waits for a process to reach the specified end state. The
process_name comes from the string describing the process,
which appears at the top of the window when the process is
running (see Naming). The Autodoc Tester will wait until
process is done before comparing the value of this command to
the string in the progress bar. This command should only be
used for a single process, or the last process in a sequence.
wait.test.(a|b) = dialog_section_name
Causes the test to wait until another test has completed a
Dialog Section named dialog_section_name.
Example
# In the B axis, wait for Fine Alignment to complete in the
A axis.
wait.test.a = FineAlign
# In the A axis, wait for Tomogram Generation to complete
in the B axis.
wait.test.b = TomoGen
wait.tf.text_field_name[.index] = [value]
Waits for the text field value to be equal to value. If value
is missing, waits for the text field to be empty. Works like
an assert with an extended wait time.
write.file = file_name|literal_string
Append a new line and literal_string to file_name. Double
quotes (" ") can be used to avoid variable substitution.
EXAMPLES
Excerpt from a makefile (uitest.make) used to run multiple test suites
all: single dual
single:
$(IMOD_UITEST_SCRIPT)/uitest single
dual:
$(IMOD_UITEST_SCRIPT)/uitest dual
Test Section for a dual axis reconstruction
[Test = dual]
# Create a test directory called dual.
set.testdir = dual
# Use reconA.adoc as a Test Autodoc - axis set to "a".
set.adoc.dialog.a=reconA.adoc
# Use reconB.adoc as a Test Autodoc - axis set to "b".
set.adoc.dialog.b=reconB.adoc
# Use the dataset BB
set.dataset = BB
Using the same Test Autodoc for two Autodoc Testers
[Test = dual]
set.testdir = dual
# Use a "dialog" section type in recon.adoc for axis A.
set.adoc.dialog.a=recon.adoc
# Use a "bdialog" section type in recon.adoc for axis B.
set.adoc.bdialog.b=recon.adoc
set.dataset = BB
The Autodoc Tester for Axis A runs the sections with a section type
of "dialog". The Autodoc Tester for Axis B runs the sections with
a section type of "bdialog".
Using variables
[Test = single-montage]
set.testdir = single-montage
# Only need one Test Autodoc - axis is set to "".
set.adoc.dialog = recon.adoc
# Using midzone2 as the dataset.
set.dataset = midzone2
# Create a variable called single.
set.var.single=
# Create a variable called montage.
set.var.montage=
In recon.adoc use these variables to decide which radio buttons to
check and which processes to wait for.
AUTHOR
Sue Held
SEE ALSO
etomo, imodenv, pip.
IMOD 2/4/2009 uitest(1)