Robot Framework Magik (RFM)

Copyright 2012-2023 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 deprecated Standalone JAR distribution tests can run in a pure Java environment without a separate python installation. (DEPRECATED)
• 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

A Python 3.11 environment is recommended with Robot Framework Version 6.0.2/6.1 .

good practice is to use a separate virtualenv:

py -3.11 -m venv D:\pyenv\robot
D:\pyenv\robot\scripts\activate
pip install --no-cache-dir robotframework~=6.0

download current master as zip or latest releases and extract it (for example to D:\robotframework-magik). 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 . Or install required packages using sample requirements.txt included in RFM download:

py -3.11 -m venv my_robot_venv
my_robot_venv\scripts\activate
python -m pip install --upgrade pip
python -m pip install --upgrade -r requirements.txt

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_sw5x_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.

Example D - start gis and run example using RD standalone JAR

With last RF 4.1.2 Standalone JAR distribution no robot installation is required, just one java call and robotframework-4.1.2.jar:

java -jar robotframework-4.1.2.jar  --critical DsView* --variablefile resources\params\variables_sw43_cbg.py examples