KWWidgets/GUI Testing/Squish/SquishForKWWidgets

Goals

• Create a CMake module to find Squish on the system (paths to Squish server and Squish runner).
• Create CMake macros that will run a Squish test by invoking the squish server and client runner, and parsing its output,
• Invoke the Squish module when configuring/building KWWidgets,

Files

The following files were added to the KWWidgets/CMake directory. Most of them were adapted from Brad Davis' scripts.

• FindSquish.cmake: locates Squish and sets SQUISH_FOUND.

Warning: The SQUISH_ADD_TEST macro defined here should not be used by KWWidgets since KWWidgets has some special requirements to run Squish tests. Instead, the KWWidgets_ADD_Squish_TEST macro, defined in KWWidgetsTestingMacro.cmake, should be used to add squish tests to CTest.

• KWWidgetsSquishTestScript.cmake: implements a Squish testing sequence (start Squish server, run test, stop Squish server, etc.).
• SquishRunTestCase.sh: The shell script launched by KWWidgetsSquishTestScript.cmake to run the testing sequence.

The KWWidgets_ADD_Squish_TEST macro is defined in KWWidgetsTestingMacro.cmake:

# KWWidgets_ADD_Squish_TEST

macro(KWWidgets_ADD_Squish_TEST 
    test_name
    squish_AUT_full_path
    squish_test_case_path
    aut_env
    aut_path_script
    aut_args
    )

  set(kwwSquishShellScript "${KWWidgets_CMAKE_DIR}/SquishRunTestCase.sh")

  # Can only handle "Tk"
  set(squish_script_wrapper "Tk")

  ADD_TEST(${test_name}
    ${CMAKE_COMMAND} -V -VV --test
    "-Dsquish_aut:STRING=${squish_AUT_full_path}"
    "-Dsquish_server_executable:STRING=${SQUISH_SERVER_EXECUTABLE}"
    "-Dsquish_client_executable:STRING=${SQUISH_CLIENT_EXECUTABLE}"
    "-Dsquish_libqtdir:STRING=${QT_LIBRARY_DIR}"
    "-Dsquish_test_case:STRING=${squish_test_case_path}"
    "-Dsquish_env_vars:STRING=${aut_env}"
    "-Dsquish_wrapper:STRING=${squish_script_wrapper}"
    "-Dsquish_aut_script:STRING=${aut_path_script}"
    "-Dsquish_shell_script:STRING=${kwwSquishShellScript}"
    "-Dsquish_aut_args:STRING=${aut_args}"
    -P "${KWWidgets_CMAKE_DIR}/KWWidgetsSquishTestScript.cmake"
    ${ARGN})

endmacro(KWWidgets_ADD_Squish_TEST)

Use

The following CMakeLists.txt snippet shows how to add a Squish test to one of KWWidgets' C++ example: Examples/Cxx/WidgetsTour. The KWWidgets_USE_Squish option should be turned to ON for KWWidgets to add the corresponding tests.

find_package(Squish)

if(BUILD_TESTING AND KWWidgets_BUILD_TESTING)
  include("${KWWidgets_CMAKE_DIR}/KWWidgetsTestingMacros.cmake")
  kwwidgets_add_test_from_c_example(KWWidgets-${PROJECT_NAME} ${EXE_NAME})

  if(KWWidgets_USE_Squish AND SQUISH_FOUND)
    set(Squish_TST_NAME "${KWWidgets_SOURCE_DIR}/Examples/Cxx/${PROJECT_NAME}/Testing/Squish/suite_KWWTourExample/tst_BrowseCoreWidgets")
    kwwidgets_add_squish_test_from_c_example(
      KWWidgets-Squish-${PROJECT_NAME} ${EXE_NAME} "${Squish_TST_NAME}")    
  endif(KWWidgets_USE_Squish AND SQUISH_FOUND)

endif(BUILD_TESTING AND KWWidgets_BUILD_TESTING)

Known Issues

Squish

• Squish does not handle the vtkKWMenuButton widget properly. The replay sequence is sending too many mouse motion events and it takes a long time to playback the corresponding "picking a menu entry" action.

Note: FrogLogic is aware of this issue, and they will try to address it in the next Squish release. In the meantime, one workaround is to manually remove most of the motionEvents (except the last one) from the squish test script.

• Similar to the vtkKWMenuButton, too many mouse move events are recorded and played back when performing a mouse "drag" over the render window.
• Squish sends events to the AUT (Application Under Testing) asynchronously during playback; it does not know if the events are actually processed or not, i.e. how long it will actually take the application to react to each event on a computer different than the one that was used to create the test itself.
• Events from secondary toplevel dialogs are not recorded yet. For example, in WidgetsTourExample, select MultiColumnList from the left panel and double click on the color button: this will launch a color-picker dialog, which is KWWidgets's own color dialog. Squish does not seem to be able to record any of the mouse event coming from this toplevel dialog.
• Squish does not record/track the file name from a file dialog, since it just records the mouse events without knowledge of the semantics of the widget. The same is true for the color-picker-dialog, as reported previously.

KWWidgets

• In order to validate tests that operate on image data, a KWWidgets application needs to be able to grab a screenshot of the render window or render windows, so that baseline images can be created and compared with the squish test results, for validation purposes.