.. _section-FloraScript Commands 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 :numref:`figure-load-family-regression-tests.png`. .. _figure-load-family-regression-tests.png: .. figure:: ../../../figs/load-family-regression-tests.png :alt: File family-regression-tests.fs is loaded with empty content initially 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 :numref:`figure-load-family-in-fs-file.png`. .. code-block:: flora load flr/family/family.flr .. _figure-load-family-in-fs-file.png: .. figure:: ../../../figs/load-family-in-fs-file.png :alt: Load statement to load family.flr 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: .. code-block:: flora 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: .. code-block:: flora 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 :numref:`figure-who-is-gregs-aunt-fs-output-ok.png`. The **OK** status indicates the command has executed successfully. In other words, the statement: .. code-block:: flora assertTrue Greg[aunt->Emma] is a true statement. .. _figure-who-is-gregs-aunt-fs-output-ok.png: .. figure:: ../../../figs/who-is-gregs-aunt-fs-output-ok.png :alt: Results of family-regression-tests.fs execution in **Sunflower** console Results of family-regression-tests.fs execution in **Sunflower** console On the other hand, if we have: .. code-block:: flora load flr/family/family.flr assertTrue Greg[aunt->Louisa] This will result in a FAILED status for the statment, as shown in :numref:`figure-who-is-gregs-aunt-fs-output-fail.png`, which implies the statement is false. .. _figure-who-is-gregs-aunt-fs-output-fail.png: .. figure:: ../../../figs/who-is-gregs-aunt-fs-output-fail.png :alt: Failed results of family-regression-tests.fs execution in **Sunflower** console 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 :numref:`figure-execute-query-who-has-a-brother.png`. .. _figure-execute-query-who-has-a-brother.png: .. figure:: ../../../figs/execute-query-who-has-a-brother.png :alt: Execute query Who has a brother? 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 :numref:`figure-create-new-folder-for-expected-results-1.png`. .. _figure-create-new-folder-for-expected-results-1.png: .. figure:: ../../../figs/create-new-folder-for-expected-results-1.png :alt: Create a new folder to keep the expected query results 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 :numref:`figure-create-new-folder-for-expected-results-2.png`, and click **Finish**. .. _figure-create-new-folder-for-expected-results-2.png: .. figure:: ../../../figs/create-new-folder-for-expected-results-2.png :alt: Keep the expected query results folder in the Sunflower project 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 :numref:`figure-save-query-results-who-has-a-brother-1.png`. .. _figure-save-query-results-who-has-a-brother-1.png: .. figure:: ../../../figs/save-query-results-who-has-a-brother-1.png :alt: Save query results for who has a brother? 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 :numref:`figure-save-query-results-who-has-a-brother-2.png`. .. _figure-save-query-results-who-has-a-brother-2.png: .. figure:: ../../../figs/save-query-results-who-has-a-brother-2.png :alt: Specifying location for saved query results 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 :numref:`figure-saved-query-results-show-in-sunflower.png` .. _figure-saved-query-results-show-in-sunflower.png: .. figure:: ../../../figs/saved-query-results-show-in-sunflower.png :alt: Saved query results file in **Sunflower** navigation tree 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: .. code-block:: flora 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 :numref:`figure-compare-with-file-ok.png` .. _figure-compare-with-file-ok.png: .. figure:: ../../../figs/compare-with-file-ok.png :alt: Regression test results match saved results 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?": .. code-block:: flora 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 :numref:`figure-betty-has-brother-chris-trace-1.png` .. _figure-betty-has-brother-chris-trace-1.png: .. figure:: ../../../figs/betty-has-brother-chris-trace-1.png :alt: Click **?** to show trace for answer Betty 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 :numref:`figure-betty-has-brother-chris-trace-2.png`. .. _figure-betty-has-brother-chris-trace-2.png: .. figure:: ../../../figs/betty-has-brother-chris-trace-2.png :alt: Save trace for answer Betty 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 :ref:`section-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 :numref:`figure-saved-betty-has-brother-chris-trace-shows-in-sunflower.png` .. _figure-saved-betty-has-brother-chris-trace-shows-in-sunflower.png: .. figure:: ../../../figs/saved-betty-has-brother-chris-trace-shows-in-sunflower.png :alt: Save trace file shows in **Sunflower** 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: .. code-block:: flora 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 :numref:`figure-compare-trace-with-file-ok.png`. .. _figure-compare-trace-with-file-ok.png: .. figure:: ../../../figs/compare-trace-with-file-ok.png :alt: Regression test on trace matches saved result 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 :ref:`section-Query Result Preferences` for more details on the trace depth setting.