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.


   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 ":" on is truncated, and strings in parenthesis
       are removed.  To see the field names in etomo, run etomo with the
       --names option.  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|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.

        Bcbcttb).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)