Test Menus

Author: Jeff Dalton

Updated: Sun Mar 19 16:48:52 2006 by Jeff Dalton


1. Test-menu elements and file syntax

To use a test-menu file, have a command-line arg or .props file entry
test-menu=filename, e.g.:

  ip2 -test-menu=somedir/test-sequences.xml

The file contains a list; each element describes a single entry on
the test menu.  In outline, the file therefore looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<list>
   ...
</list>

Five types of entry are currently supported (although new types
can be defined):

TEST-ELEMENT = TEST-ITEM | TEST-SEPARATOR | TEST-SUBMENU
             | TEST-SEQUENCE | TEST-SEQUENCE-GENERATOR

TEST-ITEM ::=
   <test-item
         delay-before="INT">
      <menu-text>STRING</menu-text>
      <to-name>STRING</to-name>
      <contents>SENDABLE</contents>
   </test-item>

TEST-SEPARATOR ::=
   <test-separator />

TEST-SUBMENU ::=
   <test-submenu>
      <menu-text>STRING</menu-text>
      <test-items><list>TEST-ELEMENT...</list></test-items>
   </test-submenu>

TEST-SEQUENCE ::=
   <test-sequence>
      <menu-text>STRING</menu-text>
      <test-items><list>TEST-ITEM...</list></test-items>
   </test-sequence>

TEST-SEQUENCE-GENERATOR ::=
   <test-sequence-generator
         initial-delay="INT"
         delay-between="INT">
      <menu-text>STRING</menu-text>
      <template>TEST-ITEM</template>
      <to-names><list>...</list></to-names>
      <content-strings><list>...</list></content-strings>
   </test-sequence-generator>

A SENDABLE is an issue, activity, report, chat-message, or constraint.

Test-separators and test-submenus give some control over the
way tests are presented by a process panel.

Note that string-valued fields may be written as attributes instead of
as elements if the string is sufficiently simple.

Test items, sequences, sequence-generators, seperators and submenus
do not have to come from files.  They are ordinary Java objects that
can also be constructed in Java.  However, it is often more convenient
to specify them in XML.

In each of the above syntaxes, the menu-text is a string that is
displayed in the "Test" menu.  For a test-item only, any occurrence of
"$to" in the menu-text will be replaced by the value of the same
test-item's to-name.  (That is not done for a sequence, because the
messages in a sequence might be to different destinations.)

A to-name is the symbol/ipc name of the agent the test-item's
contents should be sent to.

The delay-before in a test-item is the number of milliseconds to wait
before sending the contents.  Delay-before defaults to 0.

Here is an example.

   <test-item
         menu-text="Give $to a report-back example issue"
         to-name="me">
      <contents>   
         <issue priority="high"
                report-back="yes">
            <pattern>
               <list>
                  <symbol>note</symbol>
                  <string>sample note text</string>
               </list>
            </pattern>
         </issue>
      </contents>
   </test-item>

That test-item would appear in the "Test" menu as "Give me a
report-back example issue" and when selected would send the
panel an issue with priority=high, report-back=yes, etc.

Here is a test-item that sends a report after a delay of 4 seconds:

   <test-item menu-text="Send $to a single report with a delay"
              to-name="me"
              delayBefore="4000">
      <contents>
         <report report-type="information"
                 text="Here's some information" />
      </contents>
   </test-item>

