The PluginTester.exe
console app allows you to run your field data plugin outside of the AQUARIUS Time-Series server environment, for easier debugging and validation.
- Can be run from CMD.EXE, PowerShell, or a bash shell.
- Can be run from within Visual Studio, to allow step-by=step debugging of you plugin.
- An exit code of 0 means the file was successfully parsed by the plugin.
- An exit code of 1 means "something went wrong".
- Everything gets logged to
PluginTester.log
- Any appended results from the plugin can be saved to a JSON file.
Parse a file using a field data plugin, logging the results.
usage: PluginTester [-option=value] ...
Supported -option=value settings (/option=value works too):
-Plugin Path to the plugin assembly to debug
-Data Path to the data file to be parsed. Can be set more than once.
-Location Optional location identifier context
-UtcOffset UTC offset in .NET TimeSpan format. [default: -08:00:00]
-Json Optional path to write the appended results as JSON
-ExpectedError Expected error message
-ExpectedStatus Expected parse status. One of SuccessfullyParsedButDataInvalid, SuccessfullyParsedAndDataValid, CannotParse [default: SuccessfullyParsedAndDataValid]
The tester uses log4net
to log to both the console and to the PluginTester.log
file.
Log statements from the tester itself are easily distinguished from log statements from the plugin being tested.
This post-build event will test that your plugin can successfully parse the data\somefile.ext
file. If a parsing error is detected, the build will be marked as failed.
$(SolutionDir)packages\Aquarius.FieldDataFramework.18.4.0\tools\PluginTester.exe /Plugin=$(TargetPath) /Data=$(SolutionDir)..\data\somefile.ext
The PluginTester.exe
tool follows standard exit code conventions. Zero means success, and any positive exit codes means an error occurred.
Visual Studio post-build events will detect any non-zero exit codes and indicate a failed parse attempt by your plugin.
You can leverage two features of PluginTester
to build an automated test suite for your plugin.
You can even test for error conditions using the /ExpectedStatus
and /ExpectedError
options.
- An exit code of 0 means "The plugin parsed the file as expected".
Any other exit code means something went wrong. Use the exit code to determine if the file was parsed.
$ PluginTester.exe -Plugin=MyPlugin.dll -Data=data.csv -Json=results.json || echo "Did not parser data.csv"
- Saving the appended results to JSON should always yield the identical output.
#!/bin/bash
# Helper function
exit_abort () {
[ ! -z "$1" ] && echo ERROR: "$1"
echo
echo 'ABORTED!'
echo
exit $ERRCODE
}
PluginTester=../some/path/PluginTester.exe
PluginPath=some/other/path/MyPlugin.dll
DataPath=data.csv
JsonPath=results.json
ExpectedResultsPath=some/path/expected.json
$PluginTester -Plugin=$pluginPath -Data=$DataPath -Json=$JsonPath || exit_abort "Can't parse $DataPath"
cmp $JsonPath $ExpectedResultsPath || exit_abort "Expected output did not match."
Use the PluginTest.exe
to debug your plugin from within Visual Studio.
- Open your plugin's Properties page
- Select the Debug tab
- Select Start external program: as the start action and browse to
packages\Aquarius.FieldDataFramework.18.4.0\tools\PluginTester.exe
- Enter the Command line arguments: to launch your plugin
/Plugin=<yourPluginAssembly>.dll /Data=a\path\to\sometestfile.ext
The /Plugin=
argument can be the filename of your plugin assembly, without any folder. The default working directory for a start action is the bin folder containing your plugin.
- Set a breakpoint in your plugin's
ParseFile()
methods. - Select your plugin project in Solution Explorer and select "Debug | Start new instance"
- Now you're debugging your plugin!
The tester doesn't fully emulate the plugin framework. It simply exercises the IFieldDataPlugin
interface and collects the data your plugin tries to append.
- The AQTS framework will perform extensive validation on the data being appended. But the tester doesn't (and can't) perform any of that validation.
When PluginTester
says "Yup" but AQTS says "Nope" to a file, usually that means a data validation error. Check the FieldDataPluginFramework.log
on your AQTS server for details.
If the log file doesn't contain an explaination why the data won't upload:
- Use
PluginTester /Json=path.json
option to save the appended data in JSON format. - Send the JSON file to the SupportTeam @ AquaticInformatics and we'll take a deeper look.