Debugging Scripts with Assertions – Abstracting the Assert Process

Yesterday we looked at the concept of an assertion for debugging, and the structure of an assertion in a FileMaker script. Now we will look at a better method of scripting assertions for portability and flexibility.

The Assert script

Instead of adding a dozen script steps for every assertion, we are going to abstract the assert process to a subscript. This subscript can be called from any script with two parameters – condition and message.

• condition is a FileMaker calculation expression stored as text. When evaluated, it must return true for the assertion to pass.
• message is the text string that will be presented in a custom dialog if the assertion fails.

The script will be named Assert and expects a JSON parameter containing elements condition and message. The Assert script will unpack the JSON elements into variables for use in the script.

The script is as follows:

# Evaluate assertion condition and display message on failure
# Parameter: JSON - condition, message
# condition is a Boolean expression which must be true to pass
Set Variable [ $json ; 
    Value: Get ( ScriptParameter ) ]
Set Variable [ $condition ; 
    Value: JSONGetElement ( $json ; "condition" ) ]
Set Variable [ $message ; 
    Value: JSONGetElement ( $json ; "message" ) ]
If [ Evaluate ( $condition ) ]
  # assertion passed
Else
  # assertion failed
  Show Custom Dialog [ 
    "Assertion Failed" ; $message ]
  If [ Get (LastMessageChoice) = 1 // stop ]
    Halt Script
  Else If [ Get (LastMessageChoice) = 2 // pause ]
    Pause/Resume Script [ Indefinitely ]
  Else If [ Get (LastMessageChoice) = 3 // ignore ]
  # continue script
  End If
End If

The Evaluate function is used to evaluate the text string, which is the condition being tested.

Calling the Assert script

To add an assertion into an existing script, we simply use the Perform Script script step to call the Assert script. We supply the parameter as a JSON object, which would look like this:

JSONSetElement ( "" ;  
  ["condition"; 
   "Get ( LayoutName ) = \"Email Form\""; 
   JSONString ];
  ["message"; 
   "Incorrect layout."; 
   JSONString ]
  )

Another example is this:

JSONSetElement ( "" ;
  ["condition"; 
   "Get ( FoundCount ) > 0";
   JSONString ];
  ["message";
   "Expected one or more records to be found.";
   JSONString ]
  )

Note that since the condition is a string, it will need special characters like double quotes to be escaped appropriately.

The Assert script does not know anything about what is being tested. Its only job is to evaluate the supplied condition and respond when that condition fails.

Assertion on, Assertion off

The next challenge is controlling when assertions run. Assertions are a developer tool, not part of normal application behaviour. We need a way to enable them during development and disable them for users.

That is for tomorrow.