Test Menus

Author: Jeff Dalton

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.

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>

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.

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>

Jeff Dalton <J.Dalton@ed.ac.uk>