A test-sequence contains a list of test-items.  The menu-text
of those items is ignored (and needn't be specified).  The
test-sequences's own menu-text appears in the "Test" menu.

When the test-sequence is selected from the "Test" menu, it processes
the list of test-items in order.  For each item, it waits for the
item's delay-before milliseconds and then send's the item's contents
to the agent named by the item's to-name.  This allows a sequence
to send messages to a variety of different destinations.  By using
delay-before values of zero, it is possible to get several messages
to be sent (almost) at once.

Each item in a test-sequence may have a different type of contents.
That makes it possible to send an issue to one agent, a report to
another, and so forth.

However, in some cases, all of the items in a sequence will have
certain things in common; and then it may be possible to use a
test-sequence-generator.


2. Test-sequence-generators

A test-sequence-generator contains a single test-item that is used as
a template.  The menu-text of that item is ignored (and needn't be
specified), but all other fields may be significant.

A test-sequence-generator may contain either a list of to-names
or a list of content-strings, but not both.

If it contains a list of to-names, a sequence is constructed by making
a copy of the template for each of the to-names, replacing the copy's
to-name each time.  The resulting sequence will send essentially the
same message to a series of agents

If there is a list of content-strings instead, the sequence contains one
copy for each of the content-strings, with the "main contents" of the
copy replaced by the corresponding content-string, suitably interpreted.
This sequence will send a series of similar messages of the same type (issue,
report, or whatever) to a single agent: the agent specified by the to-name
of the template.

The interpretation of a content string depends on the class of the
template's contents.  If the template contains an issue or activity,
the content string is treated as a pattern and parsed in the usual way
(with ?names being variables etc); if the template contains a report
or chat-message, the content-string is placed in the object's text
field.  Constraints are not yet supported (although they may appear
in ordinary test-sequences.)

The test-items in the generated sequence have delay-before values
determined as follows: If the generator specifies an
initial-delay, it becomes the delay-before of the first item
in the generated sequence.  If the generator specifies a
delay-betweem, it becomes the delay-before of all subsequent
items in the sequence.  Otherwise, the template's delay-before
is preserved.

Here is an example that when selected will send a series of chat-messages:

   <test-sequence-generator initial-delay="0" delay-between="2000">
      <menu-text>
         <string>Send me some example chat messages</string>
      </menu-text>
      <content-strings>
         <list>
            <string>Sample chat text 1</string>
            <string>Sample chat text two</string>
            <string>More chat</string>
            <string>This time there will be
several lines of text
   and maybe some indentation
   just for variety
even though it's only an example.</string>
         </list>
      </content-strings>
      <template>
         <test-item>
            <to-name>
               <string>me</string>
            </to-name>
            <contents>   
               <chat-message />
            </contents>
         </test-item>
       </template>
   </test-sequence-generator>


3. Using the "Test" menu

Entries in the "Test" menu do not have to send messages.  They don't
even need to involve any of the objects described here.  However, 
this section will describe only the cases that can be specified by
a test-menu file.

If a single message is to be sent, without a delay, it is sent as soon
as its "Test"-menu entry is selected.  That is so regardless of whether
it came from a single test-item or from a 1-item sequence.

Otherwise, a new thread is created to supervise the message sending.
While that thread is running, the corresponding menu entry is prefixed
by "Stop: " and, if selected, stops the thread.  When the thread
terminates, the entry reverts to its original form.

However, all messages are actually sent by the GUI event thread
(just as in the normal operation of a panel).  The other thread exists
only to control the timing.

Messages sent to "me" are given directly to the panel rather than
going via the communication strategy.


4. A longer example

Note that in the first test-sequence-generator the template
contains a pattern that will be overwritten in the copies that
make up the generated sequence.  That was useful when testing
(to make sure the right thing happened) but may be undesirable
in an example.

Not also that the first list entries in the file do not specify
any delays, and so the messages will be sent as quickly as possible.

<?xml version="1.0" encoding="UTF-8"?>
<list>

   <test-sequence>
      <menu-text>
         <string>Send me some example issues</string>
      </menu-text>
      <test-items>
         <list>
            <test-item>
               <to-name>
                  <string>me</string>
               </to-name>
               <contents>   
                  <issue priority="high">
                     <pattern>
                        <list>
                           <symbol>note</symbol>
                           <string>sample note text</string>
                        </list>
                     </pattern>
                  </issue>
               </contents>
            </test-item>
            <test-item>
               <to-name>
                  <string>me</string>
               </to-name>
               <contents>   
                  <issue priority="low">
                     <pattern>
                        <list>
                           <symbol>consider</symbol>
                           <string>some other sample text</string>
                        </list>
                     </pattern>
                  </issue>
               </contents>
            </test-item>
         </list>  
      </test-items>
   </test-sequence>

   <test-sequence-generator>
      <menu-text>
         <string>Send me some example issues</string>
      </menu-text>
      <content-strings>
         <list>
            <string>Sample text 1</string>
            <string>Sample text two</string>
         </list>
      </content-strings>
      <template>
         <test-item>
            <to-name>
               <string>me</string>
            </to-name>
            <contents>   
               <issue priority="high">
                  <pattern>
                     <list>
                        <symbol>note</symbol>
                        <string>sample note text</string>
                     </list>
                  </pattern>
               </issue>
            </contents>
         </test-item>
      </template>
   </test-sequence-generator>

   <test-sequence-generator initial-delay="0" delay-between="2000">
      <menu-text>
         <string>Send me some example chat messages</string>
      </menu-text>
      <content-strings>
         <list>
            <string>Sample chat text 1</string>
            <string>Sample chat text two</string>
            <string>More chat</string>
            <string>This time there will be
several lines of text
   and maybe some indentation
   just for variety
even though it's only an example.</string>
         </list>
      </content-strings>
      <template>
         <test-item to-name="me">
            <contents>   
               <chat-message />
            </contents>
         </test-item>
       </template>
   </test-sequence-generator>

   <test-item menu-text="Send $to a single report with a delay"
              to-name="me"
              delay-before="4000">
      <contents>
         <report report-type="information"
                 text="Here's some information" />
      </contents>
   </test-item>

</list>

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
