Table of contents
Tester plugin (preliminary file name npapi.dll) is designed to add a level of convenience and automation to testing Netscape Plugin API. The plugin has implementation of all existing NPAPI calls and allows to execute them in any desirable pattern as well as log all NPAPI activity. Plugin handles MIME type 'application/npapi-test' and file extension 'pts' (which could stand for 'plugin test script').
The plugin is capable of issuing NPAPI calls to the Navigator and logging them along with callbacks from the Navigator with argument and return values. Time stamps are also logged so some timing issues can be investigated. All NPAPI calls, both NPN_* and NPP_*, are getting logged during operation of the plugin. User can see log in the dedicated frame in the Navigator window or dump log into file.
The plugin has two modes of operation: manual and automatic (script execution). The manual mode is thought to be convenient for taking a quick look at the API and get some initial feeling. It allows user (developer, tester) to call any NPAPI function with any valid arguments from the plugin GUI and see the either the visual result of this call or the log if the call results in callbacks from the Navigator or returns some values.
Automatic mode is for more sophisticated testing with preset pattern of calls. Before starting a test plugin reads a specified script file which contains all necessary info on what calls to execute, what parameters to pass and how to conduct the test: how many times, with what time delay after specific calls or after repetition cycle.
From plugin GUI user can choose log file name and script file name (or URL - see Enhancements if this is in to-do list).
Special case is full page mode, when the plugin is invoked on file extension association. In this case there is no GUI at all, and *.pts file is treated as a script file to execute.
Platform implementations of the plugin GUI can differ since the plugin was originally developed for Windows NT, and GUI is the only non-crossplatform part of it. See Enhancements section for the latest on platform implementations.
In its original configuration the main Navigator window is divided into three frames: Control frame, Display frame and Log frame, although this configuration is not required.
Plugin controls (the actual GUI) occupy the Control frame, while Display frame can be used as a target for calls like NPN_GetURL and Log frame displays the log.
User chooses desired mode of operation: Auto or Manual, and using check
boxes and editable fields enables/disables logging to frame/file
chooses log and script file names. User can hold log output if timing
is important by disabling "Flush immediately" feature and flush the log
when it is appropriate by hand ("Flush" button).
In Manual mode, only valid arguments are possible to pass. If, say,
we pass a string pointer to NPN_GetURL as a URL to get, user cannot
specify the actual pointer value, he rather types the string itself. Plugin
instance value can not be modified too. In Auto mode, on the contrary,
one can pass any values in place of any argument using script
file format features. This option is particularly useful if invalid
parameters are to be tested.
This is a useful mode when no user interaction is needed at all. The plugin is launched in full page mode when it encounters file of 'pts' type. It saves this file in a local cache and then treats it as a normal script file. It automatically constructes log file with the name of cache file and 'log' extension. This can overridden in preferences profile. See Appendix B on how to specify log file name in fully automatic mode .
Those were added to enchance the plugin functionality so that it can operate without fully implemented API in the browser.
First, you can start running script automatically as soon as NPP_New is called on the plugin.
Second, the plugin can use native pop up window to display its GUI.
Both modes do not rely on the browser capability to create windows/frames/widgets and layout. See Appendix B on how to turn these modes on in the preferences file.
Every NPAPI call is logged into a log item which normally consists of three lines:
Symbolic separator can be inserted after each log record. This could be useful for automated log file readers. See Appendix B on how to specify separator .
Script file is in a form of standard Windows profile (.INI
file).
Private profile is a text file consisting of sections and keys with
their values, comments can be made with a semicolon in first position
'Numeric' sections are the actual script, each representing one NPAPI call. Calls will be executed in their numeric order, some numbers could be missing, so you can start to write your script with numbers multiple by say ten in order to be able to insert new script items later.
Important feature:
arg* keys represent NPAPI function call arguments and they
depend on actual call. In some cases you may not specify an argument if
you have no control over it. E.g. pointer to the plugin instance or pointer
to a stream created by NPN_NewStream. Scripter code will pick
up right ones for you. If you specify them explicitly it will take them
but be prepared for boom. This is appropriate if you want to test an API
call with invalid arguments. String should can be represented by
actual string. Arguments which are parameters of enumerated type or #define'ed
like NPPVariable, NPReason etc. should be represented
by their enum type identificator from npapi.h like NPPVpluginNameString
or NPRES_DONE. Also NPBool should read TRUE
or FALSE. If you want to test real numeric values in place of
this args, say 0x00000000 for string pointers, use a special prefix
'_true_numeric_value_' . The following example will execute NPN_GetURL(instance,
-1, "some_target") with real instance, invalid URL and valid target:
Current Version and Known Issues
Current version is 1.6.
Issues:
The core of the plugin consists of three self-contained objects of types
CPlugin, CLogger and CScripter, and there is
also a set of various helpers like string converters and formatters, and
INI style profile handlers (on Windows, standard built-in profile stuff
can be used).
The three objects are global for the project, CPlugin being
a "coordinating center". CLogger and CScripter are not
members of CPlugin simply because there is no need to keep several
instances of e.g. CLogger for every instance of CPlugin.
One should be enough for all.
Part of CPlugin C++ interface and some functions in xp.cpp are the only things which should be implemented for every platform separately since this object handles GUI. Therefore, to make things easier, an abstract class CPluginBase has been written. This base class methods contain cross-platform code, and object of CPlugin type can be derived from this base class. With this approach no changes need to be made in any project file, only a new source file with implementation of CPlugin::CPluginBase with appropriate GUI handling can be added.
As a first step, one can try just to build a project with no additional coding, thus with no GUI, so it will work only with scripts.
CLogger and CScripter do not use any Windows specific API thus are cross-platform. C++ interface for these objects is self-explaining and straight forward. The objects handle file operations, string scanning and formatting, and also information output.
Some Windows specific calls which are used throughout the project are put together in file xp.cpp where they are #ifdef'ed and need to be implemented for every non-Windows platform. At the moment they are: XP_GetTickCount(...), XP_Sleep(...).
So, the steps for successful porting are:
Npapi.ini is located in the same directory the plugin is located. Currently it stores GUI preferences (state of check boxes etc.) in Preferences section, and normally this section does not need to be edited directly. Some exeptions are LoadWindowStatus, AutoStartScript and StandAloneWindow.
In Preferences section you can manually add an option to show a small window in the left top corner of the screen which tells you that the plugin dll is loaded in memory. This may be useful after calling NPN_SetValue setting NPPVpluginKeepLibraryInMemory TRUE.
StandAloneWindow will pop up a separate native window which will be used by the plugin instead of the browser window.
AutoStartScript will start the executing of the script file immediately after the plugin is loaded and initialized.
The default values for all those settings are "no".
In Log section the form of separator can be specified using key RecordSeparator. For example:
In this section you can also specify when to cut off long data strings in the log as follows:
The log file name for full page mode can be specified with key FileName. Note that full path should be given too: