Home • Corporate • Contacts •

TETware Knowledgebase

Products

Solutions

Information

Datasheet

Documentation

FAQ

Knowledgebase

Return to Knowledgebase Index

26. Writing a new API

Question

One of the requirements that I have is to create an API for an internal language we have developed. Can you suggest what are the requirements for creating such an API? The API will allow for remote execution, but distributed execution is not required. Do you have any pointers? What is the magnitude of such an effort?

Answer

When you create a new API for TETware, the first thing to consider is: Can the new API language be linked to C?

If the answer is Yes, then the task is a relatively simple one. You can provide a glue layer between the new language and the existing C TCM and API library. When you define the way in which test cases are to be called by the TCM, you will probably need to use the dynamic test case interface that is described in Chapter 8 of the TETware Programmers Guide. (If you go down this route, be sure not to use unpublished interfaces in the C TCM or API since these can and do change between TETware releases!)

However, if the answer is No, there is a little more work to do. You have to implement your own TCM and API library. If your language is an interpreted one it is probably best to use the (Bourne) Shell API as a starting point. You can find the source code for this below the directory src/xpg3sh/api in the TETware distribution.

If you want to see an example of how the Shell API is used, check out the Shell API demonstration test suite which is below the contrib/SHELL-API directory in the contrib distribution.

Now some hints as to how to approach the task . . .

1. Interface between tcc and the test case.



1. Command-line arguments.
   tcc passes a list of Invocable Components on the command line. Your TCM should use this list to decide which test purpose functions to call. You should be prepared to accept zero or more arguments. Each argument might be:



• an invocable component number;



• a range of invocable component numbers (that is: two numbers separated by a hyphen);



• the word all (meaning all invocable components in the test case);



• a comma-separated list of any of these.




If no arguments are passed on the command line, your TCM should behave as if all had been specified. If the word all follows a number or a number range, it means ``all the ICs in the test case beyond the last one specified''.

Your TCM should allow for the possibility that an IC might be specified more than once on the command line.

2. Environment variables.
   tcc passes certain information to the test case in the environment. Check out the section entitled ``Communication variables'' in the TETware Programmers Guide. In particular, you will need to make use of TET_ACTIVITY, TET_CODE and TET_CONFIG. You may also need to use TET_ROOT, depending on how your language works.

   However, it is also possible for your test case to be invoked directly by a user, so you should allow for the possibility that these environment variables are not set. Look at the Shell API to see how it handles this situation.




3. Current working directory.
   When tcc executes a test case, it does so in the test case execution directory. The precise location of this directory depends on the settings of certain configuration and environment variables. So you should not make any assumptions about the current working directory when the test case is executed.



4. Execution results file.
   The TCM should create a results file called tet_xres in the directory in which it is invoked. tcc reads journal lines from this file when the test case exits.



5. TCM exit status.
   Your TCM should exit with a zero status value if no errors occur. If a fatal error occurs you should print a Test Case Manager message describing the problem to the execution results file and exit with a +ve status value.



2. API functions.
   As far as possible, your API should (at least) provide functionality of each type that is described in Chapter 11 of the TETware Programmers Guide. Depending on the capabilities of your language, you may need to provide explicit functions to implement the things that the Shell does of itself - these things are described in the last few subsections of Chapter 11. You can refer to the corresponding sections in Chapter 8 for more information if necessary.

   One point to note - the description of the Shell version of tet_reason says that the function ``prints a string on the standard output''. This is because that is the way for a shell function to return a string; the string is picked up in the calling function by using backquotes. When you implement this function in your language, you will probably just want to return the string to the caller.




3. Journal lines.
   These are described in Chapter 13 of the TETware User Guide and in Appendix C of the TETware User Guide.



1. Format.
   Your API should format and print these lines to the tet_xres file. Be sure to format each line correctly; before printing the line you need to:



• translate embedded newlines to tabs;



• strip trailing white space;



• ensure that the line does not exceed 512 characters.



2. Line types generated by an API.
   Your TCM and/or API should generate the following lines at the appropriate times:



• Test Case Manager Start



• Test Purpose Start



• Test Purpose Result



• Invocable Component Start



• Invocable Component End



• Test Case Manager Message



• Test Case Information




All the other line types are generated by tcc - they should not be generated by your API.

3. Test purpose results.
   You should ensure that each test purpose only generates one Test Purpose Result line, no matter how many times your tet_result function is called from each test purpose. See how the Shell API handles this.

See also

• "Testing structure'' in the TETware Programmers Guide.

 

• "The Test Case Manager'' in the TETware Programmers Guide.

 

• "The C API'' and "The Shell and Korn Shell APIs'' in the TETware Programmers Guide.

 

• "Writing a Shell language API-conforming test suite'' and "Example Shell API test suite source files'' in the TETware Programmers Guide.

 

• "Running the TETware demonstrations'' in the TETware User Guide.

 

• "Test reporting and journaling'' in the TETware Programmers Guide.

• "TETware journal lines'' in the TETware User Guide.