FloraScript Commands

There are 4 basic FloraScript commands: load, assertTrue, compareWithFile, and compareTraceWithFile.

To see how these commands work, we start with loading family-regression-tests.fs into the Text Editor. If double-clicking the file doesn’t load it into the Text Editor, try dragging it from the navigation window to the Text Editor window. Once the file is successfully loaded, a file tab should appear across the top of the Text Editor, and there should be no content initially, as shown in Fig. 247.

Fig. 247 File family-regression-tests.fs is loaded with empty content initially

The load command is used to load a target file and all of its imports for the regression tests. Sunflower looks up the target file relative to the Sunflower Project the regression test file is in. For example, to load family.flr, we type the following at the input cursor in the Text Editor window, as shown in Fig. 248.

load flr/family/family.flr

Fig. 248 Load statement to load family.flr

One thing worth noting about the load command is that a subsequent load command removes what has been loaded before. So for example, if we have 2 load statements:

load flr/family/family.flr

load flr/family/child.flr

The context of family.flr will be removed by the second load statement which loads in the context of child.flr.

The assertTrue command is used to execute a query and make sure it succeeds. This command therefore can be used to test true statements which are asserted or implied. For example, let us put into family-regression-tests.fs the following:

load flr/family/family.flr

assertTrue Greg[aunt->Emma]

Save the file. Right click in the navigation tree window and choose Execute FloraScript. The Sunflower console window shows the execution results as shown in Fig. 249. The OK status indicates the command has executed successfully. In other words, the statement:

assertTrue Greg[aunt->Emma]

is a true statement.

Fig. 249 Results of family-regression-tests.fs execution in Sunflower console

On the other hand, if we have:

load flr/family/family.flr

assertTrue Greg[aunt->Louisa]

This will result in a FAILED status for the statment, as shown in Fig. 250, which implies the statement is false.

Fig. 250 Failed results of family-regression-tests.fs execution in Sunflower console

The compareWithFile command is useful for query regression testing, especially for queries with long query results. To use this command, load family.flr into the Text Editor, and execute the query “Who has a brother?”, as shown in Fig. 251.

Fig. 251 Execute query Who has a brother?

We will now save this set of expected query results in a folder. Create a new folder from the main navigation menu (File > New > Folder), as shown in Fig. 252.

Fig. 252 Create a new folder to keep the expected query results

In the new folder dialog window, click to select the same parent folder for the new folder as the family-regression-tests.fs, in this case it is SunflowerProject1, and give the new folder the name expected-results, as shown in Fig. 253, and click Finish.

Fig. 253 Keep the expected query results folder in the Sunflower project

In the Query Results window, use the Save result to... button to save the returned results, as shown in Fig. 254.

Fig. 254 Save query results for who has a brother?

When the file navigation window pops up for you to specify the location of the saved file, navigate to the newly created folder and save the results there, and name the file who-has-a-brother-10-9-2015.xml, as indicated in Fig. 255.

Fig. 255 Specifying location for saved query results

Refresh (File > Refresh from main navigation menu) SunflowerProject1 in the Sunflower navigation window. Then expand the newly created folder. The saved results file should appear in expected-results, as shown in Fig. 256

Fig. 256 Saved query results file in Sunflower navigation tree

Now we have the expected results saved, and we can use the command compareWithFile to do a regression test on the same query to compare results. Load family-regression-tests.fs into the Text Editor and put the following into the file:

load flr/family/family.flr

compareWithFile ?Person[brother -> ?_Brother] expected-results/who-has-a-brother-10-9-2015.xml

Save family-regression-tests.fs. Then right click to select “Execute FloraScript”. A regression test of the query “Who has a brother?” takes place, and a comparison between the new results and the saved results is made. If the results match, you will see the status OK in the Sunflower Console window, as shown in Fig. 257

Fig. 257 Regression test results match saved results

The compareTraceWithFile command is useful for regression testing the full trace of one specific solution to a query. For example, suppose we want to perform a regression test on one specific answer to the query “Who has a brother?”:

Betty[brother->Chris]

In the Query Results window, we will click the ? mark next to the answer Betty to display its trace, as shown in Fig. 258

Fig. 258 Click ? to show trace for answer Betty

When the trace for answer Betty is displayed, use the Save results to... button to save the expected answer to a xml file named betty-has-brother-chris.xml, as shown in Fig. 259.

Fig. 259 Save trace for answer Betty

Note that another way of generating the same trace is to use the Trace Query option with highlighted query Betty [brother->Chris]. The 3 Trace Query options are explained in Trace Query with right-click menu.

Similar to the command compareWithFile, compareTraceWithFile also looks up files relative to the parent folder family-regression-test.fs is in. The expected trace result therefore should be saved in a folder such as expected-results which has a common parent folder as family-regression-tests.fs. After saving the expected trace result, do a refresh of the navigation window. The saved trace should appear in the expected-results folder, as shown in Fig. 260

Fig. 260 Save trace file shows in Sunflower

Now we have a copy of the expected trace result for answer Betty, we can make use of the FloraScript command compareTraceWithFile to perform a regression test. Load family-regression-tests.fs into the Text Editor and put into it the following lines:

load flr/family/family.flr

compareTraceWithFile Betty[brother -> Chris] expected-results/betty-has-brother-chris.xml

Save the file and do “Execute FloraScript” from the right-click menu. The regression test result should match the saved result, as indicated by the OK status in the Sunflower Console window, as seen in Fig. 261.

Fig. 261 Regression test on trace matches saved result

Note that for compareTraceWithFile to work properly, the same trace depth setting should be used for saving the expected results and for executing the regression test. See Query Result Preferences for more details on the trace depth setting.