UI Logger

This post is just documentation for GSoC Project of UI logger here:
https://summerofcode.withgoogle.com/projects/#5252265672179712

This project is to generate a new easier Domain-Specific_language for logging the user interactions to be able to convert it to a python script that used by python UI framework for testing.

This project made with Textx which is a meta-language for building Domain-Specific Languages (DSLs) in Python. it helps you build your textual language in an easy way. You can invent your own language or build support for already existing textual language or file format.

If you need to understand how the project is written and mainly the part in this folder: https://opengrok.libreoffice.org/xref/core/uitest/ui_logger_dsl/ I think you can easily see the tutorials here of TextX. The basics of this tutorial that you can understand with 30 mins can let you understand a lot of the project.

WHY DSL?
DSL is a very useful thing because it lets us understand the code without you having coding skills because this project has a very simple grammar that will let anyone be able to understand it. Also, we can use this project to write a test without using python just with this project grammar. 

Grammar?
The grammar is the syntax of this new DSL we can say that this is the new programming language that we can use. The grammar here is divided into:

1. starter_commands :
   This is for the initiization of the, app. For example, at the start of any application, we can just type "start writer"
   
2. uno_commands :
   This is divided into 2 types:
   
   • with parameters:
     ex:"Send UNO Command (".uno:UpdateInputFields") "
   • without parameters:
     ex:"Send UNO Command (".uno:ZoomSlider")  {"ZOOM":50}"
3.  dialog_commands :
   This is divided into 2 types:
   • Open dialog which has 2 options:
     • Modal dialog:
       ex:"Open Modal CharacterPropertiesDialog"
     • Modeless Dialog:
       ex:"Open Modeless CharacterPropertiesDialog"
   • Close Dialog
     ex:"Close Dialog"
4. General_commands :
   This file for the log statements that are general for all application:
   
   • SideBar:
     ex:"From SIDEBAR Choose  {"PANEL": "StyleListDeck"}"
   • SetZoom:
     ex:"Set Zoom to 71"
   • Select Object:
     ex:"Select element no 7 From element_selector"
5. UI_Object_commands :
   this file is for The Grammar of all the UI Objects that you will see in all dialogs and they are divided to:
   • ButtonUIObject : ( Click event )
     ex:" Click on 'reset' from CharacterPropertiesDialog "
   • EditUIObject :
     • Type event
       ex:"Type on 'urled' {"TEXT": "x"} from CharacterPropertiesDialog"
     •  Select Text event 
       ex:" Select in 'urled' {"FROM": "2", "TO": "3"} from CharacterPropertiesDialog "
   • CheckBoxUIObject : ( Toggle the value )
     ex:"Toggle 'pairkerning' CheckBox from CharacterPropertiesDialog"
   • RadioButtonUIObject : ( Select event ) ex:"Toggle 'pairkerning' CheckBox from CharacterPropertiesDialog"
   • ListBoxUIObject : ( Select event )
   • ComboBoxUIObject ( Select event ) ex:"Select in 'westfontnamelb-cjk' ComboBox item number 70 from CharacterPropertiesDialog"
   • SpinUIObject ( Increase event - Decrease event ) ex:"Decrease 'fontsizesb' from CharacterPropertiesDialog"
   • TabControlUIObject ( Change tab event )ex:"Choose Tab number 4 in 'tabcontrol' from CharacterPropertiesDialog"
6. Special_commands :
   This file for the log statements that relates to each different applications Each Grammar Command here is related to his own application I will not give an example for each of those. But I think we can understand the overall grammar from the above examples but to know what is covered for each application with this project:
   
   • Writer
     
     • Type
     • Select
     • GOTO page
     • Create Table
     • Copy Text
     • Cut Text
     • Paste Text
     • Insert Break Page
   • Calc
     
     • select sheet 
     • Select cell or range
     • launch AutoFill
     •  Delete Cells
     • Remove Content of a cell
     • Insert new Cells
     • Cut Cells 
     • Copy Cells
     • Paste Cells
     •  Merge Cells
     • Unmerge Cells
   •  Impress
   • Type
   • Insert New Slide
   •  Delete Slide
   • Duplicate Slide
   •  Rename Slide
   • Draw
   • Type
   • Insert New Page
   • Delete Page
   • Rename Page
   • Math
     
     • element selector
     • Type
      All of these actions are supported and logged with the logger and can be generated or replayed with the corresponding UItest that can be generated with the dsl_core.py
     
   
   

   Using the logger

   First you should update the master branch:
   
   1) Launch LibreOffice like
   

   LO_COLLECT_UIINFO="test.log" SAL_USE_VCLPLUGIN=gen instdir/program/soffice

   
   2) Simulate what you want to do with the mouse
   3) Close LibreOffice
   
   4) Open the resulting file in instdir/uitest/test.log
   
   5) Enter the UI logger directory with this Command:
   

   cd uitest/ui_logger_dsl/

   
   6) Use the following Command
   

   python dsl_core.py <path_to_log_file> <path_to_a_new_python_file>
   

   <path_to_log_file> should be replaced with something like SourceDirectory/core/instdir/uitest/test.log
   and <path_to_a_new_python_file> can be a location of your choice where you would like to see the generated code.
   Also, old Reports has a video doing these steps.

   How to log with the new Grammar? 

   Logging in LibreOffice is mainly handled by a class called UITestLogger, defined here.The logger class logs the user actions only if the member flag mbValid is set to true. The flag can be turned on by setting the environment variable LO_COLLECT_UIINFO to a file name where the logs should be collected (see the constructor of UITestLogger, defined here). we make it equal test.log in last section.
   
   
   their is a pointer to an instance of UITestLogger class here. To use the logger object, the static function getInstance can be used to get access to the pointer.
   The function logAction, defined in the same class, is used to log events from the classes which extend the class vcl::Control. The log statements corresponding to a particular class can be found in the function get_action of the UI wrapper classes. The log statements get generated when VCL events get broadcasted.
   
   
   For other classes, we have functions named collectUIInformation spread in different places of the code (This OpenGrok search might be helpful) and these different places are the functions that execute the supported events in different applications. These functions collect information about an event and store it in a struct EventDescription (defined here) and pass it to another function of UITestLogger, called logEvent. The logEvent function constructs a log string using the information provided by the given event description, and finally logs the statement using the file stream maStream.

   The dsl core [The Compiler] ?

   can be used to convert the log file with the dsl grammar into a UI test case. It interprets the log file by having a handler of each type of commands means that if you have for example a writer type command so the writer type handler will compile it. So it converts every line into a python code and generate statements readable by the UI testing framework. all of these can done by this class : ul_compiler
   
   it saves the new lines in a variable and then at the end it generate the testcase by write all these lines in the output file then you can run the test with instructions found here.
    I hope that this will be enough for anybody want to understand the project or if their is anybody that want to extend it in the future by adding a support for more events. Any questions or feedback can be just added here in a comment and I will check it.
   

   Thank You!