Test Harness Plugin

[download id=”6″ format=”2″ autop=”false”]

Released under the GNU GPL version 3 licenseInstallation 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.

Test Harness plugin's menu item


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.

Plugin's Script Test Harness Dialog 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:

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.

 Script Test Harness Dialog's LUA script menu items Test Harness's LUA script install location


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 generated plugin example

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:

Test Harness configuration dialog


Version Change Log


Minor bug fixes


  • 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.


Initial public release