RU/development/qa/vcltesttool/developer

Declaration of OpenOffice.org for the TestTool

Introduction

To function properly, the TestTool needs to identify the menu items, dialogs, and controls in OpenOffice.org. The identification of these items for testing is not done automatically, but rather by developers through a process called Declaration. OpenOffice.org is nearly fully declared, with each new feature being declared as soon as the feature is added. However, discrepancies exist between the declaration of older and newer features. Older dialogs and controls are declared in German, whereas all new features are declared in English. As the declared names are only variables, you can use this documentation to correctly identify older features.

Types of Declaration

The TestTool can only be used on menu items, windows, dialogs,and controls that have been declared (see also:Internal Commands, Methods and Functions for TestTool). You can find the declarations in *.sid and *.win files in the .../global/sid and .../global/win directories.

There are five types of declarations in OpenOffice.org:

SlotID	Most menu items in OpenOffice.org have SlotIDs (short integer with max. 5 numbers) that are executed directly to call a function, open a dialog, and so on. However, these IDs cannot be used by the TestTool. Instead you can use the declaration names (longnames) for the SlotIDs that are listed in the *.sid –files contained in the ../global/sid directory.SlotIDs are not automatically generated during the OpenOffice.org process, but rather are assigned by developers when a new menu item is inserted.
HelpID	Most windows, dialogs, and controls automatically receive HelpIDs during the build process of OpenOffice.org. The HelpID is used to open the correct help topic for dialogs or controls in OpenOffice.org. The TestTool uses HelpIDs to identify an item in OpenOffice.org. HelpIDs cannot be used in a TestTool script. Instead, speakable names are declared in the *.win-files in ../global/win for identification. You can use any of the commands described in Internal Commands, Methods and Functions for TestTool on the items that are identified by a HelpID.File names that start with an e refer to items that are in English, whereas those that do not start with e are in German.
UniqueID	A developer can assign an UniqueID to an item in OpenOffice.org that does not have a HelpID, so that you can refer to the item a TestTool script. Please note that the TestTool internally treats HelpIDs as UniqueIDs.
UNO-Slot	Some newer menu items in OpenOffice.org (BASE or HELP) do not use SlotIDs, but rather UNO-slots (Universal Network Objects). The UNO-slots (For example, FileOpen_uno .uno:Open The name 'Open' is taken from the document: http://framework.openoffice.org: Documents & files - framework - Framework core - Documentation - Index of command names: from the column Command) are the declared the same way as SlotIDs and are listed in e_all.sid file in the ..\global\sid directory.
Schema sym:	To support every kind of textual Ids, and not just .uno:, [private:factory private:factory], service:, macro:, .HelpId: a new general schema is introduced: sym:Just put sym: in front of a textual ID and use it in the declaration.E.g.: in .sid file: test1 sym:.uno:test

Determining the SlotID of a Menu Item

Before you can determine the SlotID of a menu item in OpenOffice.org, you need to set the HELP_DEBUG environment variable to TRUE. Instead of the SlotID there could also be a textual ID, that can be used as well.

1. Do one of the following:
   1. On the Win32 platform, open a DOS window, type set HELP_DEBUG=TRUE, and then press Enter.
   2. On UNIX, open a terminal window (for example, xterm), type set HELP_DEBUG=TRUE, and then press Enter.
2. In the same window, type soffice.exe (Win32) or soffice to start OpenOffice.org.
3. Choose Tools - Options - Openoffice.org - General and ensure that the Tips and Extended Tips option is selected.
4. Open the menu containing the item that you want to determine the SlotID for and rest the mouse pointer over the item.The Extended Tip is displayed. To keep the Extended Tip open, press Ctrl+F2 or Shift+F1 (Help-What's this). The SlotID is displayed at the bottom of Extended Tip window (for example, if you choose Format - Character in Writer, the SlotID is displayed as swriter: .uno:FontDialog)

If you declared a SlotID using the method described in the Declaring a new menu item section of this chapter and receive an error similar to : UNO URL "slot:58991" could not be executed: No dispatcher was found. when you try to determine the SlotID, you must then use the following method to determine the SlotID: MenuGetItemId(iNumber as Integer).

Example:

For the Calc menu item Insert - Function list, where the SlotID is 58991 and the longname is HID_SC_FUNCTIONLIST, use this testtool-script:

DocumentCalc.UseMenu                'to access the menu bar
MenuSelect MenuGetItemId(4)         'to open the 4th menu Insert
print MenuGetItemId(12)             'to get the ID for the 11th entry from
                                    'the top including separators
print MenuGetItemText(MenuGetItemId(12)), MenuGetItemCommand(MenuGetItemId(12))
                                    'to verify it is the correct entry 

Currently this isn't a working example - you get the .uno: -slot and not the ID;This leads to the ID 26248 with the longname 'FID_FUNCTION_BOX'.

Determining the HelpIDs or UniqueIDs of Controls

Instead of using the SlotID method to determine the HelpIDs or the UniqueIDs of controls and dialogs, you can use the DisplayHID TestTool command or the ..\global\tools\declare.bas script. This script starts OpenOffice.org, but does not reset the application (that is, close open documents). This behavior allows you to open a dialog and then run the declare.bas script.

When you run the declare.bas script, the following window opens in OpenOffice.org:

Illustration I DisplayHID Window (TestTool) with declaration

To display the HelpID, the resource type number, and the title of the dialog (or control) , hold down the Display ID button (). In this example, the View - Zoom dialog in a Writer document was opened. The ID of the dialog is 10000, the resource type number is 316 and the title of the dialog is Zoom. The button has 2 modes; first mode: press the button and keep it pressed while moving the mouse to the object, release the button on the object. Second mode: press the button and release it. The mode is left by pressing the button again, or by pressing the shift key two times very fast and moving the mouse a little bit.For the same example, the following dialog opens in the TestTool:Note: This example contains German strings in the declaration.The complete dialog is declared in the TestTool environment. All entries have a name and no HelpID is displayed with the complete help text. If the dialog contains the line --0: EDIT: 90% No entries in hid.lst, at least one ListBox or another control is present in your dialog. A ListBox is an edit-field that has a button that you can use to display a list. The list contains one entry with an ID and another entry with a zero.

The Zoom dialog in the TestTool Environment is called Massstab, whereas the controls in the dialog are called GanzeSeite (=Entire Page), Seitenbreite (=Page width), and so on. These are the same names that are used in the test scripts that work with this dialog. Although the OK, Cancel, and Close buttons are in a global class for dialogs, they are not declared for each dialog. If you want to close a dialog that does not contain one of these standard buttons, you will need to find another method to the close the dialog.

In the Slots field, you can see which SlotIDs are declared for this dialog, for example, OL_Seitenansicht_Massstab is a declaration for a button on a toolbar, while ViewZoom is the slot that opens this dialog when you choose the menu item View - Zoom.

Illustration II DisplayHid Window (TestTool) without declaration.

This example is also for the Zoom dialog, but without the declaration. The asterisk (*) in front of the first entry indicates that the dialog is correctly defined in the TestTool Environment. The first column lists the names of the controls and the second column lists the resource type (in this example, radio buttons), the longname that was generated automatically by the OpenOffice.org build process, and the HelpIDs (not visible in this dialog). The longnames and HelpIDs are also listed in the hid.lst file.

Special Task: Set a temporary HelpID to a control

1. Run declare.bas.
2. Put the textcursor to the left in the small window with the red button text field '10000 WinType:....', by clicking with the mouse into it and using the 'cursor left' key.
3. Press the button in the window, to become red.
4. Go to the control you want to assign a HelpID with the mouse pointer, but don't click a mouse button, just move the mouse.
5. When the control is highligted, type the HelpID. The number shows up beside the red button.
6. End the red button mode by clicking the red button with the mouse.
7. Close the declare windows.
8. In the editor window of the file declare.bas, in the subroutine main, type your small script to use the control.

Declaring a New Menu Item

Declaring a new menu item is a three-step process: determining the UNO-Slot of the new menu item (see Determining the SlotID for a Menu Item section in this chapter), inserting the UNO-Slot in the e_all.sid file, and restarting the test script. Please note that English menu items are listed in the e_all.sid file and German menu items are listed in the all.sid file in the./global/sid directory. Only add new menu items to the e_all.sid file.

Example: Adding a new item to the View - Zoom menu.

1. Open a DOS or terminal window and type HELP_DEBUG=TRUE.
2. Start soffice.exe. If the Quickstarter is running, exit the Quickstarter.
3. Choose Tools - Options - Openoffice.org - General and ensure that the Tips and Extended Tips option is selected.
4. Open the View menu in a Writer document and rest the mouse pointer over the Zoom command.
   The name of the application and the UNO-Slot are displayed at the bottom of the Extended Tip window (in this example, swriter: .uno:Zoom).
5. Change to the ../global/sid directory, open the e_all.sid file, and go to the View section.
6. Add a new entry called ViewZoom, and paste the .uno:Zoom UNO-Slot behind the entry.
7. Save the e_all.sid file. The new menu item is added to the TestTool environment.

Declaring a New Dialog or Control

Example: Adding a new dialog or control to the View - Zoom menu item:

1. In OpenOffice.org, Choose View - Zoom.
2. In the TestTool, open the ../global/tools/declare.bas script and press F5 to run the script.
3. In OpenOffice.org, hold down the left mouse button and rest the mouse pointer over the DisplayHid dialog.
4. Release the mouse after the dialog is read. The DisplayHID dialog appears in TestTool.
5. Select all of the entries in the dialog and press copy.
6. In the ../global/win/... directory, open the edia_t_z.win file, where the leading e stands for English and dia stands for dialog, and the t_z stands for dialog names that start with T through Z. For tab pages (registers), a tab is added to the filename instead of dia. a_d means only names with leading a until leading d)
7. Paste the content of the clipboard into the open file.
8. Add an asterisk (*) as a separator in front of the dialog name Zoom and ensure that all the controls have names.

• For example:

*Zoom SID_ATTR_ZOOM
EntirePage svx:RadioButton:RID_SVXDLG_ZOOM:BTN_WHOLE_PAGE
PageWidth svx:RadioButton:RID_SVXDLG_ZOOM:BTN_PAGE_WIDTH
Optimal svx:RadioButton:RID_SVXDLG_ZOOM:BTN_OPTIMAL
Percent200 svx:RadioButton:RID_SVXDLG_ZOOM:BTN_200
Percent150 svx:RadioButton:RID_SVXDLG_ZOOM:BTN_150
Percent100 svx:RadioButton:RID_SVXDLG_ZOOM:BTN_100
Percent75 svx:RadioButton:RID_SVXDLG_ZOOM:BTN_75
Percent50 svx:RadioButton:RID_SVXDLG_ZOOM:BTN_50
Variable svx:RadioButton:RID_SVXDLG_ZOOM:BTN_USER
ReductionAsVariable svx:MetricField:RID_SVXDLG_ZOOM:ED_USER
 

You cannot use numbers or special characters in the names.

You can, however, use a plus sign (+) to refer to a dialog or a control that you previously declared. in other words, you only need to declare a dialog or a control once. A good example is the File - Open Dialog which is also used for Insert - Graphics.

• For example:

*GeneralFileDialog HID_EXPLORERDLG_FILE
UebergeordneterOrdner svtools:MenuButton:DLG_SVT_EXPLORERFILE:BTN_EXPLORERFILE_UP
NeuerOrdner svtools:ImageButton:DLG_SVT_EXPLORERFILE:TN_EXPLORERFILE_NEWFOLDER
...
+GrafikEinfuegenDlg GeneralFileDialog
Stil HID_FILEOPEN_IMAGE_TEMPLATE
Verknuepfen HID_FILEDLG_LINK_CB HID_IMPGRF_CB_LINK
Vorschau HID_FILEDLG_PREVIEW_CB HID_IMPGRF_CB_PREVIEW
Link HID_FILEDLG_LINK_CB
Preview HID_FILEDLG_PREVIEW_CB

About the hid.lst File

The hid.lst is a list that is automatically generated during the OpenOffice.org build process. The hid.lst contains longnames, SlotIDs, HelpIDs, and UniqueIDs.

An inherent problem of the OpenOffice.org declaration method is that IDs can change when a developer, for example, rearranges the order of controls in a dialog or adds a control to a dialog. As a result the same controls on the same dialog in two different versions of OpenOffice.org can have different IDs. However, the longname (unique name) of a control is automatically assigned during the build process. The longname only changes if the dialog is renamed or if the OpenOffice.org project is renamed.

The version of the hid.lst that was used by a script is listed in the header for the script in the result file. You only need to use a new hid.lst when new features are added to the OpenOffice.org GUI.

Location of the hid.lst file

The hid.lst is located in the program directory of your OpenOffice.org installation. Discussion about the future of the file: Build_Environment_Effort/HID_List

Viewing hid.lst errors

To view hid.lst errors that occur when you run an automated script or declare.bas, expand the second line in the resultfile called 'Reading the files'.

There are two possible hid.lst errors :

1. The hid.lst is corrupted (several errors in the declaration part of the result file).
2. The OpenOffice.org GUI has changed and the declaration is not correct. You have to check the dialogs with declare.bas (from qa/qatesttool/global/tools/).

The Structure of Test Scripts

Introduction

The script language for the TestTool is StarBasic, the OpenOffice.org form of BASIC (similar to VisualBasic). In addition to StarBasic, the TestTool has methods and commands for communicating with and controlling OpenOffice.org.To automate the TestTool using scripts, use the following guidelines:

• Start a test only when the application that you want to test is in its base state.
• Do not stop the complete test if an error occurs during a testcase.
• Print the results of a test to a file (=result file)

sub main

The start routine for a test script is not the same as the simple start routine for a BASIC script. The sub main keyword must be written in lowercase, with one space between the two words, otherwise only a normal BASIC script is started. The sub main routine makes an internal call to the LoadIncludeFiles function and must reside in same *.bas file as the function.

The LoadIncludeFiles function contains the main processes and routines that are required to start a test script:

sub LoadIncludeFiles                      'automatic start of LoadIncludeFiles
    use "global\system\inc\gvariabl.inc"  'includes the inc file that contains the most important global variables (g_variabl.inc)'includes the global library (master.inc)
    use "global\system\inc\master.inc"    
    Call GetUseFiles                      'calls the sub routine to get the information required for a test (sets global variables, starts the office, ...)
    gApplication = "WRITER"               'sets the global variable gApplication for the application that you want to test (here: Writer = Text document )
end sub

GetUseFiles

In GetUseFiles, the following actions are executed:

• Includes all important tooling files
• Loads complete declaration ( all *.sid and *.win files )

• Gets the environment information of the TestTool (for example, platform and system language)
• Gets the environment information of the OpenOffice.org (platform, system language, installation type [FAT or network], version, build number, installation path(s), language, and so on)
• Sets all applicable global variables
• Adjusts some important settings in OpenOffice.org
• Creates the header in the result file
• Starts OpenOffice.org

The GetUseFiles subroutine was written especially for the TestTool and is contained in the master.inc in the ../global/system/inc directory. The TestTool can only work after this subroutine is run.

testcase ... endcase

A tested area (testcase) should be as small as possible, for example, one feature or one dialog. This way, if a testcase fails, the remainder of the test script can still be executed. Insert each testcase into a testcase ... endcase routine. If an error occurs during the testcase routine, the OpenOffice.org state is recovered to a known state.

When the test script reaches a testcase routine, the testenter subroutine is automatically called. The testenter subroutine checks the base state of OpenOffice.org, automatically closes any open dialogs and all but one document window. The subroutine then copies the associated error messages to the result file.

Similarly, when the test script reaches the endcase routine, the testexit subroutine is automatically called to check and recover the last known base state of OpenOffice.org. The subroutine then copies the associated error messages to the result file.

If an error occurs during a test process, the testcase stops and jumps directly to the testexit subroutine. All errors are written to the result file. If an error occurs outside the testcase ... endcase structure, the test script stops executing.

The testcase ... endcase construction must be used for each testcase. Use this construction in the same way as a sub- or function-routine.

The testenter and testexit routines are located in ../global/system/inc/master.inc.

Note: The words testcase and endcase are keywords and must be written in lowercase. Do not use these words in documentation strings or in any other strings in the script.

Note: Never exit a testcase with 'exit sub', 'return', or with any command that does not call the TestExit sub routine. If you do, then no cleanup is performed. Instead, use goto endsub to recover the OpenOffice.org application that you are testing.

try ... catch ... endcatch

To avoid a known OpenOffice.org problem in a test script, do not test the affected area with the test scrip, otherwise use try-catch-endcatch. If an error occurs in the try-part of the script, the script automatically jumps to the catch-part and not to the recovery section of the testexit routine. If you do have a method to handle the error in the the catch-part of the test script, the test breaks and the script automatically jumps to the testexit-routine of endcase.

You can only branch this method once, that is, you can also use one try-catch-endcatch construction in the try-part and in the catch-part.

try
    ...
    try
        ...
    catch
        ...
    endcatch
    ...
catch
    ...
    try
        ...
    catch
        ...
    endcatch
    ...
endcatch

Note: try, catch, and endcatch are keywords and as such, cannot be used in documentation strings or as variables in the BASIC-scripts.

Only use the try-catch-endcatch construction when you need to circumvent a problem in a long test script. In all other instances, it is better to run into an error and then use the TestTool to recover the test.

sub and function

You can use sub and function routines in test scripts in the same way as in BASIC. You can call the routines from any part of the test script, including testcases, and try-catch-endcatch constructions.

All Supported Languages

The following languages are supported by the OpenOffice.org build process. To create a language dependent testcase, use the corresponding Tel.-Code number for a select case function.

Language	Tel.-Code	Num.-Code	ISO-Code	Asian	CTL
English (US)	01	1033	en-US
English (GB)	44		en-GB
German	49	1031	de
Greek	30	1032	el
Finnish	35	1035	fi
Hungarian	36	1038	hu
Czech	42	1029	cs
Slowak	43	1051	sk
Danish	45	1030	da
Norwegian	47	1044	no
Brazil (Port.)	55	2070	pt-BR
Korean	82	1042	ko	*
Turkish	90	1055	tr
Arabic	96	1025	ar		*
Hebrew	97	1037	he		*
Russian	07	1049	ru
Polish	48	1045	pl
Japanese	81	1041	ja	*
Chinese (simplifiled)	86	2052	zh-CN	*
Chinese (traditional)	88	1028	zh-TW	*
Portuguese	03	2070	pt
Dutch	31	1043	nl
French	33	1036	fr
Spanish	34	1034	es
Italian	39	1040	it
Swedish	46	1053	sv
Catalan	34c / 37		ca
Afrikaans	31b		af
Thai	66		th		*
L10N-Framework	99		ISO_CODE
Hindi	91		hi-IN		*

---

Testcase Documentation in Test Scripts

Description

Documentation for the automated test scripts is created using a separate tool that is currently not open sourced.

The documentation is put into a database and is also used for the status page feature. This feature allows you to click on an error and view the documentation for the testcase in which the error occurred. You can also insert the number of known errors and warnings in the header of each file. You can then change the state of a test result if you know that a certain bug will not be fixed for the next release.

Documentation can only be inserted in testcase, sub,and function routines. Any documentation that is inserted outside of these routines cannot be parsed by ttDocs.exe.

If you want include documentation for a test in the database, you need to use the same standards that were created for *.bas- and *.inc files.

The *.bas files

Each *.bas file requires a header, for example:

(... cut ...)
'* The Initial Developer of the Original Code is: Sun Microsystems, Inc.
'*
'* Copyright: 2000 by Sun Microsystems, Inc.
'*
'* All Rights Reserved.
'*
'* Contributor(s): _______________________________________
'*
'*
'/*******************************************************************
'*
'* owner : owner@foo.bar
'*
'* short description : only a short description for this test
'*
'\*******************************************************************

Underneath the SISL/LGPL header in your file, use a forward slash (/) to start the documentation header. Include the owner of this test and a short description (max. one line) of the test in the header. End the header with a backward slash (\).

You only need to document the sub main routine in the *.bas-file as this file does not contain any other testcases, functions, or sub routines. In the sub main routine, include all the *.inc-files that you want to use for the test. Do not use a single quote (') at the beginning of a file name to exclude the file from the documentation as this also excludes the file from the test. Thus, if you want to have complete documentation, only use the single quote on calls for the testcases in this routine.

Example:

sub main use "framework\options\inc\opt_tool.inc" use "framework\options\inc\opt_so_1.inc" use "framework\options\inc\opt_so_2.inc" use "framework\options\inc\opt_so_3.inc" use "framework\options\inc\opt_lan1.inc" call hStatusIn ("framework", "f_opt.bas") call opt_so_1 call opt_so_2 ' call opt_so_3 call opt_lan1 call hStatusOut end sub	All files that are included with 'use ...' can now be parsed by ttDocs. You do not need to include global inc-files. Only include the files that are required for the test.The test runs opt_so_1, opt_so_2, and opt_lan1, but skips over the call to opt_so_3 because of the single quote. However as this is only a call and not an include, the documentation for opt_so_3 remains available.

To determine the dependence between a test (*.bas file) and the tested area in the application, you need to use some of the following parameters when you call the hStatusIn routine:

call hStatusIn ('test area', 'name of the bas file')

where test area is: Base, Calc, Chart, Draw, Framework, Impress, Math, Setup, Writer or XML.

The documentation only becomes available after the *.bas file determines the dependence between a test and the tested area (that is, hStatusOut returns the information) and inserts the information in the database

The *.inc-files

Each *.inc files requires a two-part header. The first part of the header is the same as the header for a *.bas file, except that it ends with a forward slash (/) instead of a backslash (\). The second part of the header lists the testcases, functions, and sub routines that you want document. The following is an example of a header for a *.inc file:

(... cut ...)
'* The Initial Developer of the Original Code is: Sun Microsystems, Inc.
'*
'* Copyright: 2000 by Sun Microsystems, Inc.
'*
'* All Rights Reserved.
'*
'* Contributor(s): _______________________________________
'*
'*
'/*******************************************************************
'*
'* owner : owner@foo.bar 
'*
'* short description : short description for this inc file
'*
'********************************************************************
' **
' #1 the_first_testcase 'wrn:1|err:0 ' you can insert here a short description
' #1 the_second_testcase 
' #0 the_third_testcase
' #1 a_sub_routine 
' **
'\*******************************************************************

Underneath the SISL/LGPL header in your file, use a forward slash (/) to start the first part of the documentation header. Include the owner of this test and a short description (max. one line) of the test in the header. End the first part of the header with a forward slash (/).

In the second part of the header, list the routines that you want to document. Add #1 in front of a routine name to enable the documentation for the routine in ttDocs.exe and #0 to disable the documentation for the routine. End the header with a backslash (\). Do not use tabs in the header. If you want to include a tab, use spaces instead.

If you want, you can insert the numbers for errors and warnings of each testcase in the header so that the numbers can be used in the status-page feature (result pages for all test states). If you know that a testcase produces a warning for a bug that has not been fixed in some versions, use wrn:Nr, where Nr is the number of the warning. Similarly, use err:Nr for known errors that you want to ignore. The testcase is then displayed in green on the status page, although the warning occurred. Use a pipe (|) separator between wrn:.. and err:...

CHANGED - is in PRINTLOGS! Standards for Testcase Documentation

Start a documentation line with a single quote and three forward slashes ('///) to identify the line for the documentation parser (ttDocs). If you want, you can end the line with three forward slashes, but this is not required. Only documentation lines that are included in testcases, functions, and sub-routines can be parsed by ttDocs.

When you use /// for documentation strings, the result is a numeration in HTML. If you do not want this to result in a hard-coded line break, use ///+.

Example:

Documentation in script file	Result on HTML-Documentation
'/// This is the 1. line of text [...] '/// This is the 2. line	* This is the 1. line of text This is the 2. line
'/// This is the 1. line of text [...] '///+ This is the 2. line	* This is the 1. line of textThis is the 2. line

You can use HTML tags to structures your documentation. Anything enclosed by < and > is interpreted as an HTML tag. To insert the < and > characters into the documentation, use &lt for < and &gt for >. For further tips, see http://selfhtml.teamone.de/selfhtml.htm (in German) or any other page which describes HTML entities. To insert a single backslash in the documentation output, you need to write two backslashes in the documentation source.

The Style and Coding Standard used in the Automated Testing

Revisions

Version	Author	Date	Comment
0,1	Thorsten Bosbach	17.10.2002	Draft
0,2	Joerg Sievers	18.10.2002	Conversion to .sxw
0,3	Thorsten Bosbach	21.11.2002	Update with Feedback
0,4	Joerg Sievers	27.02.2003	Ready for OOo
0,5	Thorsten Bosbach	17.03.2003	Cleaned for OOo

Introduction

This chapter proposes guidelines to make the test code easier to read and to maintain.

There are two sections in this chapter:

• MUST: For everyone; especially for people who are not familiar with the (TestTool-)BASIC programming language.
• ADVANCED: For people who who want to improve their code style.

The ADVANCED section is based on the articles [Gr00], [Gr01], [Gr02], and [Gr03] to help you develop a better layout for your code.

These guidelines are relatively new and have not been applied to all of the test code that has been written. However, any new code should follow these guidelines so that the code can be properly maintained by all.

Section One - MUST

Variable

A variable is usually defined with ‘DIM name AS type’. Since the TestTool environment uses ‘OPTION explicit’, a variable must be defined before it is used, otherwise an error occurs.

You also have to declare the variable type and when you define a variable. The variable type is also indicated by a lowercase prefix at the start of the variable name.

Example: for an integer variable:

DIM iCounter AS integer 

prefix	type
i	integer
i	long
d	single
d	double
s	string
b	boolean

   The following prefixes must be combined with an additional prefix:

a	array
g	global (from global.inc)
l	list (for variables declared for use of functions from t_list.inc)

Other naming schemes:

t	testcase
s	sub
f	function

After the lowercase prefix that indicates the variable type, start each word in the variable name with an uppercase character. Write CONSTANTS in uppercase characters only, after the lowercase prefix.

You can only make one declaration per line.

For variable and function names, you can only use letters from a-z/A-Z and numbers from 0-9. Do not declare one-letter variables, except for loop counters and array indices such as i, x, y, j, n.

Do not use the a lowercase L (l) for a variable name as it cannot be distinguished from the number 1 (one) or an uppercase i (I).

A variable name can have a maximum of 255 characters and must start with a letter. You can use both lowercase and uppercase letters. When declared, numerical values must be set to 0 and strings must be set to “”.

Indentation

Use horizontal indentation to show the logical level of components in the code, for example, so you can easily see which lines of an if-then-else-clause belong to the 'then' part and which lines belong to the 'else' part. Use four spaces for instead of a tab for an indent as tab handling is different between different platforms and editors. Do not mix spaces and tabs in your code.

Only use four SPACES per indentation level

A label must have a negative indentation.

If the length of a block of code is longer than 20 lines, include a comment as to why this is at the end of the block.

The following is an example of a well-structured (indented) block of code:

    function fThisIsAnExample() as integer
        dim i as integer

        i = 1
        if (i <> 42) then
            bla
            bla
            if (i < 42) then
                bla
                bla
            label:   
                bla
                bla
            else
                bla
                ... > more than 20 lines :-)
                bla
                bla
            endif ' end of i < 42
            bla
        else
            blo
            blo
            for i = 1 to 42
                blu
                blu
                blu
            next i
            blo
        endif
    end function

Blank Spaces

Only use soft spaces and not Tabulators in the code. Always include ONE SPACE AFTER comma (,) and semi-colon (;) delimiters but not BEFORE the delimiters. For example:

    DIM i, z, s AS integer

The assign operator ‘=’ must have one space before and after it, for example, iNumber = 3

You can either include one space before and after a binary operator (binary: it needs two operands) or leave the spaces out. Note: The inclusion of spaces with binary operators does not affect the mathematical precedence.

iState = 3 + 4; iState = 3+4; iState = 3 * 4 + 5; iState = 3*4 + 5
BUT NOT: iState = 3 * 4+4

Include a SPACE between a keyword and its opening bracket, but not between a function name and its opening bracket.

Comments

Each declaration should include a descriptive comment, so that someone else can easily read your code. Temporary variables (for example, loop counters) are the exception to this rule. You do not need to include a description if the name of the temporary variable indicates the variable type (for example, iTemp). Avoid including information that is likely to become out-of-date. Do not enclose comments in large boxes drawn with asterisks or any other character.

There are three styles of comments: block, single-line, and trailing.

Block Comments

Block comments describe the contents of a file or the behavior of a function. Include block comments at the beginning and inside of each function.

The block comment that precedes a function describes what the function does, including input parameters, algorithms, and returned values.

For example:

 function fExample (iExample as integer) as boolean
    '/// ...functional description...                    ///'
    '///+ INPUTVALUES:                                  ///'
    '///+ affected variables outside of this function: ///'
    '///+ RETURNVALUE:                                ///'
 dim iTest as integer ...
end function   

Single Line Comments

Use single line comments to describe loop conditions that are not obvious and also the return values of functions.

Indent a single line comment so that it is at the same indentation level of the code that the comment describes. Include a space between the comment text and the opening (‘). For example:

    if (iTemp > 1) then
        ' Get input file from command line.
        if (iTemp < 9) then
            printlog("can't open %s\n")
        endif
    endif

Trailing Comments

Use trailing comments to document declarations. Trailing comments appear on the same line as the code that they describe.

Include enough space to separate a trailing comment from the statement that it describes.

If a block of code includes more than one trailing comment, indent the comments to the same level.

File Organization

Separate each code section by a single blank line.

Sections inside of .inc files

1. A small or big header
2. Subs if they call the following testcases in this file
3. testcases
4. subs
5. functions

Sections inside of .bas files

1. A small or big header
2. Declaration of global variables
3. Function main with:
   1. Inclusion of files
   2. hStatusIn() (indicates if the status of the testrun is displayed)
   3. Call of functions
   4. hStatusOut() (indicates if the status of the testrun is displayed).
4. sub LoadIncludeFiles

Program Organization

Sections inside of testcases/subs/functions

1. Declaration of variables. You can only declare variables in this section.
2. Initialization of variables
3. Some code
4. Set the returnvalue for functions
5. Never exit a testcase with exit sub, return, or something else as these do not call the TestExit sub routine and as a result, no cleanup is performed. Instead, use goto endsub to recover the OpenOffice.org application that you are testing.

Methods, Hints, Annotations

Selecting the same string in different languages

Since most strings are language dependent, there are several ways to select what you want in each language.

1. Use a list that contains the same word in each language that you want to test. You can then use the list with an existing global routine. The routine must be initialized in a .bas file, for example:
   global glLocale (15*20) as string

   if hSetLocaleStrings ( gTesttoolPath + "graphics\tools\locale_1.txt" , glLocale () ) = FALSE then
      warnlog "Locales file doesn't exist"
   endif printlog glLocale (1)

1. If the entry is in the same position in all languages, use the number of the entry to select it.
2. Find out if someone knows how to get the language dependent string in another way, for example, by using a name filter.

The decimal separator is also language or locale dependent. Although you can use the qatesttool/graphics/tools/id_tools.inc:GetDecimalSeperator routine to return the separator, you can usually just use integers instead of decimal numbers.

Saving files during a test

Do not save files to a directory in the TestTool environment during a test run! This can confuse the cvs as well as create a conflict when more than one user running a test tries to save to the same global location. Instead, save the files to the ${officepath}/user/work directory. This directory is created when a test is started.

For example:

1. If it does not exist, create the following directory: ../user/work/math/level_1/export. On UNIX, use mkdir to create the directory, as it generates the entire path.
2. Delete any existing files in the directory.
3. Use ConvertPath() to determine the right path separator.

   dim i as integer
   dim sFilter (50) as string
   dim lExList(500) as string ' files to be deleted
   dim sPath as string        ' filename and path to export

   sFilter(0) = 0
   sPath = ConvertPath (gOfficePath + "user/work/"+Lcase(gApplication)+"/update/")
   if dir (sPath) = "" then 
      app.mkdir (sPath)
   endif
   GetFileList (sPath, "*", lExList())
   if (KillFileList (lExList()) <> TRUE) then
      Warnlog "Couldn't delete all in Output-Directory, these files are still there:"
      for i=1 to ListCount (lExList())
         printlog "  <> " + lExList(i)
      next i
   end if

Using testing levels

One approach to perform tests is to use three testing levels: update (resource), level 1 (function), and level 2 (special).

Resource: The resource level ensures that all elements, including HelpIDs, that are required by the test are present in a dialog. This is accomplished by performing actions on the elements. If an element is missing, the test fails. You do not need to check the result of changed elements. The test must be language independent. Close the dialog with CANCEL.

Function:Performs more actions on the dialog to determine if the function of the dialog has changed. Leave the dialog open with OK. Run the test in at least the 01, 49 installations (where the numbers represent the English and German language codes, respectively), and an Asian language of your choice.

Special: These are the more complicated tests.

Section Two - ADVANCED

Ensure that the word types that you use in declarations for Boolean subroutines or Functions that have a Boolean returnvalue can be answered with yes/no or true/false, for example, FisAsianEnabled()

In an if statement, Boolean values do not need to be compared to the values TRUE and FALSE.

In the table below, the two sides are semantically identical.

If (bHasData = TRUE)	If (bHasData)
If (bHasData = FALSE)	If (not bHasData)

Word types are in the declaration of variable names.

Names for Boolean variables should name a property, for example, bWindowAvailable.

Names for all other variables should be nouns, for example, iWindowNumber.

Appendix

Acronyms used in this file that need an explanation? Examples

if..then...else

if (iNumber = 1) then 
    printlog ("snoopy") 
else 
    if (iCount = 1) then 
        printlog ("lucy") 
    else
        printlog ("garfield") 
    endif 
endif

select...case

select case iNumber 
    case 1: printlog ("1") 
    case 2: printlog ("2") 
    case 3: printlog ("3") 
    case else: printlog ("???") 
end select

Bibliography

[Gr00] GR√úNFELDER, Stephan: Quellcode wie aus einem Guss : Codierungsstandards erleichtern Einarbeitung, Wartung und Zusammenarbeit.

In: Elektronik (2001), Nr. 11, S. 59-61

[Gr01] GR√úNFELDER, Stephan; GRIESAUER, Franz: Guter Code braucht Ordnung : Universelle Regeln zur Namensgebung und zu Zahlenformaten in Programmiersprachen.

In: Elektronik (2001), Nr. 18, S. 52-59

[Gr02] GRÜNFELDER, Stephan; GRIESAUER, Franz: Guter Code braucht Ordnung : Teil 2: Das Code-Layout – Übersichtliches Aussehen macht Code besser erfassbar.

In: Elektronik (2002), Nr. 8, S. 74-81

[Gr03] GR√úNFELDER, Stephan: Guter Code braucht Ordnung : Teil 3: Fehlervermeidung bei der Erstellung von C-Programmen.

In: Elektronik (2002), Nr. 14, S. 66-71

Content on this page is licensed under the Public Documentation License (PDL).