Test Harness Plugin

Download the latest Test Harness Lightroom Plugin version here (20100216.006) 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	Log files for LUA scripts and the Test Harness can be opened directly from the dialog, in the configured Log Viewer application. Status line provides immediate feedback to the user about plugin activities, including caught exceptions. Directories for storing LUA scripts and generated plugins are now configurable. Copyright and unique ID embedded in generated plugins are now configurable. Added lrType() and isLrType() utility functions, and improved dumpToString() handling of Lightroom SDK types.
20100122.004	Initial public release

• Our Lightroom Plugins

  TPG Elemental

  TPG LR Backup

  TPG Metadata Panels

  TPG Snapshotter

  LRRelaunch [Script]

  ... and more

• Follow me on Twitter

  My Tweets

• Recent Posts

  • Review: Organizing Your Photos with Lightroom 5 Multimedia eBook
  • New Plugin Releases and Support for Lightroom 2
  • Latest Lightroom Plugin Activity over at the Photographer’s Toolbox
  • My Latest Lightroom Plugin Activity over at the Photographer’s Toolbox
  • Keyboard Shortcuts and Lightroom Plugin Menu Items

• Blogroll

  • Jeffrey Friedl’s Blog

• Tags

  android baby backup beta book camera code codec composition configuration creativesuite DNG dslr ebook education gallery import keyboard kindle lightroom lr2 LR3 LR4 LR5 metadata news nikon photography photoshop photoshopelements plugin preparation pse script shortcut smartalbum Software tethered update video Web workflow

• We Use & Recommend