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.

Prerequisites

Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed.

Java

Galasa tests and Managers are written in Java - you will need to install a Java version 11 JDK or later to use it. Note: We do not currently support Java 17 or later.

Eclipse

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 any missing plug-ins if and when you discover you need them.

You can check the current compatibility between Eclipse and Galasa versions in the table provided in the Getting started using Eclipse documentation.

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

Installing the Galasa plug-in

1. Launch Eclipse. If present, close any initial welcome screen.
2. Choose Help > Install New Software from the main menu.
3. Paste https://p2.galasa.dev/ into the Work with field and press Enter.
4. Tick the Galasa box in the main panel, ensuring that Galasa and all of its child elements are ticked.
5. 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.
6. 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

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

2. Locate your user home directory and confirm it contains a .galasa folder. 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.

3. Edit a file called overrides.properties in your .galasa folder 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

4. Edit a file called credentials.properties in your .galasa folder so that it contains:

   secure.credentials.SIMBANK.username=IBMUSER
   secure.credentials.SIMBANK.password=SYS1

   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.