Test Harness Plugin
|
[download id=”6″ format=”2″ autop=”false”] Released under the GNU GPL version 3 license. Installation instructions here. |
The Test Harness plugin helps developers quickly test LUA code running in Lightroom’s LUA environment. It does this by allowing developers to write small LUA scripts, load and run those scripts on the fly, and if desired turn the scripts into standalone Lightroom plugins.
Usage
When you open the File or Help menu’s Plug-In Extras sub-menu, a new Run Script Test Harness menu item will be available. If you are a Windows user and follow the advice in Accelerate Access to Lightroom Plugin Extras you will be able to open this sub-menu using the Alt + F, then S key sequence and access these menu items using the described accelerator keys.
The Run Script Test Harness menu item will open a dialog that displays all known LUA scripts stored in sub-directories within the plugin directory, or the additional script directory you can configure (see Test Harness Configuration below). Each sub-directory will display a separate drop down box allowing you to store your scripts in logical groupings and choose which of those scripts to use. Each group has its own Run button, to execute the currently selected script, and Generate button, to embed the selected script in a single purpose plugin it generates, and Open Log button to open the LrLogger generated log file for the script (if it exists). The dialog also contains a Reload button which refreshes the UI to display any new scripts added since the plugin was last loaded, and an Open Log button to open the Test Harness plugin’s log file. A status line is included at the bottom of the dialog to provide feedback about the plugin’s operation. If you have enabled keyboard accelerators (see above) you can use the Alt + F, then S, then H key sequence to open the menu item.
As this is a test harness for running work in progress code it is expected that the LUA scripts will encounter errors. It is recommended that your scripts performs its own error handling, but if any exceptions make it past the script’s error handling code these will be caught and written to the Test Harness plugin’s logfile: TestHarness.log. The log file can be opened using the Open Log button at the bottom of the dialog. Exceptions will also be displayed immediately in the dialog’s status line.
Running Scripts
The Run button reloads the LUA script from disk and executes it. This means changes to your scripts can be tested immediately without the usual "reload plugin then restart test" cycle encountered during Lightroom plugin development. If your script uses LrLogger to print a log file to disk, and the name passed to the LrLogger is the same as the script’s name, the Open Log button will allow you to quickly access the script’s results.
The plugin also provides some other useful functionality to simplify and speed up testing of LUA scripts:
- In built exception handling: all exceptions will be caught and written to the TestHarness.log file. No reload of the Test Harness plugin will be required if your script throws an unhandled exception, and a stack trace will be recorded to indicate which line threw the exception.
- traceback(message, level): a global function is available if you wish to record a stack trace in your LUA script
- dumpToString(item): a global function is provided to dump an item of any type to a string. Unlike tostring() this will try to record the maximum available amount of information, including the complete content of any tables passed to it.
- lrType(item): global function is available to return the name of the Lightroom SDK class, or otherwise the native LUA type of the item.
- isLrType(item): global function is available to return whether this item’s type is a Lightroom SDK class.
Example scripts are installed in the Test Harness sub-directory within the plugin. In particular the CaughtException.lua script includes an example of how to catch and log errors within your scripts, and would be a good starting point for your own LUA test scripts. The screenshots below demonstrate the relationship between how LUA scripts are stored on the disk and represented in the main dialog. You can add your own sub-directories in the test-harness.lrplugin directory to group LUA scripts you wish to test.
Generating Plugins
The Generate button creates a basic plugin containing a single menu item to execute your LUA script. This is written to a sub-directory within the specified Generated Plugin Folder (see section below). Generated plugins are completely self-contained, ready for compressing and distribution. This can be useful for producing plugins to demonstrate issues when posting to Lightroom SDK forums or reporting bugs to Adobe. The Show plugin after generation? checkbox at the bottom of the dialog controls whether Explorer (Win) or Finder (Mac) will be opened to show you the plugin once generated. If you prefer you can move the plugin to another location before installing it via the Plug-in Manager as you would any Lightroom plugin.
The copyright and plugin ID prefix recorded in the plugin’s Info.lua file can be configured to match your preferred values. Please see the following section for information on how to configure these.
Test Harness Configuration
The Test Harness has a number of configuration items that can modify the plugin’s behaviour. Use the File -> Plug-In Manager menu option to modify the following items:
- Additional Script Folder: Specify an additional folder whose sub-directories will be scanned for LUA scripts.
- Log File Viewer: Specify the program that will be used to display log files. Defaults to notepad.exe (Win) or TextEdit.app (Mac).
- Generated Plugin Folder: Specify the folder where generated plugins will be written. Defaults to the Test Harness plugin directory
- Plugin Copyright: The copyright statement to be written to any generated plugin. Defaults to the copyright notice for the Test Harness plugin itself.
- Plugin ID Prefix: The plugin toolkit ID prefix to help uniquely identify the generated plugin. Defaults to "com.thephotogeek.lightroom.test-case".
- LUA Interpreter: Specify the full path to the LUA interpreter, if installed. [Reserved for future use]
History
| Version | Change Log |
|---|---|
|
20100216.006 |
Minor bug fixes |
|
20100127.005 |
|
|
20100122.004 |
Initial public release |
[…] you are a Lightroom plugin developer you need to try my new Test Harness plugin. Why? It will save you […]