This document provides information for the new developer to proceed with keyword development--including:
1. Review SAFS Reference
2. Review SAFS XML
3. Review Existing Sourcecode
4. Review Tool API
5. Review Message Resources
6. Edit and Test Keyword Implementation
7. Edit and Test XML
Carefully review the SAFS Keywords Reference. Review the SAFS Reference Key.
The entire reference and many other assets are automatically generated from the XML used to define the Keywords--the testing language--of SAFS. As a developer edits sourcecode to add new keywords or to enhance existing keywords the developer is also responsible for the XML edits necessary to reflect this work.
(back to top)
It is the XML files, XSL Stylesheets, and (Windows) Batch programs that enable us to automatically generate the Reference. You can view the XML, XSL, DTD, and BAT files in your favorite text editor or IDE.
In a SAFS install:
In CVS:
(Much of this predates the Java-based SAFS framework in source/common!)
Key Files Associated with SAFS Reference Publishing:
If all expected XML files exist and contain properly formatted XML, then all you have to do is run the XSLBuildDDEngineReference.BAT batch program. The results of any edits will appear in the C:\SAFS\doc directory.
(back to top)
It is always a good idea to see how other keywords have been implemented. You shouldn't limit yourself to the sourcecode of your own tool, either. If you are working on a keyword that has been implemented in another engine it is often a good idea to review the sourcecode for the other engine to see how it was done. This also gives the developer a little more information as to what is expected of the keyword implementation beyond what the Reference might provide.
CVS sourcecode for several engines:
By examining existing sourcecode you can get an idea of the API your testing tool offers. However, you need to be able to reference your tool's API easily, and probably often. API documentation is usually provided in your IDE Help System, in the install directories for the tool, or online by the tool provider.
Slowly but surely we are introducing the use of shared and localizable messages across Java tools. The messages are currently stored in localizable files:
For Java, we have two classes that facilitate the use of these resource bundles:
Likely some (but not all) of the Java sourcecode you will see will show how to use these classes, or how they may exist as protected field objects available for use. If in doubt, ask the forum.
There is also a great deal of old code where PASS\FAIL messages are of the type:
log.logMessage(testRecordData.getFac(),
getClass().getName()+ ", "+ testRecordData.getCommand() +...,
PASSED_MESSAGE);
log.logMessage(testRecordData.getFac(),
getClass().getName()+ ", "+ testRecordData.getCommand() +...,
FAILED_MESSAGE);
Specifically, where we use "getClass().getName()" to log the name of the executing Class as part of the PASSED or FAILED message. We need to get away from this and, over time, get this out of our code whereever it exists as part of PASS\FAIL messages. In DEBUG or INFO messages this should be OK.
We need to focus on using the localizable resource files and their localized counterparts everywhere we can:
These are available to ComponentFunctions and DriverCommands via calls to genericText.convert and failedText.convert or similar routines:
log.logMessage(testRecordData.getFac(),
genericText.convert("success3a", altText, windowName, compName, action, use),
PASSED_MESSAGE);
log.logMessage(testRecordData.getFac(),
genericText.convert(TXT_SUCCESS_3, altText, windowName, compName, action),
PASSED_MESSAGE);
log.logMessage(testRecordData.getFac(),
failedText.convert("ignore_bad_param", action + someinfo,
action, someinfo));
(back to top)
Referring to the Keyword Reference, sourcecode for existing implementations, and the tool API for your engine, it is time to jump in and enhance or implement keywords. Always try to output shared messages from the Resource Bundles. If the right message isn't there, then add it to the appropriate Resource Bundle. Use the messaging seen in other engines (like RRAFS) as a reference for your messages. Across all engines we want the output messages to be pretty much the same.
Make sure you have the means (an application to test) that will allow you to test and debug your work against real components or targets. Once you have accurately implemented the keyword make sure you update the XML appropriately.
(back to top)
You can edit the XML in a good text or XML editor. The DTD can be used as reference to know what is valid and invalid--required or optional. However, the best source of info is in the tons of XML that is already there.
If the XML already has the keyword definition in it and you are simply adding support for the keyword in another engine then you typically only have to update the ENGINES tag with a new ENGINE definition. If you copy an ENGINE definition from elsewhere make sure you make ALL the necessary changes.
As long as the DTD is in the same directory as the XML you can usually test your XML by trying to view it in a web browser. If the browser does not complain and shows the XML tree, then it is OK. If the browser doesn't like it, the browser may give you hints as to where you have messed things up.
You should also test your XML by publishing the SAFS Reference locally. Do this by running the XSLBuildDDEngineReference.BAT batch file in the C:\SAFS\bin directory. You can then view a local copy of the reference from you C:\SAFS\doc directory.
(back to top)