Robot Framework Magik (RFM)

Copyright 2012- Luiko Czub, Smallcases Software GmbH License Apache License 2.0

Introduction

Provides Robot Framework keywords for automated testing Smallworld Magik images (4.x) and sessions (5.x). It includes also a Robot library and Python scripts to start and stop Magik images (4.x) / sessions (5.x) with a remote_cli.

Some feature

• each production image / session based on a swaf can be tested without loading additional modification code
• Robot Framework keyword-driven testing approach allows to hide complex Magik requests in readable keywords
• supports Smallworld 4.1/4.3 images and Smallworld 5.1/5.2/5.3 sessions
• supports loading, running and evaluating OpenSmallworld MUnit tests
• it is possible to handle several images / sessions during one test run, for example to test their interaction
• in combination with Robot Framework Standard Test Libraries like XML / OperatingSystem or External Test Libraries like Selenium2Library / Database Library / HTTP library allows to test the interaction with external systems
• the communication via telnet allows to test images / sessions running in a different network

Robot Framework Magik can also be used as a remote control for Magik images (4.x) and sessions (5.x)

Some details

The Robot Magik keywords robot_magik_base.robot uses the TelnetLibrary sending commands to Magik images / sessions and read their response. Precondition is, that Magik image / session under test has started a remote_cli to allow a telnet communication.

• Keyword Documentation robot_magik_base explains, how to start a remote_cli manually and which keywords exists
• Use library RobotMagikLauncher.py to start an image / session directly inside the robot tests (for example as suite setup )
• or use the Python script robot_start_magik_image.py to start an image / session with a remote_cli from outside the robot test

The Robot Magik keywords robot_magik_munit.robot defines additional keywords for loading, running and evaluating OpenSmallworld MUnit tests.

• see Keyword Documentation robot_magik_munit.

The Robot Magik keywords robot_magik_dsview.robot defines additional keywords for testing Smallworld ds_views, ds_collections and rwo_records.

• see Keyword Documentation robot_magik_dsview.

The Robot Magik library RobotMagikLauncher.py defines keyword to start and stop Magik images (SW4.x) or sessions (SW5.x) directly inside a robot test suite via the gis.exe launcher program on Windows

• see Keyword Documentation RobotMagikLauncher.
• uses the ProcessLibrary for handling the image / session process

The Python script robot_start_magik_image.py starts Magik images (SW4.x) or sessions (SW5.x) outside a robot test run via the gis.exe launcher program on Windows

• starts a remote_cli inside this image
• stores the process id in a Pid-File

The Python script robot_stop_magik_image.py

• reads the Pid-File and stops the Smallworld Magik image by sending a kill signal to the process

Installation

Robot Framework Version 7.3 is required and Python 3.12 or 3.14 recommended.

Download current master as zip or latest releases, extract it (for example to D:\robotframework-magik) and create separate virtualenv:

py -3.14 -m venv D:\pyenv\robot
D:\pyenv\robot\scripts\activate
python -m pip install --upgrade pip
python -m pip install --upgrade -r D:\robotframework-magik\requirements.txt

Now you are able to start the example test via:

D:\pyenv\robot\scripts\activate
cd D:\robotframework-magik
robot --variablefile resources\params\variables_sw43_cbg.py examples

Alternative installations see RobotFramework UserGuide Installation .

History

see CHANGES.rst

Directory Layout

resources/

Definition of Robot Framework Magik keywords

resources/scripts/

Python and Magik scripts to start and stop an image / session with a remote_cli

resources/params/

sample RF variable files defining different SW environment configs

doc/

Documentation for Robot Framework Magik keywords

tests/

self-testig suites for Robot Framework Magik keywords, library and scripts

examples/

Examples, how Robot Framework Magik keywords could be used for automated testing Smallworld Magik images / sessions

Tutorial

The library RobotMagikLauncher.py (and also the Python script robot_start_magik_image.py) implements two different start mechanism for closed and startup images.

• for closed images, the environment variable SW_MSF_STARTUP_MAGIK is used to load the Magik script start_robot_remote_cli.magik, which starts a remote_cli.
• for startup images, the gis launcher command line option -run_script is used to load the script start_robot_remote_cli.script, which adds a startup_procedure to start the remote_cli as last startup action.
• Cause Smallworld 5.x does not support the gis launcher command line option -run_script, Smallworld 5.x sessions must be started using the environment variable SW_MSF_STARTUP_MAGIK

The following examples explains, how the start, test and stop of an image works.

Example A - start gis and run example test completly inside robot

Precondition

• Adjust variable file variables_sw43_cbg.py for your SW4.x image to test
• Adjust variable file variables_sw53_cbg.py for your SW5.x session to test

Expectation:

• Test should start the image / session , run and check a calculation and stop the image / session

run example test under Smallworld 4.x

robot --variablefile resources/params/variables_sw43_cbg.py examples

run example test under Smallworld 5.x

robot --variablefile resources/params/variables_sw53_cbg.py examples

Example B - run tests in a closed image

Precondition

• Alias swaf is defined in the products gis_alias file
• current working directory is robotframework-magik

start the closed image with remote_cli

python resources\scripts\robot_start_magik_image.py --msf_startup e:\Smallworld\CST43\product swaf

• The swaf image is running with a remote_cli, listening on port 14001.
• The gis buffer log-file swaf-mmdd-hhmm-PID.log and pid-file 14001.pid are written to the users temp directory.

run example tests on the closed image

robot --exclude DsView* examples\c*

• run all Non DsView example tests - see [TAGS] label inside the test definition files
• The Robot Framework test reports are written into the current working directory.

stop the closed image

python resources\scripts\robot_stop_magik_image.py

• The image is closed and the pid-file 14001.pid is deleted.

Example C - run tests in a startup image

Precondition

• Alias cam_db_open_swaf is defined in a separate gis_alias file
• current working directory is robotframework-magik

start the startup image with remote_cli

python resources\scripts\robot_start_magik_image.py
       --msf_startup --java_home e:\tools\jre
       --aliasfile e:\test\gis_aliases
       --piddir e:\tmp\robot\pids --logdir e:\tmp\robot\logs
       --login root/  --cli_port 14003 --wait 10
       e:\Smallworld\CST51\product cam_db_open_swaf

• Now the cam_db_open_swaf image is running with a remote_cli, listening on port 14003 under user root.
• The gis buffer log-file cam_db_open_swaf image-mmdd-hhmm-PID.log is written to e:\tmp\robot\logs.
• The pid-file 14003.pid is written to e:\tmp\robot\pids
• The start process has wait 10 seconds for checking the telnet connection.
• starting a SW5.x session requires to define a --java_home and --msf_startup
• definition --java_home can be replace with defining --env_file ENV_FILE, when ENV_FILE includes a JAVA_HOME defintion or when JAVA_HOME is defined globaly

run example and self tests on the startup image

robot --include Keyword* --include Example* --variable CLI_PORT:14003
      --outputdir e:\tmp\robot\logs --xunit cbg_tests.xml
          .\tests .\examples\c*

• The Robot Framework test reports are written into e:\tmp\robot\logs
• Additional XUnit test report cbg_tests.xml is written, which can be used as input for tools that process XUnit data (like CI Server Jenkins).
• Only tests with Keyword and Example tags are run.

stop the startup image

python resources\scripts\robot_stop_magik_image.py
       --piddir e:\tmp\robot\pids --cli_port 14003

The image is closed and the pid-file 14003.pid is deleted.