Installing the Galasa plug-in offline
The Galasa zip file is available from the IBM Mainframe Downloads website and can be downloaded and extracted to a directory of your choice. The zip file contains three directories (eclipse, maven and javadoc), an
isolated.tar file and a
The eclipse directory contains the Galasa plug-in, and the maven directory contains dependencies that are required for building Galasa tests. The javadoc directory contains the Javadoc API documentation for the Galasa Managers.
isolated.tar file is an optional Docker image that hosts all the artifacts. You might want to use the Docker image if you want to host Galasa on an internal server that can be accessed by other users. If you want to host Galasa on your local machine only, you do not need to use the Docker image.
docs.jar file enables you to run the Galasa website locally on your machine or on an internal server. Instructions on how to do this are available in the
README.txt that is provided in the Galasa zip file.
Galasa installations can vary in complexity depending on the context in which it is used. Invariably though, all first-time installations begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. The Galasa plug-in is accompanied by Galasa SimBank - a demonstration application - which sits on top of a very small middleware layer called SimPlatform (you may see its name in some console messages, but you will otherwise not need to interact with SimPlatform).
This section describes the most common initial installation scenario - using Eclipse to install the Galasa plug-in - together with SimPlatform/SimBank - on your local machine and preparing it to run an initial set of provided tests against a simulated mainframe application.
Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed.
Galasa tests and Managers are written in Java - you will need to install a Java version 8 JDK or later to use it.
If you do not already have an Eclipse installation, you can download a version of Eclipse appropriate for your machine. Choose a package that supports your required level of Java development - Eclipse IDE for Java Developers or Eclipse IDE for Java EE Developers. If you are unsure, then the Eclipse IDE for Java Developers should be fine, and you can always add plug-ins if and when you discover you need them.
If you already have a version of Eclipse installed, it should be at the version codenamed Photon (released in June 2018) or later.
You will need to install Gradle version 6.8.2 which is used to build the Galasa software.
Docker (Required if using the Docker image)
If you want to deploy the Docker image that is provided in the zip file, you will need to have Docker installed.
(Optional) A 3270 terminal emulator
Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to explore Galasa Simbank, a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.
Extract the contents of the zip file into a directory of your choice.
If you are using the zipped distribution hosted in Docker, ensure that you have the appropriate privileges to run Docker commands on the server on which you are hosting the Galasa artifacts and complete the following steps to load and run the Docker image:
Note: The example uses port
8080 but you can use a different port.
Within the directory that contains the Docker image (
isolated.tar), run the following command:
docker load -i isolated.tar
The following confirmation message is received: Loaded image: galasadev/galasa-distribution:0.16.0
Run the container by using the following command:
docker run -d -p 8080:80 --name galasa galasadev/galasa-distribution:0.16.0
- Go to
http:\\hostname:8080to view the running container.
You are now ready to install the Galasa plug-in.
- Launch Eclipse. If present, close any initial welcome screen.
- Choose Help > Install New Software from the main menu.
Choose from the following options:
If you have the zip extracted locally, complete the following steps:
- Click Add and then Select Local
- Navigate to the directory into which the zip was extracted, select the Eclipse directory, and click OK
- Check that the
Locationfield is populated with the filepath information, for example,
file:///home/username/galasa-isolated-mvp/eclipse/and press Enter.
- If you are using the Docker hosting mechanism, populate the
Locationfield with the URL to the running container, for example,
http://hostname:8080/eclipseand press Enter.
- Tick the Galasa box in the main panel, ensuring that Galasa and all of its child elements are ticked and press Next.
- Follow the prompts to download and install the Galasa plug-in. You will be asked to accept the terms of the license agreement and restart Eclipse to complete the installation. You may also be asked to acknowledge and agree that you are installing unsigned content.
- After Eclipse has restarted, you can verify that the plug-in is now available by observing the presence of a new Galasa option on the main menu between Run and Window. If you choose Run > Run Configurations from the main menu, you will also observe three new entries: Galasa - Gherkin, Galasa - Java and Galasa SimBank as available options in the left-hand panel of the pop-up window.
Configuring Eclipse for Galasa
Choose Galasa > Setup Galasa Workspace from the main Eclipse menu - this command creates some necessary configuration files. Your Eclipse console confirms its progress with some messages:
Setting up the Galasa workspace Creating the ~/.galasa files Created the ~/.galasa directory Created an empty Bootstrap Properties file ~/.galasa/bootstrap.properties Created an empty Overrides Properties file ~/.galasa/overrides.properties Created an empty Credentials Properties file ~/.galasa/credentials.properties Created an empty CPS Properties file ~/.galasa/cps.properties Created an empty DSS Properties file ~/.galasa/dss.properties The ~/.m2 directory already exists Created the ~/.m2/.settings.xml example file Setup complete
- Locate your user home directory and confirm it contains a
.galasafolder. On Windows, the user home directory resembles:
C:\Users\<username>, on MacOS it will be
/Users/<username>and on Linux
/home/<username>. Note that any file or folder beginning with a
.is a hidden folder, so you might need to change the settings on your operating system to show hidden files.
Edit a file called
.galasafolder so that it contains:
zos.dse.tag.SIMBANK.imageid=SIMBANK zos.dse.tag.SIMBANK.clusterid=SIMBANK simbank.dse.instance.name=SIMBANK simbank.instance.SIMBANK.zos.image=SIMBANK zos.image.SIMBANK.ipv4.hostname=127.0.0.1 zos.image.SIMBANK.telnet.port=2023 zos.image.SIMBANK.webnet.port=2080 zos.image.SIMBANK.telnet.tls=false zos.image.SIMBANK.credentials=SIMBANK zosmf.image.SIMBANK.servers=SIMBANK zosmf.server.SIMBANK.image=SIMBANK zosmf.server.SIMBANK.port=2040 zosmf.server.SIMBANK.https=false
Edit a file called
.galasafolder so that it contains:
Note: If you have previously installed Galasa, this file is already populated.
Your local Eclipse Galasa installation is now ready for some work. Start by exploring Galasa Simbank to help you to learn about the Galasa basics.