From d4c642f83c237772b9a817c7cbafca92bc589688 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 19 Sep 2023 08:52:07 +0100 Subject: [PATCH 1/6] test images --- src/data/nav.yaml | 24 +- src/markdown-pages/doc_root.md | 41 +-- src/markdown-pages/docs/architecture.md | 46 +++ .../cli-command-reference.md | 19 +- .../cli-command-reference/hybridrunmode.svg | 34 ++ .../docs/cli-command-reference/simbank-cli.md | 117 +++++++ .../cli-command-reference/simbank-logon.png | Bin 0 -> 13302 bytes .../docs/first-steps/getting-started.md | 24 +- .../docs/first-steps/installing-offline.md | 33 +- .../docs/first-steps/installing-online.md | 21 +- .../docs/first-steps/prerequisites.md | 94 ++++++ .../docs/first-steps/simbank.md | 14 +- .../docs/running-simbank-tests.md | 181 +--------- .../basic-account-credit-test.md | 2 +- .../provisioned-account-credit-tests.md | 2 +- .../setting-up-galasa-project-eclipse.md | 314 ++++++++++++++++++ .../docs/running-simbank-tests/simbank-IVT.md | 14 +- .../setting-up-galasa-project.md | 27 +- 18 files changed, 686 insertions(+), 321 deletions(-) create mode 100644 src/markdown-pages/docs/architecture.md create mode 100644 src/markdown-pages/docs/cli-command-reference/hybridrunmode.svg create mode 100644 src/markdown-pages/docs/cli-command-reference/simbank-cli.md create mode 100644 src/markdown-pages/docs/cli-command-reference/simbank-logon.png create mode 100644 src/markdown-pages/docs/first-steps/prerequisites.md create mode 100644 src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md diff --git a/src/data/nav.yaml b/src/data/nav.yaml index e061cb13..3e0468f5 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -1,9 +1,9 @@ -# -# Copyright contributors to the Galasa project -# -# SPDX-License-Identifier: EPL-2.0 -# - +# +# Copyright contributors to the Galasa project +# +# SPDX-License-Identifier: EPL-2.0 +# + - sections: - title: Releases root: /releases/ @@ -28,14 +28,20 @@ - title: Docs root: /docs/ items: - - title: Introduction and architecture + - title: Galasa Architecture + path: /docs/architecture + - title: Downloading and Installing path: /docs/ + - title: Prerequisites + path: /docs/prerequisites - title: Getting started using the Galasa CLI path: /docs/cli-command-reference/cli-command-reference items: - title: Initialising your local environment path: /docs/initialising-home-folder - - title: Creating a project + - title: Exploring Galasa SimBank + path: /docs/cli-command-reference/simbank-cli + - title: Creating a project using the CLI path: /docs/writing-own-tests/setting-up-galasa-project - title: Running a test locally path: /docs/cli-command-reference/cli-runs-submit-local @@ -50,6 +56,8 @@ path: /docs/getting-started/installing-offline - title: Exploring Galasa SimBank path: /docs/getting-started/simbank + - title: Creating a project using Eclipse + path: /docs/running-simbank-tests/setting-up-galasa-project-eclipse - title: Running the supplied SimBank tests path: /docs/running-simbank-tests items: diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 1450130d..a28f4f4c 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -1,45 +1,22 @@ --- path: "/docs" -title: "Introduction" +title: "Downloading and installing" --- -This hub page contains links to the main Galasa documentation. To get going with Galasa as quickly as possible, explore the [Getting started](/docs/getting-started) section. Read on to learn a little about Galasa's architecture first. -# Galasa's architecture -At its top level, Galasa decomposes into three major components: +There are a few options available for downloading and installing Galasa. Prerequisites vary, depending on the options that are chosen. -* The underlying core Galasa framework -* A collection of Managers -* A test runner -*Galasa's key components (not all Managers are currently implemented)* -![Galasa architecture](galasa-architecture-framework.svg) +## Download and Install options -## The core framework -Galasa's core framework orchestrates all component activities, and co-ordinates with the test runner to actually execute your tests. You never have to write code to *invoke* your tests - you just write the code that defines them, as a set of one or more test classes and the methods within. +You can download Galasa as a binary of the Galasa CLI tool from the GitHub `cli` repository, or as an Eclipse plug-in, which can be downloaded either directly from an external update site, or as a zip file (zipped distribution). -The Galasa framework automatically recognizes your test definitions, and launches the required Managers and the test runner to provision and execute them. All without you having to explicitly invoke them. +The Galasa binary that is stored in the `cli` repository is installed by using the Galasa command line (Galasa CLI). The benefit of using the command-line to install Galasa is that much of the configuration set-up that is required is done for you automatically by scripts, so there is less manual intervention needed. You can then import the configuration into an IDE of your choice. -It is unlikely that you will need to change the framework or test runner code during the normal range of testing activities. +If you are using only Eclipse for your IDE, you might choose to download the Galasa Eclipse plug-in directly from the external update site or as a zipped distribution. Users without restricted internet access who want to use open-source Galasa, can install the Galasa Eclipse plug-in directly. The zipped distribution of Galasa allows users who do not have access to Maven Central, Eclipse Marketplace and Docker Hub from their company network to use Galasa. -For more information about the benefits of using a framework for your automated testing, see the [Benefits of Galasa](../about/automation) section. -## Managers -The two main purposes of a Manager are to reduce the amount of boilerplate code within a test and provide proven tool interaction code. This makes the test code simpler and easier to write, understand and maintain, as the focus of a test's development shifts to validating application changes, rather than marshalling environmental resources. +## Next steps -Sometimes, Managers perform a range of general-purpose services, and at other times, they are much more focused. For example, the HTTPClientManager contains a wide range of facilities you might expect from a programmable HTTP client, while the DB2Manager confines its scope to a range of DB2 interactions. +Once you have decided on your download and install options, take a look at the [Prerequisites](../markdown-pages/docs/prerequisites) documentation to find out what software you need to install. -Different Managers can collaborate with each other to perform a joint task, including sharing information and getting other Managers to complete tasks for them. This work is coordinated by the Galasa framework. - -Three types of Manager are delivered with Galasa: - -* *Core Managers*: a set of central, fundamental Managers with wide-ranging use. Examples include *zosFileManager*, *zosBatchManager* and *zosCommandManager*. These are part of the core Galasa distribution. -* *Product Managers*: a set of Managers responsible for test interactions with specific products, for example *CICSManager*, *WMQManager* and *DB2Manager*. Again, some product Managers will be part of the core Galasa distribution but it is also possible that your team may write its own Manager for a specialty product used in your organization. -* *Other, or ancillary Managers*: a set of Managers to orchestrate the integration of a range of useful software tools and components, such as *SeleniumManager*, *JMeterManager* and *DockerManager*. It is likely that you will write your own Managers to expose the services of similar tools and components used within your team. - -### Application-specific Managers -As well as consuming the services of Managers either delivered with Galasa or written by others, you may need to write a Manager specific to your application under test - an *application-specific Manager*. This is to abstract *application-specific* boilerplate functionality into a single place, removed from the tests themselves. - -A [summary table describing Managers](/docs/managers) that are currently available or planned for future releases is available in the Managers topic. - -## The test runner -Under the direction of the core framework, the Galasa test runner is responsible for actually executing your tests. \ No newline at end of file +You can then choose to view either the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation or the [Getting started using Eclipse](/docs/getting-started) documentation. diff --git a/src/markdown-pages/docs/architecture.md b/src/markdown-pages/docs/architecture.md new file mode 100644 index 00000000..24ef79a9 --- /dev/null +++ b/src/markdown-pages/docs/architecture.md @@ -0,0 +1,46 @@ +--- +path: "/docs/architecture" +title: "Architecture" +--- + +Read on to learn a little about Galasa's architecture and key components. + +# Galasa's architecture +At its top level, Galasa decomposes into three major components: + +* The underlying core Galasa framework +* A collection of Managers +* A test runner + +*Galasa's key components (not all Managers are currently implemented)* +![Galasa architecture](../galasa-architecture-framework.svg) + +## The core framework +Galasa's core framework orchestrates all component activities, and co-ordinates with the test runner to actually execute your tests. You never have to write code to *invoke* your tests - you just write the code that defines them, as a set of one or more test classes and the methods within. + +The Galasa framework automatically recognizes your test definitions, and launches the required Managers and the test runner to provision and execute them. All without you having to explicitly invoke them. + +It is unlikely that you will need to change the framework or test runner code during the normal range of testing activities. + +For more information about the benefits of using a framework for your automated testing, see the [Benefits of Galasa](../about/automation) section. + +## Managers +The two main purposes of a Manager are to reduce the amount of boilerplate code within a test and provide proven tool interaction code. This makes the test code simpler and easier to write, understand and maintain, as the focus of a test's development shifts to validating application changes, rather than marshalling environmental resources. + +Sometimes, Managers perform a range of general-purpose services, and at other times, they are much more focused. For example, the HTTPClientManager contains a wide range of facilities you might expect from a programmable HTTP client, while the DB2Manager confines its scope to a range of DB2 interactions. + +Different Managers can collaborate with each other to perform a joint task, including sharing information and getting other Managers to complete tasks for them. This work is coordinated by the Galasa framework. + +Three types of Manager are delivered with Galasa: + +* *Core Managers*: a set of central, fundamental Managers with wide-ranging use. Examples include *zosFileManager*, *zosBatchManager* and *zosCommandManager*. These are part of the core Galasa distribution. +* *Product Managers*: a set of Managers responsible for test interactions with specific products, for example *CICSManager*, *WMQManager* and *DB2Manager*. Again, some product Managers will be part of the core Galasa distribution but it is also possible that your team may write its own Manager for a specialty product used in your organization. +* *Other, or ancillary Managers*: a set of Managers to orchestrate the integration of a range of useful software tools and components, such as *SeleniumManager*, *JMeterManager* and *DockerManager*. It is likely that you will write your own Managers to expose the services of similar tools and components used within your team. + +### Application-specific Managers +As well as consuming the services of Managers either delivered with Galasa or written by others, you may need to write a Manager specific to your application under test - an *application-specific Manager*. This is to abstract *application-specific* boilerplate functionality into a single place, removed from the tests themselves. + +A [summary table describing Managers](/docs/managers) that are currently available or planned for future releases is available in the Managers topic. + +## The test runner +Under the direction of the core framework, the Galasa test runner is responsible for actually executing your tests. \ No newline at end of file diff --git a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md index efda9781..a9effdf7 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md @@ -5,21 +5,6 @@ title: "Getting started using the Galasa CLI" Use the Galasa command line interface (Galasa CLI) to help you complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. -## Installing the CLI tool - -You can [download the CLI tool](https://github.com/galasa-dev/cli/releases) from the _cli_ repository in GitHub. - -The following versions of the Galasa CLI tool are available to download for different operating systems: - -| Operating system | Download | -| :---- | :-------- | -| MacOSX | galasactl-darwin-x86_64 | -| MacOSX | galasactl-darwin-arm64 | -| Linux 64-bit x86 | galasactl-linux-x86_64 | -| Linux arm64 | galasactl-linux-arm64 | -| zLinux | galasactl-linux-s390x | -| Windows | galasactl-windows-x86_64.exe | - ## Getting started @@ -27,8 +12,8 @@ Complete the following steps to start running the Galasa CLI tool: On Mac or Unix: -1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. -2. Download the appropriate binary for your machine architecture and re-name it to `galasactl`. +1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. +2. Download the appropriate binary of the [Galasa CLI tool](https://github.com/galasa-dev/cli/releases) for your machine architecture from the _cli_ repository in GitHub and re-name it to `galasactl`. 3. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. For example, ```export PATH=${PATH}:/my/folder/containing/galasactl```. 4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. 5. Set permission to open the CLI tool by running the `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command. diff --git a/src/markdown-pages/docs/cli-command-reference/hybridrunmode.svg b/src/markdown-pages/docs/cli-command-reference/hybridrunmode.svg new file mode 100644 index 00000000..899047bd --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/hybridrunmode.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md new file mode 100644 index 00000000..c0e7b27f --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md @@ -0,0 +1,117 @@ +--- +path: "/docs/cli-command-reference/simbank-cli" +title: "Exploring Galasa SimBank using the CLI" +--- +Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform, which exists to provide options for future growth. As delivered, SimBank implements a sample banking application against which you can configure and run a set of provided tests in preparation for running your own tests against an *actual* mainframe application. You can also practice writing some new tests to run against the SimBank banking application. + +By exercising the Galasa framework against SimBank, you can pre-empt a lot (but not all) of the work and learning necessary to eventually hook your own tests up with a genuine mainframe environment. If the provided SimBank tests do not work, then it is unlikely that you will be able to run your own tests on a mainframe application. In summary, SimBank helps you to learn Galasa's basic principles of operation before you need to learn how to connect Galasa to your own mainframe application-under-test. + +## Launching SimBank + +This repository contains the Galasa SimBank Eclipse plug-in, SimBank applications and set of sample SimBank tests. + +If you have previously started SimBank, then choose *Run > Run Configurations* from the main menu and select and run the configuration that you created for SimBank. If not, complete the following steps: + +1. Clone the Galasa `simplatform` repository on your machine by running the following command in the directory on your local machine in which you want to clone the repository files: + ``` + git clone https://github.com/galasa-dev/simplatform.git + ``` +2. Run the `./build-locally.sh` script to build the code. +3. Run the `./run-locally.sh --server` script to start the simbank server inside a local JVM. +In a few seconds, the terminal window responds with a series of initialization messages, which on Windows looks like: +``` +2019-10-21 14:24:35 INFO dev.galasa.simplatform.main.Simplatform main Starting Simplatform ... +2019-10-21 14:24:35 INFO dev.galasa.simplatform.db.Database setDerbyHome Setting Derby home to C:\Users\\AppData\Local\Temp\galasaSimplatform1440125512154994774 +2019-10-21 14:24:36 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility Creating SAF service +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Checking if account: 123456789 exists +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Account doesn't exist +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank openAccount Creating account: 123456789 +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Checking if account: 987654321 exists +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Account doesn't exist +2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank openAccount Creating account: 987654321 +2019-10-21 14:24:36 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility addUser Added user: IBMUSER +2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main Loading services... +2019-10-21 14:24:36 INFO dev.galasa.simplatform.listener.Listener Loading service: dev.galasa.simplatform.listener.WebServiceListener listening on port: 2080 +2019-10-21 14:24:36 INFO dev.galasa.simplatform.listener.Listener Loading service: dev.galasa.simplatform.listener.TelnetServiceListener listening on port: 2023 +2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main ... services loaded +2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main Starting Derby Network server.... +2019-10-21 14:24:37 INFO dev.galasa.simplatform.main.Simplatform main ... Derby Network server started on port 2027 +2019-10-21 14:24:37 INFO dev.galasa.simplatform.main.Simplatform main ... Simplatform started +``` +If you are a Mac or Linux user, the messages will be almost identical. + +4. The SimBank process has been launched, and is listening on port *2023* for Telnet connections, on port *2080* for web services connections and on port *2027* for Derby SQL connections. Neither web services or Derby connections are explored further in this section. + +## Manually exploring the SimBank application +When you launch SimBank, its banking application listens on port 2023 for incoming client Telnet connections, offering an opportunity to first connect to it manually to review and understand the (simulated) transactions it supports, before subjecting it to Galasa's provided tests. + +### Logging in to the simulated application +1. With the *Galasa SimBank* component still running, configure your 3270 terminal emulator to access port *2023* of *localhost* (or IP address 127.0.0.1 if the *localhost* alias has not been set up) via the Telnet protocol. No SSL configuration is required. +1. Connect to the listening Telnet service with your 3270 emulator and review the logon screen: + + ![SimBank logon screen](simbank-logon.png) + +1. Ensure that the cursor is in the `Userid` field - if it is not, use the TAB key to position it: + + ![TAB to the userid field](simbank-userid.png) + +1. Enter the userid `IBMUSER` + + ![Enter your userid](./simbank-ibmuser.png) + +1. Press TAB to move the cursor into the `Password` field, type the password `SYS1` and press your terminal emulator's ENTER key to logon and transfer to the SimBank main menu: + + ![Banktest home screen](./simbank-banktest.png) + +> *Note:* Depending on your terminal emulator, its ENTER key may not be mapped to the physical ENTER key on your computer. For example, +> on PCOMM, by default, the ENTER key is mapped to the host machine's right CTRL key. If you are unsure about this, review +> your terminal emulator's documentation. + +6. Press PF1: + + ![CICS home screen](../first-steps/simbank-cics.png) + +1. Press your terminal emulator's CLEAR SCREEN key. +1. Enter the transaction name `BANK` and press your terminal emulator's ENTER key once more to get to the SimBank main menu: + + ![Main banking menu](../first-steps/simbank-mainmenu.png) + +As you have been progressing through this process, selected events are logged: + +``` +2019-08-16 09:26:39 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: SessionManagerLogon +2019-08-16 10:26:08 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility authenticate User: IBMUSER authenticated +2019-08-16 10:26:08 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: SessionManagerMenu +2019-08-16 10:30:10 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: CICSGoodMorning +2019-08-16 10:36:19 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: CICSClearScreen +2019-08-16 10:38:54 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: BankMainMenu +``` +This is an example of log output that can be useful when running tests. +### Browsing account information +1. From the SimBank main menu, press PF1, taking you to the account menu screen. +1. Press TAB until the cursor is in the `Account Number` field, enter `123456789` and press ENTER. + The account details are populated and it is apparent that account number 123456789 is 56.72 in credit. + + ![Account balance](../first-steps/simbank-balance.png) + +1. Press PF3 to return to the account menu screen. + +### Transferring funds between accounts +1. From the SimBank main menu, press PF4, taking you to the SimBank transfer menu. +1. Press TAB until the cursor is in the `Transfer from Account Number` field and enter `123456789`. +1. Press TAB until the cursor is in the `Transfer to Account Number` field and enter `987654321`. +1. Press TAB until the cursor is in the `Transfer Amount` field and enter `1` + + ![Inter-account transfer](../first-steps/simbank-transfer.png) + +1. Press ENTER - a `Transfer Successful` message appears. A log message is also written to the terminal window: + +``` +2019-08-16 13:50:53 INFO dev.galasa.simplatform.application.Bank transferMoney Transfering 1.0 from account: 123456789 to account: 987654321 +``` + +Press PF3 and once again browse the 123456789 account as described previously to verify that its total credit has decreased by the transferred 1.00, and that the 987654321 account has increased by the same amount. + +Note that SimBank also offers a web services interface on port 2080, and although it is not exercised in this topic, it *is* used by two of the provided tests - `BasicAccountCreditTest.java` and `ProvisionedAccountCreditTests.java`. + +Having explored SimBank manually, it's a good time to run some or all of a small collection of automated tests that are provided with SimBank itself - to start, choose _Running the supplied SimBank tests_ in the side-menu. \ No newline at end of file diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-logon.png b/src/markdown-pages/docs/cli-command-reference/simbank-logon.png new file mode 100644 index 0000000000000000000000000000000000000000..85e15999cbb8aaa80a4070ff7d72200c345f285c GIT binary patch literal 13302 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

LI?w93SfIea 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: We currently support Java version 11 to version 16 JDK. We do not currently support Java 17 or later. If your Eclipse version comes with Java 17 or later, ensure that the JRE environment refers to a Java 11 runtime in your Eclipse launch configuration. - -You can tell Eclipse about an installed runtime by going to _Settings_>_Java_>_Installed JREs_ from the Eclipse menu, and adding the Java 11 runtime to the list of installed JREs. You can set this runtime as default so that Eclipse launches tests with a Java 11 runtime. - -## Installing +You can download Galasa either from a downloadable zip file (zipped distribution) or directly from an external update site. For more information about these options, see the [Introduction](/docs/doc_root) documentation. To install the Galasa plug-in from the external update site, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index edfd173d..05d79d56 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -5,7 +5,8 @@ title: "Installing the Galasa plug-in offline" The Galasa _isolated.zip_ file is available from the https://resources.galasa.dev/ site 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 `docs.jar` file. -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. +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. The `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. @@ -13,37 +14,17 @@ The `docs.jar` file enables you to run the Galasa website locally on your machin ## Getting started -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). +If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. + +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. +This section describes 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 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](/docs/getting-started) documentation. - -### Gradle - -You will need to install Gradle, which is used to build the Galasa software. You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Creating a Galasa project](/docs/writing-own-tests/setting-up-galasa-project) documentation. - -### 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. +Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed. For a full list of prerequisites, see the [Prerequisites](prerequisites) documentation. ## Getting started diff --git a/src/markdown-pages/docs/first-steps/installing-online.md b/src/markdown-pages/docs/first-steps/installing-online.md index 12fbe771..73fb5b78 100644 --- a/src/markdown-pages/docs/first-steps/installing-online.md +++ b/src/markdown-pages/docs/first-steps/installing-online.md @@ -3,29 +3,18 @@ path: "/docs/getting-started/installing-online" title: "Installing the Galasa plug-in" --- -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). +If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. + +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. +This section describes 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](/docs/getting-started) documentation. - -### (Optional) A 3270 terminal emulator +Depending on how you plan to use Galasa, there are several software prerequisites, some or all of which you may have already installed. For a full list of prerequisites, see the [Prerequisites](prerequisites) documentation. -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 diff --git a/src/markdown-pages/docs/first-steps/prerequisites.md b/src/markdown-pages/docs/first-steps/prerequisites.md new file mode 100644 index 00000000..b6afea29 --- /dev/null +++ b/src/markdown-pages/docs/first-steps/prerequisites.md @@ -0,0 +1,94 @@ +--- +path: "/docs/prerequisites" +title: "Galasa Prerequisites" +--- + +This section takes you through the software prerequisites required before installing Galasa. The prerequisites vary, depending on the version of Galasa that you download and the option you use to install it. + +For information about the download and install options available, see the [Introduction](../../about_Galasa.md) documentation. + +### Java JDK + +Required. 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. + +### Maven + +Maven is required if you want to use Maven rather than Gradle to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. + +Maven is an Open Source build automation tool, initially created in 2003 and part of the Apache Software Foundation. If you are using Eclipse, you do not explicitly need to install it because the Galasa plugin downloads and installs it silently during its own installation and configuration. If you have already installed Maven as part of some other software project, no action is needed. + +### Galasa command line tool (Galasa CLI) + +Required if you want to use the Galasa CLI to interact with Galasa. You can [download the CLI tool](https://github.com/galasa-dev/cli/releases) from the _cli_ repository in GitHub. + +The following versions of the Galasa CLI tool are available to download for different operating systems and machine architectures: + +| Operating system | Download | +| :---- | :-------- | +| MacOSX | galasactl-darwin-x86_64 | +| MacOSX | galasactl-darwin-arm64 | +| Linux 64-bit x86 | galasactl-linux-x86_64 | +| Linux arm64 | galasactl-linux-arm64 | +| zLinux | galasactl-linux-s390x | +| Windows | galasactl-windows-x86_64.exe | + +*Note:* You can find out the architecture of your machine by typing the command `uname -m` into your Mac or Linux terminal. + +### Eclipse + +If you are planning to install and use Galasa with Eclipse, you need to have an Eclipse installation on your machine. 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. + +The following table shows the current compatibility between Eclipse and Galasa versions: + + +| Eclipse level | Compatible Galasa version | +| :---- | :-------- | +| 2023-03 | 0.27.0 and later | +| 2022-09 | 0.27.0 and later | +| 2022-06 | 0.26.0, 0.25.0 | + +Note: We currently support Java version 11 to version 16 JDK. We do not currently support Java 17 or later. If your Eclipse version comes with Java 17 or later, ensure that the JRE environment refers to a Java 11 runtime in your Eclipse launch configuration. + +You can tell Eclipse about an installed runtime by going to _Settings_>_Java_>_Installed JREs_ from the Eclipse menu, and adding the Java 11 runtime to the list of installed JREs. You can set this runtime as default so that Eclipse launches tests with a Java 11 runtime. + +### Gradle + +Gradle is required if you are installing the zipped distribution of Galasa, or if you want to use Gradle rather than Maven to build Galasa projects (hierarchical file structures that provide the ability to store and run Galasa tests). + +Gradle is an Open Source build automation tool, initially created in 2008. If you have already installed Gradle as part of some other software project, no action is needed. + +The following table shows the current compatibility between Gradle and Galasa versions: + + +| Gradle release | Compatible Galasa version | +| :---- | :-------- | +| 6.8.x | All | +| 6.9.x | All | +| 7.x.x | All | + + +### 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. + +### A 3270 terminal emulator (Optional) + +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. + + +Once you have installed the relevant software, you are ready to install Galasa. + + +## Installing + +To install the Galasa plug-in using the command line, follow the instructions in [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference). + +To install the Galasa plug-in from the external update site, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). + +To install the Galasa plug-in using the zipped distribution, follow the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). + + +## Next steps + +You can then start exploring Galasa Simbank; a component distributed with Galasa that you can start playing with to help you to learn about the Galasa basics. + diff --git a/src/markdown-pages/docs/first-steps/simbank.md b/src/markdown-pages/docs/first-steps/simbank.md index 9b89be55..82d4b944 100644 --- a/src/markdown-pages/docs/first-steps/simbank.md +++ b/src/markdown-pages/docs/first-steps/simbank.md @@ -1,6 +1,6 @@ --- path: "/docs/getting-started/simbank" -title: "Exploring Galasa SimBank" +title: "Exploring Galasa SimBank using Eclipse" --- Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform, which exists to provide options for future growth. As delivered, SimBank implements a sample banking application against which you can configure and run a set of provided tests in preparation for running your own tests against an *actual* mainframe application. You can also practice writing some new tests to run against the SimBank banking application. @@ -45,11 +45,11 @@ When you launch SimBank, its banking application listens on port 2023 for incomi 1. With Eclipse and the *Galasa SimBank* component still running, configure your 3270 terminal emulator to access port *2023* of *localhost* (or IP address 127.0.0.1 if the *localhost* alias has not been set up) via the Telnet protocol. No SSL configuration is required. 1. Connect to the listening Telnet service with your 3270 emulator and review the logon screen: - ![SimBank logon screen](./simbank-logon.png) + ![SimBank logon screen](simbank-logon.png) 1. Ensure that the cursor is in the `Userid` field - if it is not, use the TAB key to position it: - ![TAB to the userid field](./simbank-userid.png) + ![TAB to the userid field](simbank-userid.png) 1. Enter the userid `IBMUSER` @@ -65,12 +65,12 @@ When you launch SimBank, its banking application listens on port 2023 for incomi 6. Press PF1: - ![CICS home screen](./simbank-cics.png) + ![CICS home screen](../first-steps/simbank-cics.png) 1. Press your terminal emulator's CLEAR SCREEN key. 1. Enter the transaction name `BANK` and press your terminal emulator's ENTER key once more to get to the SimBank main menu: - ![Main banking menu](./simbank-mainmenu.png) + ![Main banking menu](../first-steps/simbank-mainmenu.png) As you have been progressing through this process, Eclipse has been logging selected events to its console: @@ -88,7 +88,7 @@ This is an example of log output that can be useful when running tests. 1. Press TAB until the cursor is in the `Account Number` field, enter `123456789` and press ENTER. The account details are populated and it is apparent that account number 123456789 is 56.72 in credit. - ![Account balance](./simbank-balance.png) + ![Account balance](../first-steps/simbank-balance.png) 1. Press PF3 to return to the account menu screen. @@ -98,7 +98,7 @@ This is an example of log output that can be useful when running tests. 1. Press TAB until the cursor is in the `Transfer to Account Number` field and enter `987654321`. 1. Press TAB until the cursor is in the `Transfer Amount` field and enter `1` - ![Inter-account transfer](./simbank-transfer.png) + ![Inter-account transfer](../first-steps/simbank-transfer.png) 1. Press ENTER - a `Transfer Successful` message appears. A log message is also written to the Eclipse *Console* window: diff --git a/src/markdown-pages/docs/running-simbank-tests.md b/src/markdown-pages/docs/running-simbank-tests.md index 7903e658..dc5c0874 100644 --- a/src/markdown-pages/docs/running-simbank-tests.md +++ b/src/markdown-pages/docs/running-simbank-tests.md @@ -10,175 +10,26 @@ Galasa SimBank comes with a selection of prepared Galasa tests: - A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. - A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. -All of these example tests become available when you set up a Galasa example project within Eclipse. +The following sections explain how to run the `SimBankIVT` test class by using the Galasa CLI and by using Eclipse. -If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](#headmaven) section. +## Running the SimBank IVT test class using the Galasa CLI -If you are using the Galasa plug-in from the external update site and are using Gradle, follow the instructions in the [_Creating an example Galasa project using Gradle_](#headonlinegradle) section. -If you are using the Galasa zipped distribution you must use Gradle to build your project, so follow the instructions in the [_Creating an example Galasa project using Gradle (zipped distribution)_](#headgradle) section. +## Running the SimBank IVT test class using Eclipse -Note that there are some variations in the Eclipse interface, depending on the version of Eclipse that you are using. +1. Create your initial example projects as described in Running the supplied SimBank tests - a once-only activity. +1. Ensure that Eclipse is running, your example projects are open and that you have launched SimBank as described in Exploring SimBank. +1. Choose _Run > Run Configurations_ and look for and select _Galasa - Java_ in the left pane (not Galasa SimBank). +1. Right-click _Galasa_, choose _New Configuration_ and give it a name. +1. In the dialog, choose _Browse_ to locate your project - `dev.galasa.simbank.tests`, then press _OK_. Then press _Search_ to locate your test class, `SimBankIVT` and press _OK_. +1. Press _Apply_ then _Run_. +1. The `SimBankIVT` test class runs, and the Eclipse console displays their progress through to completion - you will see a console message like:
+ `INFO dev.galasa.boot.Launcher.launch - Boot complete` +
+ when the tests have finished. You will also see a _live terminal_ window in which the interactions with the 3270 terminal are captured - you can use the attached controls to step back and forth along the sequence of screens. +1. View the results of the test runs in Eclipse. Find out more in the [Viewing test results](/docs/running-simbank-tests/viewing-test-results) documentation. -## Creating an example Galasa project using Maven -NOTE: Normally m2e (the Eclipse Maven plug-in) automatically compiles the test bundles and produces the necessary manifest and OSGi files. However, there appears to be an anomaly in m2e in the 2019 versions of Eclipse which we are investigating. If the bundles fail to build correctly, you can force the Maven build by right-clicking the _project_ and selecting _Run As > Maven Install_. We will resolve this issue in a future release. - -1. Ensure that Eclipse is running. -2. Choose _File > New > Example_, select _SimBank example Maven projects_ and click _Next_. -3. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), two new entries appear: - ``` - dev.galasa.simbank.manager - dev.galasa.simbank.tests - ``` -4. Right-click on `dev.galasa.simbank.manager` and choose _Run As > Maven install_ - wait a few moments for the Maven build and then right-click on `dev.galasa.simbank.tests` and do the same. Note that the order in which you do this is significant - first `dev.galasa.simbank.manager` and then `dev.galasa.simbank.tests`. This is because the SimBank tests have a dependency on the SimBank Manager. -5. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. -6. Explore the `dev.galasa.simbanks.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./provided-tests.png) - -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. - -## Creating an example Galasa project using Gradle - -1. Ensure that Eclipse is running. -2. Depending on your operating system, choose either _Window > Preferences_ or _Eclipse > Preferences_, check that you are using the correct version of Gradle. -3. Choose _File > New > Example_, select _SimBank example Gradle projects_ and click _Next_. -4. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), three new entries appear: - ``` - dev.galasa.simbank.manager - dev.galasa.simbank.parent - dev.galasa.simbank.tests - ``` -5. In Project Explorer, right-click on `dev.galasa.simbank.parent` and select _Gradle > Refresh Gradle Project_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab when the project is refreshed successfully.
- Note: If you get an error connecting to the Gradle build, go to _Window > Preferences > Gradle_, check the _Local installation directory_ box, browse to the folder in which you installed Gradle and click _OK_ and _Apply and Close_. -6. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. -7. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. -8. Provide a meaningful name and set up your Gradle Task to run a clean build. - ![SimBank tests](./clean-build.png) -9. In _Working Directory_, click *Workspace*, select `dev.galasa.simbank.parent` and click `OK`. -10. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. -11. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. -12. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./gradle-tests.png) - -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. - - -## Creating an example Galasa project using Gradle (zipped distribution) - -1. Ensure that Eclipse is running. -2. Depending on your operating system, choose either _Window > Preferences_ or _Eclipse > Preferences_, check that you are using the correct version of Gradle, and then select `Galasa` from the left hand pane. -3. Change the _Remote Maven URI_ to the local Maven directory, for example, `file:///home/username/galasa-isolated-mvp/maven` to enable running tests to access any dependencies.
- Note: If you are using the Docker image, set the URL to the running container, for example, `http://hostname:8080/maven`. -4. Click _Apply and Close_. -5. Choose _File > New > Example_, select _SimBank example Gradle projects_ and click _Next_. -6. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), three new entries appear: - ``` - dev.galasa.simbank.manager - dev.galasa.simbank.parent - dev.galasa.simbank.tests - ``` -7. Add a `pluginManagement` section, at the top of the `settings.gradle` file in `dev.galasa.simbank.parent` so that the Gradle build can search the Maven directory for any required plug-ins. Specify the Maven repository as the location of the unzipped Maven directory. For example: - ```dev.galasa.simbank.parent - settings.gradle file - pluginManagement { - repositories { - maven { - url = "file:///home/username/galasa-isolated-mvp/maven" - } - } - } - ``` - Note: If you are using the Docker image, set the URL to the running container. For example: - ```dev.galasa.simbank.parent - settings.gradle file - pluginManagement { - repositories { - maven { - url = "http://hostname:8080/maven" - } - } - } - ``` -8. In `dev.galasa.simbank.manager`, modify the `build.gradle` file: - 1. In the repositories closure, replace `mavenCentral()` with the location of the unzipped Maven directory so that the individual projects can locate any dependencies that they might require for building. For example: - ```dev.galasa.simbank.manager - build.gradle file - repositories { - maven { - url = "file:///home/username/galasa-isolated-mvp/maven" - } - } - ``` - Note: If you are using the Docker image, set the URL to the running container. For example: - ```dev.galasa.simbank.manager - build.gradle file - repositories { - maven { - url = "http://hostname:8080/maven" - } - } - ``` - 2. Modify the dependencies closure by adding the following constraints: - ```dev.galasa.simbank.manager - build.gradle file - constraints { - implementation('commons-codec:commons-codec:1.15'){ - because "Force specific version of commons-codec for security reasons" - } - implementation('org.apache.httpcomponents:httpcore:4.4.14'){ - because "Force specific version of httpcore for security reasons" - } - } - ``` -9. In `dev.galasa.simbank.tests`, modify the `build.gradle` file: - 1. In the repositories closure, replace `mavenCentral()` with the location of the unzipped Maven directory. For example: - ```dev.galasa.simbank.tests - build.gradle file - repositories { - maven { - url = "file:///home/username/galasa-isolated-mvp/maven" - } - } - ``` - Note: If you are using the Docker image, set the URL to the running container. For example: - ```dev.galasa.simbank.tests - build.gradle file - repositories { - maven { - url = "http://hostname:8080/maven" - } - } - ``` - 2. Modify the Selenium Manager dependency to remove packages that are not required. Change the dependency from: - ```dev.galasa.simbank.tests - build.gradle file - implementation'dev.galasa:dev.galasa.selenium.manager:0.+' - ``` - to: - ```dev.galasa.simbank.tests - build.gradle file - implementation('dev.galasa:dev.galasa.selenium.manager:0.+'){ - exclude group: 'com.squareup.okio', module: 'okio' - exclude group: 'com.squareup.okhttp3', module: 'okhttp' - exclude group: 'net.bytebuddy', module: 'byte-buddy' - exclude group: 'org.apache.commons', module: 'commons-exec' - exclude group: 'com.google.guava', module: 'guava' - } - ``` - 3. Modify the dependencies closure by adding the following constraints: - ```dev.galasa.simbank.tests - build.gradle file - constraints { - implementation('commons-codec:commons-codec:1.15'){ - because "Force specific version of commons-codec for security reasons" - } - implementation('org.apache.httpcomponents:httpcore:4.4.14'){ - because "Force specific version of httpcore for security reasons" - } - } - ``` -10. Ensure that you save the modifications that you made to the files. -11. In Project Explorer, right-click on `dev.galasa.simbank.parent` and select _Gradle > Refresh Gradle Project_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab when the project is refreshed successfully.
- Note: If you get an error connecting to the Gradle build, go to _Window > Preferences > Gradle_, check the _Local installation directory_ box, browse to the folder in which you installed Gradle and click _OK_ and _Apply and Close_. -12. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. -13. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. -14. Provide a meaningful name and set up your Gradle Task to run a clean build. -15. In _Working Directory_, click *Workspace*, select `dev.galasa.simbank.parent` and click `OK`. -16. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. -17. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. -18. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./gradle-tests.png) - -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. +## Next steps +Explore the SimBankIVT test and the other SimBank tests in the following sections. Follow the flow of logic in these classes and understand more about the Java that is used to create them, including how to use Galasa annotations and review documented test methods. \ No newline at end of file diff --git a/src/markdown-pages/docs/running-simbank-tests/basic-account-credit-test.md b/src/markdown-pages/docs/running-simbank-tests/basic-account-credit-test.md index ef5155a5..138da0bf 100644 --- a/src/markdown-pages/docs/running-simbank-tests/basic-account-credit-test.md +++ b/src/markdown-pages/docs/running-simbank-tests/basic-account-credit-test.md @@ -4,7 +4,7 @@ title: "BasicAccountCreditTest" --- This test updates a Galasa SimBank account using web services and examines the changes via some 3270 screens, illustrating how to use web services to interface with the SimBank application, and how to create and use Java methods that you do not wish to be recognized as test methods. -To run this test, follow the same steps as for `SimBankIVT.java` but using the test class name `BasicAccountCreditTest` instead of `SimBankIVT`. Don't forget that you need to launch [Galasa SimBank](/docs/getting-started/simbank) before running the test. +To run this test, follow the same steps as for `SimBankIVT.java` but using the test class name `BasicAccountCreditTest` instead of `SimBankIVT`. Don't forget that you need to launch Galasa SimBank before running the test. The spine of this test resembles that of `SimBankIVT.java`, with a nearly-identical collection of imports and invoked Managers within the main test class - `BasicAccountCreditTest` in this case. diff --git a/src/markdown-pages/docs/running-simbank-tests/provisioned-account-credit-tests.md b/src/markdown-pages/docs/running-simbank-tests/provisioned-account-credit-tests.md index 46063b05..75524f66 100644 --- a/src/markdown-pages/docs/running-simbank-tests/provisioned-account-credit-tests.md +++ b/src/markdown-pages/docs/running-simbank-tests/provisioned-account-credit-tests.md @@ -2,7 +2,7 @@ path: "/docs/running-simbank-tests/provisioned-account-credit-tests" title: "ProvisionedAccountCreditTests" --- -To run this test, follow the same steps as for `SimBankIVT.java` but using the test class name `ProvisionedAccountCreditTests` instead of `SimBankIVT`. Don't forget that you need to launch [Galasa SimBank](/docs/getting-started/simbank) before running the test. +To run this test, follow the same steps as for `SimBankIVT.java` but using the test class name `ProvisionedAccountCreditTests` instead of `SimBankIVT`. Don't forget that you need to launch Galasa SimBank before running the test. This test performs the same function as `BasicAccountCreditTest.java` but has an improved design which includes the use of a provisioned account object, which, once declared as: ```java diff --git a/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md new file mode 100644 index 00000000..6e96608b --- /dev/null +++ b/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md @@ -0,0 +1,314 @@ +--- +path: "/docs/running-simbank-tests/setting-up-galasa-project-eclipse" +title: "Creating a Galasa project using Eclipse" +--- + +Galasa SimBank comes with a selection of prepared Galasa tests: + +- A basic Installation Verification Test (IVT) which logs on to SimBank - `SimBankIVT.java`. +- A test that updates an account using web services and examines the changes with 3270 screens - `BasicAccountCreditTest.java`. +- A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. +- A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. + +All of these example tests become available when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. + +If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](c) section. + +If you are using the Galasa plug-in from the external update site and are using Gradle, follow the instructions in the [_Creating an example Galasa project using Gradle_](#headonlinegradle) section. + +If you are using the Galasa zipped distribution you must use Gradle to build your project, so follow the instructions in the [_Creating an example Galasa project using Gradle (zipped distribution)_](#headgradle) section. + +Note that there are some variations in the Eclipse interface, depending on the version of Eclipse that you are using. + + +## A bit about Maven + +Maven is _opinionated_, which means that you need to comply with its expectations about how a project and its directories should be organised. When you create a Maven project, you should use the generated structure. + +The most visible practical evidence that a project is a Maven project is its pervasive use of `pom.xml` (Project Object Model) files. These XML files contain the magic that allows Maven to manage your project dependencies and build orchestration. + +## A bit about Gradle + +The Gradle project structure looks somewhat different to the Maven structure because Gradle projects use `build.gradle`, `bnd.bnd` and `settings.gradle` files rather than `pom.xml` files. + +The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. + +You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](docs/prerequisites) documentation. + + +## Before you start + +Check that an `.m2` folder exists in your user home directory. Built artifacts are placed in the `~/.m2/repository`. On Windows, the user home directory resembles: C:\Users\, on MacOS it will be /Users/ and on Linux /home/. Note that any file or folder beginning with a `.` (period) is a hidden folder, so you might need to change the settings on your operating system to show hidden files. + +## A little plan + +A full (parent) Galasa project includes several sub-projects, which can also be known as _modules_, some of which are mandatory and some optional. A parent project can contain the following sub-projects: + +- A Managers sub-project, allowing you to extend the provided range of Managers. In practice, if you have no intention of writing a Manager, you can omit this. +- An OBR (OSGi Bundle Repository) sub-project, which is mandatory. Galasa uses the OBR to locate your test project(s) and reason about their interdependencies. +- One or more test sub-projects, that as the name implies, contain the tests themselves. + +The parent project establishes all the dependencies for the sub-projects or modules. It builds all the modules in the order of the dependencies - it builds the Manager module before the test projects that use it. + +For simplicity, it is assumed that you will only have one version of a test in production at any one time. However, by establishing different versions of your tests, you can have test streams with different versions of the same test project. For the purposes of the forthcoming example, the version of all projects is set to `0.1.0-SNAPSHOT`. + + + +## Creating an example Galasa project using Maven + +NOTE: Normally m2e (the Eclipse Maven plug-in) automatically compiles the test bundles and produces the necessary manifest and OSGi files. However, there appears to be an anomaly in m2e in the 2019 versions of Eclipse which we are investigating. If the bundles fail to build correctly, you can force the Maven build by right-clicking the _project_ and selecting _Run As > Maven Install_. We will resolve this issue in a future release. + +1. Ensure that Eclipse is running. +2. Choose _File > New > Example_, select _SimBank example Maven projects_ and click _Next_. +3. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), two new entries appear: + ``` + dev.galasa.simbank.manager + dev.galasa.simbank.tests + ``` +4. Right-click on `dev.galasa.simbank.manager` and choose _Run As > Maven install_ - wait a few moments for the Maven build and then right-click on `dev.galasa.simbank.tests` and do the same. Note that the order in which you do this is significant - first `dev.galasa.simbank.manager` and then `dev.galasa.simbank.tests`. This is because the SimBank tests have a dependency on the SimBank Manager. +5. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. +6. Explore the `dev.galasa.simbanks.tests` package. You'll see the group of tests provided with SimBank: + ![SimBank tests](./provided-tests.png) + +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. + +## Creating an example Galasa project using Gradle + +1. Ensure that Eclipse is running. +2. Depending on your operating system, choose either _Window > Preferences_ or _Eclipse > Preferences_, check that you are using the correct version of Gradle. +3. Choose _File > New > Example_, select _SimBank example Gradle projects_ and click _Next_. +4. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), three new entries appear: + ``` + dev.galasa.simbank.manager + dev.galasa.simbank.parent + dev.galasa.simbank.tests + ``` +5. In Project Explorer, right-click on `dev.galasa.simbank.parent` and select _Gradle > Refresh Gradle Project_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab when the project is refreshed successfully.
+ Note: If you get an error connecting to the Gradle build, go to _Window > Preferences > Gradle_, check the _Local installation directory_ box, browse to the folder in which you installed Gradle and click _OK_ and _Apply and Close_. +6. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. +7. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. +8. Provide a meaningful name and set up your Gradle Task to run a clean build. + ![SimBank tests](./clean-build.png) +9. In _Working Directory_, click *Workspace*, select `dev.galasa.simbank.parent` and click `OK`. +10. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. +11. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. +12. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: + ![SimBank tests](./gradle-tests.png) + +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. + + +## Creating an example Galasa project using Gradle (zipped distribution) + +1. Ensure that Eclipse is running. +2. Depending on your operating system, choose either _Window > Preferences_ or _Eclipse > Preferences_, check that you are using the correct version of Gradle, and then select `Galasa` from the left hand pane. +3. Change the _Remote Maven URI_ to the local Maven directory, for example, `file:///home/username/galasa-isolated-mvp/maven` to enable running tests to access any dependencies.
+ Note: If you are using the Docker image, set the URL to the running container, for example, `http://hostname:8080/maven`. +4. Click _Apply and Close_. +5. Choose _File > New > Example_, select _SimBank example Gradle projects_ and click _Next_. +6. Confirm your _New project_ prefix as `dev.galasa.simbank` and press _Finish_. In your _Package Explorer_ (if it's not visible, choose _Window > Show View > Package Explorer_), three new entries appear: + ``` + dev.galasa.simbank.manager + dev.galasa.simbank.parent + dev.galasa.simbank.tests + ``` +7. Add a `pluginManagement` section, at the top of the `settings.gradle` file in `dev.galasa.simbank.parent` so that the Gradle build can search the Maven directory for any required plug-ins. Specify the Maven repository as the location of the unzipped Maven directory. For example: + ```dev.galasa.simbank.parent - settings.gradle file + pluginManagement { + repositories { + maven { + url = "file:///home/username/galasa-isolated-mvp/maven" + } + } + } + ``` + Note: If you are using the Docker image, set the URL to the running container. For example: + ```dev.galasa.simbank.parent - settings.gradle file + pluginManagement { + repositories { + maven { + url = "http://hostname:8080/maven" + } + } + } + ``` +8. In `dev.galasa.simbank.manager`, modify the `build.gradle` file: + 1. In the repositories closure, replace `mavenCentral()` with the location of the unzipped Maven directory so that the individual projects can locate any dependencies that they might require for building. For example: + ```dev.galasa.simbank.manager - build.gradle file + repositories { + maven { + url = "file:///home/username/galasa-isolated-mvp/maven" + } + } + ``` + Note: If you are using the Docker image, set the URL to the running container. For example: + ```dev.galasa.simbank.manager - build.gradle file + repositories { + maven { + url = "http://hostname:8080/maven" + } + } + ``` + 2. Modify the dependencies closure by adding the following constraints: + ```dev.galasa.simbank.manager - build.gradle file + constraints { + implementation('commons-codec:commons-codec:1.15'){ + because "Force specific version of commons-codec for security reasons" + } + implementation('org.apache.httpcomponents:httpcore:4.4.14'){ + because "Force specific version of httpcore for security reasons" + } + } + ``` +9. In `dev.galasa.simbank.tests`, modify the `build.gradle` file: + 1. In the repositories closure, replace `mavenCentral()` with the location of the unzipped Maven directory. For example: + ```dev.galasa.simbank.tests - build.gradle file + repositories { + maven { + url = "file:///home/username/galasa-isolated-mvp/maven" + } + } + ``` + Note: If you are using the Docker image, set the URL to the running container. For example: + ```dev.galasa.simbank.tests - build.gradle file + repositories { + maven { + url = "http://hostname:8080/maven" + } + } + ``` + 2. Modify the Selenium Manager dependency to remove packages that are not required. Change the dependency from: + ```dev.galasa.simbank.tests - build.gradle file + implementation'dev.galasa:dev.galasa.selenium.manager:0.+' + ``` + to: + ```dev.galasa.simbank.tests - build.gradle file + implementation('dev.galasa:dev.galasa.selenium.manager:0.+'){ + exclude group: 'com.squareup.okio', module: 'okio' + exclude group: 'com.squareup.okhttp3', module: 'okhttp' + exclude group: 'net.bytebuddy', module: 'byte-buddy' + exclude group: 'org.apache.commons', module: 'commons-exec' + exclude group: 'com.google.guava', module: 'guava' + } + ``` + 3. Modify the dependencies closure by adding the following constraints: + ```dev.galasa.simbank.tests - build.gradle file + constraints { + implementation('commons-codec:commons-codec:1.15'){ + because "Force specific version of commons-codec for security reasons" + } + implementation('org.apache.httpcomponents:httpcore:4.4.14'){ + because "Force specific version of httpcore for security reasons" + } + } + ``` +10. Ensure that you save the modifications that you made to the files. +11. In Project Explorer, right-click on `dev.galasa.simbank.parent` and select _Gradle > Refresh Gradle Project_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab when the project is refreshed successfully.
+ Note: If you get an error connecting to the Gradle build, go to _Window > Preferences > Gradle_, check the _Local installation directory_ box, browse to the folder in which you installed Gradle and click _OK_ and _Apply and Close_. +12. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. +13. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. +14. Provide a meaningful name and set up your Gradle Task to run a clean build. +15. In _Working Directory_, click *Workspace*, select `dev.galasa.simbank.parent` and click `OK`. +16. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. +17. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. +18. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: + ![SimBank tests](./gradle-tests.png) + +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. + + +## More about the parent project + +The top level folder, which is called `dev.galasa.example.banking` in this example, is the parent project. The parent project is a convenient container in which to hold all of the generated files. In Maven the `pom.xml` in the parent project is used to build all the other generated files. In Gradle, the `settings.gradle` file is used. + +Within the example parent project structure there are three generated OSGi bundle sub-projects: + +- The payee bundle project, _dev.galasa.example.banking.payee_, which contains two Galasa tests - _TestPayee.java_ and _TestPayeeExtended.java_ - both of which relate to testing the `payee` feature. +- The account test bundle project, _dev.galasa.example.banking.account_, which contains two Galasa tests - _TestAccount.java_ and _TestAccountExtended.java_ - both of which relate to testing the `account` feature. + +- An OSGi Bundle Repository (OBR) which holds metadata listing the tests that are available in the Galasa test projects. + + +## More about the test projects + +Within each of the Galasa test projects - `payee` and `account` - you can see the following files and folders: + +- A pom.xml file (for use by the Maven build tool) + +- A build.gradle file (for use by the Gradle build tool) + +- A bnd.bnd file (for use by the Gradle build tool) + +- A `src` tree holding source code + +- Two java files in each `feature` test project + +- A text resource file in each `feature` test project, which is read and used by the tests at run-time. + + +## About the tests + +The _TestAccount.java_ and the _TestPayee.java_ source files show how a Core Manager can be injected into your test class before any test methods being used. + +The _TestAccountExtended.java_ and the _TestPayeeExtended.java_ source files show: + +- How to obtain the `run-id` identifier by which an instance of running the test can be known. This can be useful for naming artifacts, logging or otherwise. + +- How to read a text file resource which is embedded within the test OSGi bundle. This can be useful for getting data files for use in the testing of the application. + +- How logging can be performed to help debug issues in the test code itself. + +- How a file that is created by the test run can be captured together with other test results for later viewing. + + +## Additional notes on the key elements of pom.xml files + +The following sections provide a little more information about some of the elements that are found within the various pom.xml files. + +### The parent pom.xml file elements + +- The `` and `` elements are standard prologues to a `pom.xml` file. + +The following extract from the generated parent pom.xml shows some of the key elements that are described: + +``` +dev.galasa.example.banking +dev.galasa.example.banking +0.0.1-SNAPSHOT +pom +``` + +- The `` is used to group related Maven projects in a Maven repository. It is recommended (but not enforced) that all projects in a [test stream](../writing-own-tests/test-streams) share the same `groupId`. +- The `` must be unique for each Maven project under a `groupId`. To prevent confusion, you could make it unique across `groupId`s. The `groupId` and `artifactId` can nominally be anything you choose, but if you were to ever consider publishing the project on Maven Central, you would have to ensure that they were unique across Maven Central. Because of this, and to avoid future name collisions, it is conventional to use (reversed) company domain names, which leads to patterns like `dev.galasa.example.banking`. +- The `` in this project is set to `0.1.0-SNAPSHOT`. +- `` indicates what type of Maven project this is - in this case, a `pom` project. + +The following extract from the parent pom.xml shows the module elements that are contained within the generated parent pom.xml: + +``` + + dev.galasa.example.banking.payee + dev.galasa.example.banking.account + dev.galasa.example.banking.obr + +``` + +- `` details what sub-modules (sub-projects) are contained within this parent project. Usually, when the parent project is built, so are the sub-modules. + +Other elements that are contained within the generated parent pom.xml are listed in the following section: + +- `` controls where Maven deploys the project when built. A variable is used so that the same project can be built and deployed to different test stream repositories. +- The `` element specifies properties such as file encoding and Java version numbers. +- `` establishes the versions of dependencies in all of the sub-modules. A BOM project is provided by the Galasa team that includes the versions of all of the released Managers. Set the version of Galasa you wish to run against, for example 0.20.0, and all the Manager versions are imported. +- `` list all the Managers you wish to make available for your tests and custom Manager if present. You could include `` in each of the sub-modules, but it is easier to maintain the list here. +- `` identify the Maven plugins to be used during the build process. The `maven-bundle-plugin` builds OSGi bundles (the Manager and test projects), indicated by `bundle`. The `galasa-maven-plugin` is used in two ways - to build a test catalog for each bundle project and to build the `galasa-obr` project. + +### The test project pom.xml file elements + +- The `` element signifies that all the properties and dependencies found in the parent pom.xml file are to be used for this project - avoiding duplication and allowing changes to ripple through all sub-projects. +- The `` element is set to `bundle` so an OSGi bundle is built instead of a simple JAR. + + +## The test pom.xml file elements + + - The `` element is set to `galasa-obr` which causes the Galasa Maven plugin to build this project. diff --git a/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md b/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md index 577c32ad..ccb607e5 100644 --- a/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md +++ b/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md @@ -3,19 +3,7 @@ path: "/docs/running-simbank-tests/simbank-IVT" title: "Running the SimBank Installation Verification Test" --- -This basic test logs on to Galasa SimBank and examines an account. - -1. Create your initial example projects as described in Running the supplied SimBank tests - a once-only activity. -1. Ensure that Eclipse is running, your example projects are open and that you have launched SimBank as described in Exploring SimBank. -1. Choose _Run > Run Configurations_ and look for and select _Galasa - Java_ in the left pane (not Galasa SimBank). -1. Right-click _Galasa_, choose _New Configuration_ and give it a name. -1. In the dialog, choose _Browse_ to locate your project - `dev.galasa.simbank.tests`, then press _OK_. Then press _Search_ to locate your test class, `SimBankIVT` and press _OK_. -1. Press _Apply_ then _Run_. -1. The `SimBankIVT` test class runs, and the Eclipse console displays their progress through to completion - you will see a console message like:
- `INFO dev.galasa.boot.Launcher.launch - Boot complete` -
- when the tests have finished. You will also see a _live terminal_ window in which the interactions with the 3270 terminal are captured - you can use the attached controls to step back and forth along the sequence of screens. -1. View the results of the test runs in Eclipse. Find out more in the [Viewing test results](/docs/running-simbank-tests/viewing-test-results) documentation. +This basic test logs on to Galasa SimBank and examines an account. Don't forget that you need to launch Galasa SimBank before running the test. ## Exploring the `SimBankIVT` test class diff --git a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md index b6e61c6e..42e0346d 100644 --- a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md +++ b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md @@ -1,8 +1,19 @@ --- path: "/docs/writing-own-tests/setting-up-galasa-project" -title: "Creating a Galasa project" +title: "Creating a Galasa project using the command line" --- +Galasa SimBank comes with a selection of prepared Galasa tests: + +- A basic Installation Verification Test (IVT) which logs on to SimBank - `SimBankIVT.java`. +- A test that updates an account using web services and examines the changes with 3270 screens - `BasicAccountCreditTest.java`. +- A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. +- A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. + +All of these example tests become available when you set up a Galasa example project. + +## Creating a project by using the Galasa CLI + You can quickly and easily create a project structure to accommodate your own independent tests in your local storage by using the [Galasa command line interface](/docs/cli-command-reference/cli-command-reference) (Galasa CLI) that is provided with Galasa. You can pass parameters to the `galasactl project create` command, enabling you to build your project using either Maven or Gradle, and allowing you to choose your own artifact names and naming conventions. @@ -17,29 +28,17 @@ The example provided in this topic creates a project containing both Maven and G ## A bit about Maven -Maven is an Open Source build automation tool, initially created in 2003 and part of the Apache Software Foundation. You do not explicitly need to install it, the Galasa plugin downloads and installs it silently during its own installation and configuration. If you have already installed Maven as part of some other software project, no action is needed. - Maven is _opinionated_, which means that you need to comply with its expectations about how a project and its directories should be organised. When you create a Maven project, you should use the generated structure. The most visible practical evidence that a project is a Maven project is its pervasive use of `pom.xml` (Project Object Model) files. These XML files contain the magic that allows Maven to manage your project dependencies and build orchestration. ## A bit about Gradle -Gradle is an Open Source build automation tool, initially created in 2008. If you want to use Gradle to build Galasa projects, you must install it. If you have already installed Gradle as part of some other software project, no action is needed. - The Gradle project structure looks somewhat different to the Maven structure because Gradle projects use `build.gradle`, `bnd.bnd` and `settings.gradle` files rather than `pom.xml` files. The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -The following table shows the current compatibility between Gradle and Galasa versions: - - -| Gradle release | Compatible Galasa version | -| :---- | :-------- | -| 6.8.x | All | -| 6.9.x | All | -| 7.x.x | All | - +You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](docs/prerequisites) documentation. ## Before you start From 7e0860540341ebc936669837a6ea0b586d932b3a Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 21 Sep 2023 15:51:35 +0100 Subject: [PATCH 2/6] restructure --- src/data/nav.yaml | 10 +- src/markdown-pages/Galasa_automation.md | 2 +- src/markdown-pages/about_Galasa.md | 2 +- src/markdown-pages/doc_root.md | 19 +-- src/markdown-pages/docs/architecture.md | 2 +- .../cli-command-reference.md | 36 +----- .../installing-cli-tool.md | 68 ++++++++++ .../cli-command-reference/runs-local-debug.md | 14 ++- .../runs-submit-local.md | 8 +- .../docs/cli-command-reference/simbank-cli.md | 117 ------------------ .../docs/ecosystem/ecosystem-architecture.md | 10 +- .../docs/ecosystem/ecosystem-installing.md | 18 +-- .../docs/ecosystem/ecosystem.md | 6 +- .../docs/first-steps/getting-started.md | 18 ++- .../first-steps/initialising-home-folder.md | 69 ++++++----- .../docs/first-steps/installing-offline.md | 14 ++- .../docs/first-steps/installing-online.md | 11 +- .../docs/first-steps/prerequisites.md | 87 +++++-------- .../manager-groups/ecosystem-manager-group.md | 2 +- src/markdown-pages/docs/managers.md | 2 +- .../docs/running-simbank-tests.md | 4 +- .../setting-up-galasa-project-eclipse.md | 9 +- .../writing-own-tests/running-test-modes.md | 6 +- .../setting-up-galasa-project.md | 58 ++++----- src/markdown-pages/highlights.md | 2 +- 25 files changed, 262 insertions(+), 332 deletions(-) create mode 100644 src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md delete mode 100644 src/markdown-pages/docs/cli-command-reference/simbank-cli.md diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 3e0468f5..73d75c92 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -30,17 +30,15 @@ items: - title: Galasa Architecture path: /docs/architecture - - title: Downloading and Installing + - title: Installing options path: /docs/ - - title: Prerequisites - path: /docs/prerequisites - title: Getting started using the Galasa CLI path: /docs/cli-command-reference/cli-command-reference - items: + items: + - title: Downloading and installing the Galasa CLI + path: /docs/cli-command-reference/installing-cli-tool - title: Initialising your local environment path: /docs/initialising-home-folder - - title: Exploring Galasa SimBank - path: /docs/cli-command-reference/simbank-cli - title: Creating a project using the CLI path: /docs/writing-own-tests/setting-up-galasa-project - title: Running a test locally diff --git a/src/markdown-pages/Galasa_automation.md b/src/markdown-pages/Galasa_automation.md index e5953c21..da3174f4 100644 --- a/src/markdown-pages/Galasa_automation.md +++ b/src/markdown-pages/Galasa_automation.md @@ -59,5 +59,5 @@ Tests written for Galasa can be run locally on your computer for manual debuggin Environment-agnostic capabilities: - Tests can be run against multiple environments as code progresses through release stages. -- The Galasa test engine allows tests to run locally for easier development and debugging, as well as in the Galasa ecosystem for production testing at scale. +- The Galasa test engine allows tests to run locally for easier development and debugging, as well as in the Galasa Ecosystem for production testing at scale. diff --git a/src/markdown-pages/about_Galasa.md b/src/markdown-pages/about_Galasa.md index e0bcedca..c77e6963 100644 --- a/src/markdown-pages/about_Galasa.md +++ b/src/markdown-pages/about_Galasa.md @@ -31,7 +31,7 @@ Galasa simplifies testing in such an environment. The following diagram shows an This sophisticated solution requires end-to-end integration testing of an application that runs on different platforms (z/OS and Cloud) and uses different technologies (a 3270 emulator, JCL batch job and Selenium Web Driver). -When run inside a [Galasa ecosystem](/docs/ecosystem), a Galasa test can be invoked from an IDE or as part of a CI/CD pipeline. The Galasa framework initializes the test environment, creates valid test data, runs the test and validates the test output. As all test results and artifacts are stored in one location, it's easy to generate reports and diagnose the cause of any failures. +When run inside a [Galasa Ecosystem](/docs/ecosystem), a Galasa test can be invoked from an IDE or as part of a CI/CD pipeline. The Galasa framework initializes the test environment, creates valid test data, runs the test and validates the test output. As all test results and artifacts are stored in one location, it's easy to generate reports and diagnose the cause of any failures. ## Use Galasa to help you to: diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index a28f4f4c..744a846b 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -1,22 +1,23 @@ --- path: "/docs" -title: "Downloading and installing" +title: "Installing options" --- -There are a few options available for downloading and installing Galasa. Prerequisites vary, depending on the options that are chosen. +There are a few options available when installing Galasa. Prerequisites vary, depending on the option that is chosen. +You can install Galasa for using in the command-line, for using Eclipse, or for sharing with your department (using the Galasa zipped distribution). -## Download and Install options +There are benefits of installing Galasa for using in the command-line. Much of the configuration set-up that is required is done for you automatically by scripts, so less manual intervention is needed. You can then import the configuration into an IDE of your choice, rather than having to use Eclipse. -You can download Galasa as a binary of the Galasa CLI tool from the GitHub `cli` repository, or as an Eclipse plug-in, which can be downloaded either directly from an external update site, or as a zip file (zipped distribution). +If you are using only Eclipse for your IDE, do not have restricted internet access and want to use open-source Galasa you might choose to install the Galasa Eclipse plug-in directly from the external update site for using in Eclipse. -The Galasa binary that is stored in the `cli` repository is installed by using the Galasa command line (Galasa CLI). The benefit of using the command-line to install Galasa is that much of the configuration set-up that is required is done for you automatically by scripts, so there is less manual intervention needed. You can then import the configuration into an IDE of your choice. - -If you are using only Eclipse for your IDE, you might choose to download the Galasa Eclipse plug-in directly from the external update site or as a zipped distribution. Users without restricted internet access who want to use open-source Galasa, can install the Galasa Eclipse plug-in directly. The zipped distribution of Galasa allows users who do not have access to Maven Central, Eclipse Marketplace and Docker Hub from their company network to use Galasa. +If you do not have access to Maven Central, Eclipse Marketplace, and Docker Hub from your company network, you can use the Galasa zipped distribution. ## Next steps -Once you have decided on your download and install options, take a look at the [Prerequisites](../markdown-pages/docs/prerequisites) documentation to find out what software you need to install. +If you are installing Galasa for using in the command-line, following the instructions in [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation. + +If you are installing Galasa for using in the Eclipse, or if you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using Eclipse](/docs/getting-started) documentation. -You can then choose to view either the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation or the [Getting started using Eclipse](/docs/getting-started) documentation. +To find out about the architecture of Galasa and some of its key components, take a look at the [Galasa architecture](/docs/architecture) documentation. \ No newline at end of file diff --git a/src/markdown-pages/docs/architecture.md b/src/markdown-pages/docs/architecture.md index 24ef79a9..ed1d88e8 100644 --- a/src/markdown-pages/docs/architecture.md +++ b/src/markdown-pages/docs/architecture.md @@ -3,7 +3,7 @@ path: "/docs/architecture" title: "Architecture" --- -Read on to learn a little about Galasa's architecture and key components. +To get going with Galasa as quickly as possible, explore the [Installing options](/docs) section. Read on to learn a little about Galasa's architecture and key components. # Galasa's architecture At its top level, Galasa decomposes into three major components: diff --git a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md index a9effdf7..e83f64ce 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md @@ -3,35 +3,8 @@ path: "/docs/cli-command-reference/cli-command-reference" title: "Getting started using the Galasa CLI" --- -Use the Galasa command line interface (Galasa CLI) to help you complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. - - -## Getting started - -Complete the following steps to start running the Galasa CLI tool: - -On Mac or Unix: - -1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. -2. Download the appropriate binary of the [Galasa CLI tool](https://github.com/galasa-dev/cli/releases) for your machine architecture from the _cli_ repository in GitHub and re-name it to `galasactl`. -3. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. For example, ```export PATH=${PATH}:/my/folder/containing/galasactl```. -4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. -5. Set permission to open the CLI tool by running the `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command. - -You are now able to run Galasa CLI commands from the command line. - - -On Windows (Powershell) - -1. Download the binary and re-name it to `galasactl`. -2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. -3. Open `cmd.exe` and type `start galasactl.exe` in the directory containing `galasactl`. - -You are now able to run Galasa CLI commands from the command line. - - -*Note:* It is useful to put `galasactl` in your PATH to enable the Galasa CLI tool to be called from any directory. If you are using a Mac, you can find `PATH`, and the directories stored within it, by entering the command `echo $PATH | tr ":" "\n"` in your terminal. If you are using Windows, type the command `C:\> echo %PATH%`. You can then either add the binary into a directory that is already in your PATH, or add a new directory containing the tool to your PATH. +If you are installing Galasa for using in the command-line, you can use the Galasa command line interface tool (Galasa CLI) to interact with Galasa to complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. ## About Galasa CLI commands @@ -48,7 +21,7 @@ Go programs can sometimes struggle to resolve DNS names, especially when a worki ## Getting help -Use the following command to get more information about the command and command options, including default values. +Once you have installed the Galasa CLI, you can use the following command to get more information about the command and command options, including default values. ``` galasactl --help @@ -66,8 +39,7 @@ You can view a list of error messages that can be output by the galasactl tool i +## Next steps - - - +To install Galasa for using in the command line, follow the instructions in [Downloading and installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool). diff --git a/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md new file mode 100644 index 00000000..95ca14af --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md @@ -0,0 +1,68 @@ +--- +path: "/docs/cli-command-reference/installing-cli-tool" +title: "Downloading and installing the Galasa CLI" +--- + +This section provides details about prerequisite software requirements and information about how to download and install the Galasa CLI on your local machine. + +## Prerequisites + +| Software | Description | +| :---- | :-------- | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.8.x and later. | +| 3270 emulator | Optional. 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.| + + +## Downloading the Galasa CLI + +To install Galasa for using in the command-line you first need to download the binary file for the Galasa CLI from the Galasa cli respository in GitHub. + +The following versions of the Galasa CLI are available to download for different operating systems and machine architectures: + +| Operating system | Download | +| :---- | :-------- | +| MacOSX | galasactl-darwin-x86_64 | +| MacOSX | galasactl-darwin-arm64 | +| Linux 64-bit x86 | galasactl-linux-x86_64 | +| Linux arm64 | galasactl-linux-arm64 | +| zLinux | galasactl-linux-s390x | +| Windows | galasactl-windows-x86_64.exe | + +You can find out the architecture of your machine by typing the command `uname -m` into your Mac or Linux terminal. + + +## Installing the Galasa CLI + +Complete the following steps to install Galasa for using the command line: + +On Mac or Unix: + +1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. +2. Download the appropriate binary of the Galasa CLI for your machine architecture from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub and re-name it to `galasactl`. +3. Add Galasa CLI to your PATH to enable you to run CLI commands from anywhere on your file system without having to specify the absolute path. To set the path permanently, you need add the Galasa CLI path to your shell's initialization file. For example, if you downloaded the galasactl executable to a folder called `~/tools` in your home directory, you need to add `~/tools` to the list of directories that your shell searches through when you enter a command. You can do this by adding the line ```export PATH=$PATH:$HOME/tools``` to your shell’s initialization file (for example `~/.bashrc` or `~/.zshrc`). You should now be able to run the Galasa CLI too from any directory in your file system. +4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. +5. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command. + +You are now able to run Galasa CLI commands from the command line. + + +On Windows (Powershell) + +1. Download the binary and re-name it to `galasactl`. +2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. +3. Open `cmd.exe` and type `start galasactl.exe` in the directory containing `galasactl`. + +You are now able to run Galasa CLI commands from the command line. + + +## Next steps + +Read the [Initialising your local environment](/docs/initialising-home-folder) documentation to help you to set up some basic file structures and files in your home folder so that you can start using Galasa. + + + + + + + diff --git a/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md b/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md index 6a97ed2c..46ea4f19 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md @@ -3,15 +3,19 @@ path: "/docs/cli-command-reference/cli-runs-local-debug" title: "Debugging a test locally" --- -You can run a test locally in debug mode by using the galasactl `runs submit local` command with the `--debug` option specified. To run in debug mode, the Galasa test connects with a Java debugger on a specified port and the IDE being used is configured to connect to the same port. The test can then be launched in the Java debugger. +The following section describes how to connect your Galasa test with a Java debugger on a specified port, and then configure your IDE (IDE options covered in this topic are Microsoft VSCode,IntelliJ, and Eclipse) to connect to that same port so that you can run your test locally in debug mode. -The default value of the port is `2970`, but you can override this value adding an optional property, `galasactl.jvm.local.launch.debug.port`, into the `bootstrap.properties` file. For example, `galasactl.jvm.local.launch.debug.port=2971`. This property is ignored if the `--debug` option is not supplied to the `runs submit local` command. +## Using the debug option + +You can run a test locally in debug mode by using the galasactl `galasactl runs submit local` command with the `--debug` option specified. To run in debug mode, the Galasa test connects with a Java debugger on a specified port and the IDE being used is configured to connect to the same port. The test can then be launched in the Java debugger. + +The default value of the port is `2970`, but you can override this value adding an optional property, `galasactl.jvm.local.launch.debug.port`, into the `bootstrap.properties` file. For example, `galasactl.jvm.local.launch.debug.port=2971`. This property is ignored if the `--debug` option is not supplied to the `galasactl runs submit local` command. If you need to override the value of the port that is set in the bootstrap, you can do so by using the `--debugPort` option on the `runs submit local` command. The port value itself must be an unsigned integer. To launch multiple testcases in debug mode, add an explicit `--debugPort` option on the `galasactl runs submit local` command, so that each port is only used by one test/debugger pair at a time. -You can view the full list of options that are available with the `runs submit local` command in the +You can view the full list of options that are available with the `galasactl runs submit local` command in the Galasa cli repository. @@ -23,7 +27,7 @@ In `listen` mode, the JVM that launches the testcase opens a debug port and paus You can override the default value of `listen` by adding the optional property `galasactl.jvm.local.launch.debug.mode` into the `bootstrap.properties` file. For example, `galasactl.jvm.local.launch.debug.mode=attach`. -If you need to override the mode that is set in the bootstrap, you can do so by using the `--debugMode` option on the `runs submit local` command. +If you need to override the mode that is set in the bootstrap, you can do so by using the `--debugMode` option on the `galasactl runs submit local` command. @@ -67,7 +71,7 @@ Complete the following steps to run a local test in debug mode using VSCode: } ``` 3. Check that the port number specified, so that when you configure the IDE the port used by the IDE matches the port number that is used by the testcase. In this example, `port` is set to `2970`, which is the default value.
-4. Check the value of the `request` field. The request field with a value of `attach` can be paired with the default of `listen` that is used by the `runs submit local --debug` command. Each tool must be configured with the opposite value, so one listens to the port, and the other attaches to it. +4. Check the value of the `request` field. The request field with a value of `attach` can be paired with the default of `listen` that is used by the `galasactl runs submit local --debug` command. Each tool must be configured with the opposite value, so one listens to the port, and the other attaches to it. 5. Make a note of the `name` that is specified so that you select this configuration to launch the test in the Java debugger. diff --git a/src/markdown-pages/docs/cli-command-reference/runs-submit-local.md b/src/markdown-pages/docs/cli-command-reference/runs-submit-local.md index ddd3fc5e..34d41c14 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-submit-local.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-submit-local.md @@ -3,7 +3,7 @@ path: "/docs/cli-command-reference/cli-runs-submit-local" title: "Running tests locally using the command line" --- -The `runs submit local` command submits tests to run within the local JVM, rather than dynamically deploying the tests to a remotely deployed Galasa Ecosystem. +The `galasactl runs submit local` command submits tests to run within the local JVM, rather than dynamically deploying the tests to a remotely deployed Galasa Ecosystem. Running tests locally should only be used during test development to verify that the test is behaving as expected. Local runs do not benefit from the features that are provided when running tests within a Galasa Ecosystem. For example, resources are not cleaned-up in the event of a failure and scaling capabilities are limited by workstation resources. @@ -11,7 +11,7 @@ Local runs do not benefit from the features that are provided when running tests ## Working with the `runs submit local` command -To use the `runs submit local` command, the `JAVA_HOME` environment variable must be set to reference the JVM in which you want the test to run. This is because the local java run-time environment is used to launch the test locally. To check that `JAVA_HOME` is set correctly, the tool checks that `$JAVA_HOME/bin/java` exists in Unix or Mac, and `%JAVA_HOME%\bin\java.exe` exists on Windows. +To use the `galasactl runs submit local` command, the `JAVA_HOME` environment variable must be set to reference the JVM in which you want the test to run. This is because the local java run-time environment is used to launch the test locally. To check that `JAVA_HOME` is set correctly, the tool checks that `$JAVA_HOME/bin/java` exists in Unix or Mac, and `%JAVA_HOME%\bin\java.exe` exists on Windows. The level of Java must match the supported level of the Galasa version that is being launched. Use the `galasactl --version` command to find the galasactl tool version. We currently support Java version 11 to version 16 JDK. _Note:_ We do not currently support Java 17 or later. @@ -40,13 +40,13 @@ where: - `--obr` specifies where the CLI tool can find an OBR which refers to the bundle where the tests are stored. When running locally, all tests must exist in the OBR (or OBRs) that are passed to the tool. The `--obr` parameter specifies the Maven co-ordinates of the obr jar file, in the format `mvn:groupId/artifactId/version/classifier`. - `--class` specifies which test class to run. The string is in the format of `/`. All test methods within the class are run. Use multiple flags to test multiple classes. -You can view the full list of options that are available with the `runs submit local` command in the +You can view the full list of options that are available with the `galasactl runs submit local` command in the Galasa cli repository. ## Stopping a running test -Use `Ctrl-C` to stop the `galasactl` tool, ending all test activity. Note that this might leave the system under test with resources that are not cleaned-up. +Use `Ctrl-C` to stop the Galasa CLI, ending all test activity. Note that this might leave the system under test with resources that are not cleaned-up. diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md deleted file mode 100644 index c0e7b27f..00000000 --- a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -path: "/docs/cli-command-reference/simbank-cli" -title: "Exploring Galasa SimBank using the CLI" ---- -Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform, which exists to provide options for future growth. As delivered, SimBank implements a sample banking application against which you can configure and run a set of provided tests in preparation for running your own tests against an *actual* mainframe application. You can also practice writing some new tests to run against the SimBank banking application. - -By exercising the Galasa framework against SimBank, you can pre-empt a lot (but not all) of the work and learning necessary to eventually hook your own tests up with a genuine mainframe environment. If the provided SimBank tests do not work, then it is unlikely that you will be able to run your own tests on a mainframe application. In summary, SimBank helps you to learn Galasa's basic principles of operation before you need to learn how to connect Galasa to your own mainframe application-under-test. - -## Launching SimBank - -This repository contains the Galasa SimBank Eclipse plug-in, SimBank applications and set of sample SimBank tests. - -If you have previously started SimBank, then choose *Run > Run Configurations* from the main menu and select and run the configuration that you created for SimBank. If not, complete the following steps: - -1. Clone the Galasa `simplatform` repository on your machine by running the following command in the directory on your local machine in which you want to clone the repository files: - ``` - git clone https://github.com/galasa-dev/simplatform.git - ``` -2. Run the `./build-locally.sh` script to build the code. -3. Run the `./run-locally.sh --server` script to start the simbank server inside a local JVM. -In a few seconds, the terminal window responds with a series of initialization messages, which on Windows looks like: -``` -2019-10-21 14:24:35 INFO dev.galasa.simplatform.main.Simplatform main Starting Simplatform ... -2019-10-21 14:24:35 INFO dev.galasa.simplatform.db.Database setDerbyHome Setting Derby home to C:\Users\\AppData\Local\Temp\galasaSimplatform1440125512154994774 -2019-10-21 14:24:36 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility Creating SAF service -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Checking if account: 123456789 exists -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Account doesn't exist -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank openAccount Creating account: 123456789 -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Checking if account: 987654321 exists -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank accountExists Account doesn't exist -2019-10-21 14:24:36 INFO dev.galasa.simplatform.application.Bank openAccount Creating account: 987654321 -2019-10-21 14:24:36 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility addUser Added user: IBMUSER -2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main Loading services... -2019-10-21 14:24:36 INFO dev.galasa.simplatform.listener.Listener Loading service: dev.galasa.simplatform.listener.WebServiceListener listening on port: 2080 -2019-10-21 14:24:36 INFO dev.galasa.simplatform.listener.Listener Loading service: dev.galasa.simplatform.listener.TelnetServiceListener listening on port: 2023 -2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main ... services loaded -2019-10-21 14:24:36 INFO dev.galasa.simplatform.main.Simplatform main Starting Derby Network server.... -2019-10-21 14:24:37 INFO dev.galasa.simplatform.main.Simplatform main ... Derby Network server started on port 2027 -2019-10-21 14:24:37 INFO dev.galasa.simplatform.main.Simplatform main ... Simplatform started -``` -If you are a Mac or Linux user, the messages will be almost identical. - -4. The SimBank process has been launched, and is listening on port *2023* for Telnet connections, on port *2080* for web services connections and on port *2027* for Derby SQL connections. Neither web services or Derby connections are explored further in this section. - -## Manually exploring the SimBank application -When you launch SimBank, its banking application listens on port 2023 for incoming client Telnet connections, offering an opportunity to first connect to it manually to review and understand the (simulated) transactions it supports, before subjecting it to Galasa's provided tests. - -### Logging in to the simulated application -1. With the *Galasa SimBank* component still running, configure your 3270 terminal emulator to access port *2023* of *localhost* (or IP address 127.0.0.1 if the *localhost* alias has not been set up) via the Telnet protocol. No SSL configuration is required. -1. Connect to the listening Telnet service with your 3270 emulator and review the logon screen: - - ![SimBank logon screen](simbank-logon.png) - -1. Ensure that the cursor is in the `Userid` field - if it is not, use the TAB key to position it: - - ![TAB to the userid field](simbank-userid.png) - -1. Enter the userid `IBMUSER` - - ![Enter your userid](./simbank-ibmuser.png) - -1. Press TAB to move the cursor into the `Password` field, type the password `SYS1` and press your terminal emulator's ENTER key to logon and transfer to the SimBank main menu: - - ![Banktest home screen](./simbank-banktest.png) - -> *Note:* Depending on your terminal emulator, its ENTER key may not be mapped to the physical ENTER key on your computer. For example, -> on PCOMM, by default, the ENTER key is mapped to the host machine's right CTRL key. If you are unsure about this, review -> your terminal emulator's documentation. - -6. Press PF1: - - ![CICS home screen](../first-steps/simbank-cics.png) - -1. Press your terminal emulator's CLEAR SCREEN key. -1. Enter the transaction name `BANK` and press your terminal emulator's ENTER key once more to get to the SimBank main menu: - - ![Main banking menu](../first-steps/simbank-mainmenu.png) - -As you have been progressing through this process, selected events are logged: - -``` -2019-08-16 09:26:39 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: SessionManagerLogon -2019-08-16 10:26:08 INFO dev.galasa.simplatform.saf.SecurityAuthorizationFacility authenticate User: IBMUSER authenticated -2019-08-16 10:26:08 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: SessionManagerMenu -2019-08-16 10:30:10 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: CICSGoodMorning -2019-08-16 10:36:19 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: CICSClearScreen -2019-08-16 10:38:54 INFO dev.galasa.simplatform.t3270.screens.AbstractScreen buildScreen Building Screen: BankMainMenu -``` -This is an example of log output that can be useful when running tests. -### Browsing account information -1. From the SimBank main menu, press PF1, taking you to the account menu screen. -1. Press TAB until the cursor is in the `Account Number` field, enter `123456789` and press ENTER. - The account details are populated and it is apparent that account number 123456789 is 56.72 in credit. - - ![Account balance](../first-steps/simbank-balance.png) - -1. Press PF3 to return to the account menu screen. - -### Transferring funds between accounts -1. From the SimBank main menu, press PF4, taking you to the SimBank transfer menu. -1. Press TAB until the cursor is in the `Transfer from Account Number` field and enter `123456789`. -1. Press TAB until the cursor is in the `Transfer to Account Number` field and enter `987654321`. -1. Press TAB until the cursor is in the `Transfer Amount` field and enter `1` - - ![Inter-account transfer](../first-steps/simbank-transfer.png) - -1. Press ENTER - a `Transfer Successful` message appears. A log message is also written to the terminal window: - -``` -2019-08-16 13:50:53 INFO dev.galasa.simplatform.application.Bank transferMoney Transfering 1.0 from account: 123456789 to account: 987654321 -``` - -Press PF3 and once again browse the 123456789 account as described previously to verify that its total credit has decreased by the transferred 1.00, and that the 987654321 account has increased by the same amount. - -Note that SimBank also offers a web services interface on port 2080, and although it is not exercised in this topic, it *is* used by two of the provided tests - `BasicAccountCreditTest.java` and `ProvisionedAccountCreditTests.java`. - -Having explored SimBank manually, it's a good time to run some or all of a small collection of automated tests that are provided with SimBank itself - to start, choose _Running the supplied SimBank tests_ in the side-menu. \ No newline at end of file diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index e7f841d9..6e4cbb13 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -3,16 +3,16 @@ path: "/docs/ecosystem/architecture" title: "Ecosystem Architecture" --- -The following diagram provides a high-level representation of the Galasa ecosystem architecture:

![Galasa ecosystem architecture:](ecosystem-overview.svg) +The following diagram provides a high-level representation of the Galasa Ecosystem architecture:

![Galasa ecosystem architecture:](ecosystem-overview.svg)
The ecosystem is made up of a collection of microservices for orchestrating runtimes, monitoring tests and resources, and providing clean-up of those resources if required. The ecosystem provides a centralized store for run configurations, a single location for storing all test results and test artifacts, and utilizes a REST endpoint that can be called from any IDE or pipeline. ### Key components: -The following diagram highlights a some of the key components that make up the Galasa ecosystem and examples of external resources with which Galasa can interact: ![Galasa ecosystem:](galasa-ecosystem-architecture.svg) +The following diagram highlights a some of the key components that make up the Galasa Ecosystem and examples of external resources with which Galasa can interact: ![Galasa ecosystem:](galasa-ecosystem-architecture.svg) -
Expand the following sections to find out more about the key components of the Galasa ecosystem: +
Expand the following sections to find out more about the key components of the Galasa Ecosystem:

Galasa Stores @@ -38,8 +38,8 @@ The following diagram highlights a some of the key components that make up the G | **Engine controller** | The engine controller enables tests to run at scale within the ecosystem. This service is responsible for instantiating individual test engines by creating Docker containers or Kubernetes pods to manage and execute individual Galasa automation test runs. The engine controller allocates a test engine to a test submission if the required resources for the test are available. Otherwise, the test is put into a waiting state to be run at an appropriate time. | | **Resource Management** | The resource management service monitors running tests and resources that have been marked as in use. If a test case becomes stale or is ended manually, this service performs clean up actions to ensure that the resources are entered back into the pool for another test to use. This service can perform large pieces of work, including the de-provisioning of an environment. | | **Metrics Server** | The metrics server indicates the health of the ecosystem, for example, providing metrics on the number of successful test runs. | -| **API Server** | The API server acts as a central point from which to control the Galasa ecosystem and is used by Galasa as an endpoint with which IDEs and pipelines interact for submitting tests and retrieving results. The API server hosts the bootstrap server. | -| **Bootstrap Server** | The bootstrap server is part of the API server. The bootstrap is an endpoint that is provided by the API server to store the initial configuration required to instantiate a Galasa framework. When setting up the Galasa ecosystem, the Eclipse IDE must be updated to point to the bootstrap that is configured to use the ecosystem. | +| **API Server** | The API server acts as a central point from which to control the Galasa Ecosystem and is used by Galasa as an endpoint with which IDEs and pipelines interact for submitting tests and retrieving results. The API server hosts the bootstrap server. | +| **Bootstrap Server** | The bootstrap server is part of the API server. The bootstrap is an endpoint that is provided by the API server to store the initial configuration required to instantiate a Galasa framework. When setting up the Galasa Ecosystem, the Eclipse IDE must be updated to point to the bootstrap that is configured to use the ecosystem. | | **Web UI** | The WebUI is currently under construction and planned for a future release. Use the WebUI to see a dashboard overview of the current and historical health of the Galasa framework. The UI can also run, schedule or reschedule tests, be used to analyse output from failed test runs, and manage the configuration needed to customise the framework and tests for maximum throughput, resilience and flexibility. | | **LDAP authentication server (Optional)** | This server is planned for a future release to provide the ability to authenticate through an LDAP server. | diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md index 73681dcb..68c0e1d7 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md @@ -4,11 +4,11 @@ title: "Installing the Galasa Ecosystem on Docker" --- -The following section explains how to install a Galasa ecosystem on a Docker engine by using the Docker operator. Currently the Docker operator only supports the amd64 platform. A s390x (zLinux) implementation is planned for a future release. +The following section explains how to install a Galasa Ecosystem on a Docker engine by using the Docker operator. Currently the Docker operator only supports the amd64 platform. A s390x (zLinux) implementation is planned for a future release. ## Prerequisites -To bring up the Galasa ecosystem by using the Docker operator, you need access to a Linux virtual machine (VM) with Docker engine installed on it. +To bring up the Galasa Ecosystem by using the Docker operator, you need access to a Linux virtual machine (VM) with Docker engine installed on it. The VM requires 4 VCPUs, 80GB of storage and a recommended minimum of 8GB of memory. The size of the VM provided is directly related to the number of tests that can be run in parallel. It is possible to bring up the ecosystem with 4GB of memory, but this will support a maximum of two tests running in parallel. Docker has a default value of 4GB of memory set, so you need to change this value which you can do by using Docker Desktop. @@ -21,7 +21,7 @@ The Docker operator automatically brings up the following servers on the VM. For *Note:* If the VM has a firewall running, you might need to open the ports that are listed in the following tables. -The following servers are required for the Galasa ecosystem: +The following servers are required for the Galasa Ecosystem: | Name | Description | Port @@ -41,7 +41,7 @@ The following server is not required by the ecosystem but is automatically deplo To use SimPlatform, you need to have access to Maven Central. Chat to us on our Galasa Slack workspace if you need help with this. -## Installing the Galasa ecosystem on the Docker engine +## Installing the Galasa Ecosystem on the Docker engine The ecosystem needs to know the hostname or IP address of the VM on which the Docker engine is running. Due to the way Docker works, you cannot use ```localhost``` or ```127.0.0.1``` - you must use the actual VM hostname or IP address. This information is provided in a *config.yaml* file. @@ -62,7 +62,7 @@ Note the two-spaced indentation on some of the lines - they are important in YA If you opened any ports, check that the port numbers are correct in the *config.yaml* file. -2. Deploy the Galasa ecosystem by running the following Docker command on the VM: +2. Deploy the Galasa Ecosystem by running the following Docker command on the VM: ``` docker run -it -v \ @@ -73,15 +73,15 @@ icr.io/galasadev/galasa-docker-operator-amd64:latest where ```{path}``` is the full pathname to the directory containing your *config.yaml* file. -This command brings up the [microservices](/docs/ecosystem/architecture) that are required to run a Galasa ecosystem. When the command completes, nine docker containers should be running. The command might take a little time to complete. +This command brings up the [microservices](/docs/ecosystem/architecture) that are required to run a Galasa Ecosystem. When the command completes, nine docker containers should be running. The command might take a little time to complete. 3. View the active containers by running the ```docker ps``` command. -The Galasa ecosystem is now successfully installed on the VM. +The Galasa Ecosystem is now successfully installed on the VM. -### Connecting to the Galasa ecosystem +### Connecting to the Galasa Ecosystem -The bootstrap contains the information that Galasa needs to bring up a framework in the Eclipse environment to connect to the ecosystem. From your IDE, edit the bootstrap to reconfigure Galasa to point to the Galasa ecosystem that you created. +The bootstrap contains the information that Galasa needs to bring up a framework in the Eclipse environment to connect to the ecosystem. From your IDE, edit the bootstrap to reconfigure Galasa to point to the Galasa Ecosystem that you created. In Eclipse, you can edit the bootstrap by completing the following steps: diff --git a/src/markdown-pages/docs/ecosystem/ecosystem.md b/src/markdown-pages/docs/ecosystem/ecosystem.md index 3ef9f7e2..1b814023 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem.md @@ -3,7 +3,7 @@ path: "/docs/ecosystem" title: "The Galasa Ecosystem" --- -To realise the full power of Galasa, you need to run your tests inside a Galasa ecosystem. The ecosystem enables you to run automated testing away from your workstation, outside of a local JVM. +To realise the full power of Galasa, you need to run your tests inside a Galasa Ecosystem. The ecosystem enables you to run automated testing away from your workstation, outside of a local JVM. The SimBank tests showcase how the Galasa framework can run inside a locally hosted JVM. Local runs use their own Galasa property files to act as configurational services, making it easy to instantiate and run tests. @@ -17,7 +17,7 @@ However, there are limitations to taking a local-only approach: ## Running tests in the Galasa Ecosystem -The Galasa ecosystem is a cloud native application which exposes a sequence of microservices that are used to manage the set of running tests. Running tests inside the ecosystem provides a number of benefits: +The Galasa Ecosystem is a cloud native application which exposes a sequence of microservices that are used to manage the set of running tests. Running tests inside the ecosystem provides a number of benefits: - Sharing tests across an enterprise
When tests run inside the ecosystem, the Galasa framework provides the ability to scale horizontally to run large numbers of tests in parallel - enabling more testing to complete in a shorter timeframe. The ability to run tests at scale is one of the key features that differentiates Galasa from other test frameworks. Data is locked whilst in use, preventing cross contamination with other running tests. @@ -26,7 +26,7 @@ When tests run inside the ecosystem, the Galasa framework provides the ability t With Galasa, one person can complete the configurations for use across all test runs. Galasa configurations are maintained in a single location - the Configuration Property Store (CPS) and so can be shared across an organization for use by other tests. Setting these properties centrally establishes a single source of truth and means that testers do not need to know about or configure these properties each time they write a new test. Test run results, run logs and artifacts are also stored in one central location, again enabling sharing across teams. - Testing as a service
- With an established Galasa ecosystem you can run your testing as a service; regression tests, application tests, system verification tests and time-consuming adhoc tests can be run on demand by using Galasa as part of your DevOps pipeline and in a cloud environment. Workload is directed away from the CI pipeline and is run in its own dedicated environment, preventing computational resources from being diverted away from other jobs that are running within the pipeline. + With an established Galasa Ecosystem you can run your testing as a service; regression tests, application tests, system verification tests and time-consuming adhoc tests can be run on demand by using Galasa as part of your DevOps pipeline and in a cloud environment. Workload is directed away from the CI pipeline and is run in its own dedicated environment, preventing computational resources from being diverted away from other jobs that are running within the pipeline. - Automated test runs
The Galasa test catalog can be used as part of the ecosystem to run automated testing away from a workstation without the need for local test material. The catalog can be configured to store related tests within a shared test catalog, enabling tests to be automatically selected to run for any given change set. The test catalog uses the latest version of test cases, so you know the tests that you're running are up-to-date. diff --git a/src/markdown-pages/docs/first-steps/getting-started.md b/src/markdown-pages/docs/first-steps/getting-started.md index 7009feb9..d3072d00 100644 --- a/src/markdown-pages/docs/first-steps/getting-started.md +++ b/src/markdown-pages/docs/first-steps/getting-started.md @@ -6,9 +6,25 @@ title: "Getting started using Eclipse" Before development of the Galasa command line tool (galasactl), Eclipse was the main focus for getting started with using Galasa and exploring Simbank and it continues to provide an alternative UI experience to the equivalent command line option. +If you are planning to install and use Galasa with Eclipse, you need to have an Eclipse installation on your machine. 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. + +The following table shows the current compatibility between Eclipse and Galasa versions: + + +| Eclipse level | Compatible Galasa version | +| :---- | :-------- | +| 2023-03 | 0.27.0 and later | +| 2022-09 | 0.27.0 and later | +| 2022-06 | 0.26.0, 0.25.0 | + +Note: We currently support Java version 11 to version 16 JDK. We do not currently support Java 17 or later. If your Eclipse version comes with Java 17 or later, ensure that the JRE environment refers to a Java 11 runtime in your Eclipse launch configuration. + +You can tell Eclipse about an installed runtime by going to _Settings_>_Java_>_Installed JREs_ from the Eclipse menu, and adding the Java 11 runtime to the list of installed JREs. You can set this runtime as default so that Eclipse launches tests with a Java 11 runtime. + + ## Downloading and Installing -You can download Galasa either from a downloadable zip file (zipped distribution) or directly from an external update site. For more information about these options, see the [Introduction](/docs/doc_root) documentation. +You can download Galasa either from a downloadable zip file (zipped distribution) or directly from an external update site. For more information about these options, see the [Installing options](../../docs) documentation. To install the Galasa plug-in from the external update site, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). diff --git a/src/markdown-pages/docs/first-steps/initialising-home-folder.md b/src/markdown-pages/docs/first-steps/initialising-home-folder.md index f55207e8..abec7fd7 100644 --- a/src/markdown-pages/docs/first-steps/initialising-home-folder.md +++ b/src/markdown-pages/docs/first-steps/initialising-home-folder.md @@ -1,33 +1,41 @@ --- path: "/docs/initialising-home-folder" -title: "Initialising your local environment by using the CLI" +title: "Initialising your local environment" --- To start using Galasa tools, or running Galasa tests, you need to set up some basic file structures and files in your home folder. These files include a default bootstrap file, and some local properties files. For more information about these files and what they are used for, see the [About the properties files](#about) section. The following section shows you how to initialise your Galasa home folder by using the Galasa command line interface (Galasa CLI) tool that is provided with Galasa. Once your home folder is initialised, you can start running Galasa tests on your local JVM. -You can view the full list of options (flags) that are available with the `local init` command in the [Galasa cli repository](https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_local_init.md). +You can view the full list of options (flags) that are available with the `galasactl local init` command in the [Galasa cli repository](https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_local_init.md). -## Setting the Galasa bootstrap -Most Galasa CLI commands need a reference to the Galasa bootstrap file or URL. You can set the bootstrap either by using the `--bootstrap` option on the CLI command or by setting the `GALASA_BOOTSTRAP` environment variable. If both are provided, the `--bootstrap` option takes precedence. +## Setting the Galasa home folder -You can set environment variables on a terminal by using the `export` (if you are on Mac or Linux) or `set` (if you are on Windows) command. For example, to set `GALASA_BOOTSTRAP` to `http://my-bootstrap-url`, use the following command: +Galasa comes with a home folder, that is set to `~/.galasa` by default. The home folder is a writable folder that is used by default to store test results and artifacts which are created when tests are run using local JVMs. + +This value can be overridden using the `GALASA_HOME` environment variable. Setting this variable means that you can control where files are created, where Galasa retrieves settings from, and where local test run results and artifacts are stored. This is useful if you need isolation between multiple Galasa local test environments, if you want to share your configuration and test run results with others, or if your `~/.galasa` folder is low on disk space. + +For example, to set the `GALASA_HOME` environment variable to a folder called _mygalasatests_ in a directory called _temp_, use the following command: On Mac or Unix: ``` -export GALASA_BOOTSTRAP=http://my-bootstrap-url +export GALASA_HOME=/temp/mygalasatests ``` On Windows: ``` -set GALASA_BOOTSTRAP=http://my-bootstrap-url +set GALASA_HOME=C:\temp\mygalasatests ``` +You can override the value of the `GALASA_HOME` environment variable on a call-by-call basis by using the `--galasahome` command-line option. + +If you change the `GALASA_HOME` variable to a non-existent or non-initialised folder path, you can create the folder and re-initialise the folder path by running the `galasactl local init` command. + + ## Initialising the Galasa home folder To initialise your Galasa home folder in your home directory along with the properties files, use the following command: @@ -52,42 +60,40 @@ ${HOME}/.galasa You can validate the set up by locating your user home directory and confirming that it contains a `.galasa` folder. On Windows, the user home directory resembles: ```C:\Users\```, on MacOS it will be ```/Users/``` and on Linux ```/home/```. Note that any file or folder beginning with a `.` is a hidden folder, so you might need to change the settings on your file browser user interface to show hidden files. -## Overriding the Galasa home folder +## About the properties files -The `${HOME}/.galasa` folder is a writable folder and is used by default to store test results and artifacts which are created when tests are run using local JVMs. +The following table explains a bit more about the purpose of the properties files that are created: -This value can be overridden using the `GALASA_HOME` environment variable. Setting this variable means that you can control where files are created, where Galasa retrieves settings from, and where local test run results and artifacts are stored. This is useful if you need isolation between multiple Galasa local test environments, if you want to share your configuration and test run results with others, or if your `${HOME}/.galasa` folder is low on disk space. +| Name | Description | +| :---- | :-------- | +| bootstrap.properties | The bootstrap contains the information that Galasa needs to bring up a framework in the environment to connect to the Galasa Ecosystem. If you are running a test on your local machine, the bootstrap file is blank as it does not need to refer to the ecosystem. | +| cps.properties | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. You can extract a test property value from the CPS file for use in a test by using the `@TestProperty` annotation that is provided by the Core Manager.| +| credentials.properties | It is likely that a test will need to pass credentials to the application being tested. For example, as HTTP credentials or as username and password values entered onto a 3270 screen. Rather than hard code the credentials inside a test class, you can store the values in the credentials.properties file when the test is run locally. The ability to get credentials from a credentials store means that you do not need to hard code these values inside a test, enabling the test to be run in different environments without changing a single line of code. You can extract credentials to use in your test by using the `getCredentials` method that is provided by the Core Manager. | +| dss.properties | The dynamic status store (DSS) provides status information about the ecosystem and the tests that are running. The DSS is used by the resource manager and engine controller to ensure the limits that are set in the CPS configuration are not exceeded. DSS property values change dynamically as tests are run, showing the resources that are currently being used, shared or locked by a test, so that workloads can be limited to avoid throttling. When running tests locally (inside Eclipse or using the CLI), all tests use the local file as the DSS. | +| overrides.properties | Specifying overrides is useful if you want to run a set of tests against a particular configuration without changing the test code. For example, you might have multiple versions of software that you need to test. How can you do that without changing the test code? The answer is to use override properties. If you are running tests locally, you can set overrides properties by editing your Overrides Properties file. | -For example, to set the `GALASA_HOME` environment variable to a folder called _mygalasatests_ in a directory called _temp_, use the following command: + + +## Setting the Galasa bootstrap + +The bootstrap is a simple properties file that contains the information that Galasa needs to bring up a framework to connect to an ecosystem. If you are running a test remotely in a Galasa Ecosystem, or if you are running a test locally but using a shared configuration that is hosted by the Galasa Ecosystem, the Galasa bootstrap is set to the URL of the Galasa Ecosystem in which you want to run your test or in which the shared configuration is stored. The bootstrap is blank only when a test is run locally, without using shared configuration. For more information about the modes in which you can run a Galasa test, see the [Running a Galasa test](/docs/writing-own-tests/running-test-modes) documentation. + +If you are planning to only run tests locally, with everything running on the local machine, you do not need to set the Galasa bootstrap. Otherwise, you can set the bootstrap either by using the `--bootstrap` option on the CLI command or by setting the `GALASA_BOOTSTRAP` environment variable. If both are provided, the `--bootstrap` option takes precedence. + +You can set environment variables on a terminal by using the `export` (if you are on Mac or Linux) or `set` (if you are on Windows) command. For example, to set `GALASA_BOOTSTRAP` to `http://my-bootstrap-url`, use the following command: On Mac or Unix: ``` -export GALASA_HOME=/temp/mygalasatests +export GALASA_BOOTSTRAP=http://my-bootstrap-url ``` On Windows: ``` -set GALASA_HOME=C:\temp\mygalasatests +set GALASA_BOOTSTRAP=http://my-bootstrap-url ``` -You can override the value of the `GALASA_HOME` environment variable on a call-by-call basis by using the `--galasahome` command-line option. - -If you change the `GALASA_HOME` variable to a non-existent or non-initialised folder path, you can create the folder and re-initialise the folder path by running the `galasactl local init` command. - - -## About the properties files - -The following table explains a bit more about the purpose of the properties files that are created: - -| Name | Description | -| :---- | :-------- | -| bootstrap.properties | The bootstrap contains the information that Galasa needs to bring up a framework in the environment to connect to the Galasa Ecosystem. If you are running a test on your local machine, the bootstrap file is blank as it does not need to refer to the ecosystem. | -| cps.properties | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. You can extract a test property value from the CPS file for use in a test by using the `@TestProperty` annotation that is provided by the Core Manager.| -| credentials.properties | It is likely that a test will need to pass credentials to the application being tested. For example, as HTTP credentials or as username and password values entered onto a 3270 screen. Rather than hard code the credentials inside a test class, you can store the values in the credentials.properties file when the test is run locally. The ability to get credentials from a credentials store means that you do not need to hard code these values inside a test, enabling the test to be run in different environments without changing a single line of code. You can extract credentials to use in your test by using the `getCredentials` method that is provided by the Core Manager. | -| dss.properties | The dynamic status store (DSS) provides status information about the ecosystem and the tests that are running. The DSS is used by the resource manager and engine controller to ensure the limits that are set in the CPS configuration are not exceeded. DSS property values change dynamically as tests are run, showing the resources that are currently being used, shared or locked by a test, so that workloads can be limited to avoid throttling. When running tests locally (inside Eclipse or using the CLI), all tests use the local file as the DSS. | -| overrides.properties | Specifying overrides is useful if you want to run a set of tests against a particular configuration without changing the test code. For example, you might have multiple versions of software that you need to test. How can you do that without changing the test code? The answer is to use override properties. If you are running tests locally, you can set overrides properties by editing your Overrides Properties file. | ## Initialising the settings.xml file @@ -96,4 +102,9 @@ The `settings.xml` file enables you to set configurations for Maven to use durin If you have Maven installed, and have run a Maven command, an `/.m2` folder, containing a folder called `repositories`, should exist in your home directory. Running the `galasa local init` command then automatically creates a `settings.xml` file in this `/.m2` folder, and populates the file with basic configuration settings. +## Next steps + +You can now start [creating a project using the CLI](/docs/writing-own-tests/setting-up-galasa-project) to accommodate your own independent tests in your local storage. + + diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 05d79d56..6dff42d6 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -24,9 +24,19 @@ This section describes using Eclipse to install the Galasa plug-in - together wi ## Prerequisites -Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed. For a full list of prerequisites, see the [Prerequisites](prerequisites) documentation. +Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed. -## Getting started +| Software | Description | +| :---- | :-------- | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Gradle | Required to install the zipped distribution. You can also build Galasa projects using Gradle (or you can use Maven to build projects if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.8.x and later.| +| Eclipse | Required. Provides the ability to interact with and use Galasa. See [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | +| 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. | +| Maven | Optional (as Gradle is required). You can use Maven rather than Gradle to build Galasa projects. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | +| 3270 emulator | Optional. 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.| + + +## Unpacking the zip file Extract the contents of the zip file into a directory of your choice. diff --git a/src/markdown-pages/docs/first-steps/installing-online.md b/src/markdown-pages/docs/first-steps/installing-online.md index 73fb5b78..bd28a583 100644 --- a/src/markdown-pages/docs/first-steps/installing-online.md +++ b/src/markdown-pages/docs/first-steps/installing-online.md @@ -3,7 +3,7 @@ path: "/docs/getting-started/installing-online" title: "Installing the Galasa plug-in" --- -If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. +If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Getting started using Eclipse](/docs/getting-started) documentation. 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). @@ -13,7 +13,14 @@ This section describes using Eclipse to install the Galasa plug-in - together wi ## Prerequisites -Depending on how you plan to use Galasa, there are several software prerequisites, some or all of which you may have already installed. For a full list of prerequisites, see the [Prerequisites](prerequisites) documentation. +Depending on how you plan to use Galasa, there are several software prerequisites, some or all of which you may have already installed. + +| Software | Description | +| :---- | :-------- | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Eclipse | Required. Provides the ability to interact with and use Galasa. See the [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | +| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. If you are using Eclipse, you do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. All Galasa versions are compatible with Gradle releases 6.8.x and later.| +| 3270 emulator | Optional. 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 diff --git a/src/markdown-pages/docs/first-steps/prerequisites.md b/src/markdown-pages/docs/first-steps/prerequisites.md index b6afea29..57aea02d 100644 --- a/src/markdown-pages/docs/first-steps/prerequisites.md +++ b/src/markdown-pages/docs/first-steps/prerequisites.md @@ -3,59 +3,56 @@ path: "/docs/prerequisites" title: "Galasa Prerequisites" --- -This section takes you through the software prerequisites required before installing Galasa. The prerequisites vary, depending on the version of Galasa that you download and the option you use to install it. +This section takes you through the software prerequisites required before installing Galasa. The prerequisites vary, depending on the whether you are installing Galasa for using in the command-line, or for using in Eclipse. If you are installing Galasa for using in Eclipse, the prerequisites also vary depending on whether you are downloading Galasa directly from the external update site, or are using the zipped distribution. -For information about the download and install options available, see the [Introduction](../../about_Galasa.md) documentation. +For information about installing options, see the [Installing options](../../about_Galasa.md) documentation. -### Java JDK +
-Required. 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. +### Installing Galasa for using in the command-line -### Maven - -Maven is required if you want to use Maven rather than Gradle to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. +| Software | Description | +| :---- | :-------- | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Maven or [Gradle](#gradle) | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. | +| Galasa CLI tool | Required. The tool enables interactions with Galasa via the command line. See [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference) for more information about installing the tool. | +| 3270 emulator | Optional. 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.| -Maven is an Open Source build automation tool, initially created in 2003 and part of the Apache Software Foundation. If you are using Eclipse, you do not explicitly need to install it because the Galasa plugin downloads and installs it silently during its own installation and configuration. If you have already installed Maven as part of some other software project, no action is needed. -### Galasa command line tool (Galasa CLI) +Once you have installed the relevant software, you are ready to install Galasa. To install Galasa for using the command line, follow the instructions in [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference). -Required if you want to use the Galasa CLI to interact with Galasa. You can [download the CLI tool](https://github.com/galasa-dev/cli/releases) from the _cli_ repository in GitHub. +
-The following versions of the Galasa CLI tool are available to download for different operating systems and machine architectures: +### Installing Galasa for using in Eclipse -| Operating system | Download | +| Software | Description | | :---- | :-------- | -| MacOSX | galasactl-darwin-x86_64 | -| MacOSX | galasactl-darwin-arm64 | -| Linux 64-bit x86 | galasactl-linux-x86_64 | -| Linux arm64 | galasactl-linux-arm64 | -| zLinux | galasactl-linux-s390x | -| Windows | galasactl-windows-x86_64.exe | - -*Note:* You can find out the architecture of your machine by typing the command `uname -m` into your Mac or Linux terminal. - -### Eclipse +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Eclipse | Required. Provides the ability to interact with and use Galasa. See the [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | +| Maven or [Gradle](#gradle) | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration.| +| 3270 emulator | Optional. 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.| -If you are planning to install and use Galasa with Eclipse, you need to have an Eclipse installation on your machine. 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. +Once you have installed the relevant software, you are ready to install Galasa. To install the Galasa for using in Eclipse, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). -The following table shows the current compatibility between Eclipse and Galasa versions: +
+### Installing Galasa for using in Eclipse (zipped distribution) -| Eclipse level | Compatible Galasa version | +| Software | Description | | :---- | :-------- | -| 2023-03 | 0.27.0 and later | -| 2022-09 | 0.27.0 and later | -| 2022-06 | 0.26.0, 0.25.0 | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| [Gradle](#gradle) | Required to install the zipped distribution. You can also build Galasa projects using Gradle (or you can use Maven to build projects if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. | +| Eclipse | Required. Provides the ability to interact with and use Galasa. See [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | +| 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. | +| Maven | Optional (as Gradle is required). You can use Maven rather than Gradle to build Galasa projects. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | +| 3270 emulator | Optional. 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.| -Note: We currently support Java version 11 to version 16 JDK. We do not currently support Java 17 or later. If your Eclipse version comes with Java 17 or later, ensure that the JRE environment refers to a Java 11 runtime in your Eclipse launch configuration. +Once you have installed the relevant software, you are ready to install Galasa. To install the zipped distribution of Galasa, follow the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). -You can tell Eclipse about an installed runtime by going to _Settings_>_Java_>_Installed JREs_ from the Eclipse menu, and adding the Java 11 runtime to the list of installed JREs. You can set this runtime as default so that Eclipse launches tests with a Java 11 runtime. -### Gradle +### Gradle -Gradle is required if you are installing the zipped distribution of Galasa, or if you want to use Gradle rather than Maven to build Galasa projects (hierarchical file structures that provide the ability to store and run Galasa tests). - -Gradle is an Open Source build automation tool, initially created in 2008. If you have already installed Gradle as part of some other software project, no action is needed. +Gradle is required if you are installing the zipped distribution of Galasa, or if you want to use Gradle rather than Maven to build Galasa projects (hierarchical file structures that provide the ability to store and run Galasa tests). The following table shows the current compatibility between Gradle and Galasa versions: @@ -67,28 +64,8 @@ The following table shows the current compatibility between Gradle and Galasa ve | 7.x.x | All | -### 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. - -### A 3270 terminal emulator (Optional) - -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. - - -Once you have installed the relevant software, you are ready to install Galasa. - - -## Installing - -To install the Galasa plug-in using the command line, follow the instructions in [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference). - -To install the Galasa plug-in from the external update site, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). - -To install the Galasa plug-in using the zipped distribution, follow the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). - ## Next steps -You can then start exploring Galasa Simbank; a component distributed with Galasa that you can start playing with to help you to learn about the Galasa basics. +Start exploring Galasa Simbank; a component distributed with Galasa that you can start playing with to help you to learn about the Galasa basics. diff --git a/src/markdown-pages/docs/manager-groups/ecosystem-manager-group.md b/src/markdown-pages/docs/manager-groups/ecosystem-manager-group.md index dac951bb..cd18b391 100644 --- a/src/markdown-pages/docs/manager-groups/ecosystem-manager-group.md +++ b/src/markdown-pages/docs/manager-groups/ecosystem-manager-group.md @@ -5,4 +5,4 @@ title: "Ecosystem Managers" Name | Description | | :-------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **[Galasa Ecosystem Manager](/docs/managers/galasa-ecosystem-manager)**
![alpha](../../../images/alpha.svg) | Deploys an entire Galasa ecosystem to Kubernetes to enable integration testing against Galasa. | +| **[Galasa Ecosystem Manager](/docs/managers/galasa-ecosystem-manager)**
![alpha](../../../images/alpha.svg) | Deploys an entire Galasa Ecosystem to Kubernetes to enable integration testing against Galasa. | diff --git a/src/markdown-pages/docs/managers.md b/src/markdown-pages/docs/managers.md index 001ccfac..e510a5f6 100644 --- a/src/markdown-pages/docs/managers.md +++ b/src/markdown-pages/docs/managers.md @@ -77,7 +77,7 @@ Each Manager is tagged with one of the follow readiness indicators: Name | Description | | :-------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **[Galasa Ecosystem Manager](/docs/managers/galasa-ecosystem-manager)**
![alpha](../../images/alpha.svg) | Deploys an entire Galasa ecosystem to Kubernetes to enable integration testing against Galasa. | +| **[Galasa Ecosystem Manager](/docs/managers/galasa-ecosystem-manager)**
![alpha](../../images/alpha.svg) | Deploys an entire Galasa Ecosystem to Kubernetes to enable integration testing against Galasa. |
diff --git a/src/markdown-pages/docs/running-simbank-tests.md b/src/markdown-pages/docs/running-simbank-tests.md index dc5c0874..0e4f6d05 100644 --- a/src/markdown-pages/docs/running-simbank-tests.md +++ b/src/markdown-pages/docs/running-simbank-tests.md @@ -10,9 +10,7 @@ Galasa SimBank comes with a selection of prepared Galasa tests: - A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. - A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. -The following sections explain how to run the `SimBankIVT` test class by using the Galasa CLI and by using Eclipse. - -## Running the SimBank IVT test class using the Galasa CLI +The following sections explain how to run the `SimBankIVT` test class by using Eclipse. ## Running the SimBank IVT test class using Eclipse diff --git a/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md index 6e96608b..5740bc69 100644 --- a/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md +++ b/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md @@ -3,14 +3,7 @@ path: "/docs/running-simbank-tests/setting-up-galasa-project-eclipse" title: "Creating a Galasa project using Eclipse" --- -Galasa SimBank comes with a selection of prepared Galasa tests: - -- A basic Installation Verification Test (IVT) which logs on to SimBank - `SimBankIVT.java`. -- A test that updates an account using web services and examines the changes with 3270 screens - `BasicAccountCreditTest.java`. -- A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. -- A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. - -All of these example tests become available when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. +Galasa SimBank comes with a selection of [supplied Galasa SimBank tests](/docs/running-simbank-tests) which become available to run when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](c) section. diff --git a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index efd69b87..fc229d13 100644 --- a/src/markdown-pages/docs/writing-own-tests/running-test-modes.md +++ b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md @@ -16,8 +16,8 @@ title: "Running a Galasa test" There are three modes in which you can run a Galasa test:

- locally, with everything running on the local machine
-- locally but using a shared configuration that is hosted by the Galasa ecosystem
-- remotely, by submitting the test to run in the Galasa ecosystem
+- locally but using a shared configuration that is hosted by the Galasa Ecosystem
+- remotely, by submitting the test to run in the Galasa Ecosystem
The mode in which you choose to run a test depends on what you are trying to achieve. Use the following information to understand which mode is most appropriate for a given scenario. @@ -64,7 +64,7 @@ To reliably run many tests in parallel, deploy your tests to the Galasa Ecosyste - Test results and reports need gathering from a single point. For example, when test results need reporting or exporting to another report-generating system, or when bug investigation can proceed by independent inspection test results and artifacts. -A problem faced in large-scale use of the local JVM method of test invocation is how to gather test results from disparate machines or environments, so that the test results can be combined and form test reports for system health monitoring. This is something that running tests within a Galasa ecosystem handles well, as the results of each test are stored centrally. Test results can be shared with others, enabling independent inspection and debugging of run artifacts. +A problem faced in large-scale use of the local JVM method of test invocation is how to gather test results from disparate machines or environments, so that the test results can be combined and form test reports for system health monitoring. This is something that running tests within a Galasa Ecosystem handles well, as the results of each test are stored centrally. Test results can be shared with others, enabling independent inspection and debugging of run artifacts. - When the clean-up of resources in the system under test is an important requirement diff --git a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md index 42e0346d..3ab32464 100644 --- a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md +++ b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md @@ -3,16 +3,9 @@ path: "/docs/writing-own-tests/setting-up-galasa-project" title: "Creating a Galasa project using the command line" --- -Galasa SimBank comes with a selection of prepared Galasa tests: +Read on to discover more about the structure of a Galasa project, learn how to create and build your own example project, and understand the purpose of the artifacts that are generated. -- A basic Installation Verification Test (IVT) which logs on to SimBank - `SimBankIVT.java`. -- A test that updates an account using web services and examines the changes with 3270 screens - `BasicAccountCreditTest.java`. -- A test that uses a provisioned account object to perform the same test as `BasicAccountCreditTest.java` in an improved test design - `ProvisionedAccountCreditTests.java`. -- A test that exercises the z/OS Batch Manager by simulating the submission of a JCL job to add a number of accounts to the SimBank system - `BatchAccountsOpenTest.java`. - -All of these example tests become available when you set up a Galasa example project. - -## Creating a project by using the Galasa CLI +## Getting started You can quickly and easily create a project structure to accommodate your own independent tests in your local storage by using the [Galasa command line interface](/docs/cli-command-reference/cli-command-reference) (Galasa CLI) that is provided with Galasa. @@ -38,14 +31,11 @@ The Gradle project structure looks somewhat different to the Maven structure bec The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](docs/prerequisites) documentation. - +You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Downloading and installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool) documentation. -## Before you start -Check that an `.m2` folder exists in your user home directory. Built artifacts are placed in the `~/.m2/repository`. On Windows, the user home directory resembles: C:\Users\, on MacOS it will be /Users/ and on Linux /home/. Note that any file or folder beginning with a `.` (period) is a hidden folder, so you might need to change the settings on your operating system to show hidden files. -## A little plan +## Project Structure A full (parent) Galasa project includes several sub-projects, which can also be known as _modules_, some of which are mandatory and some optional. A parent project can contain the following sub-projects: @@ -58,7 +48,7 @@ The parent project establishes all the dependencies for the sub-projects or modu For simplicity, it is assumed that you will only have one version of a test in production at any one time. However, by establishing different versions of your tests, you can have test streams with different versions of the same test project. For the purposes of the forthcoming example, the version of all projects is set to `0.1.0-SNAPSHOT`. -## Creating an example test project +## Creating an example project In the following example we are going to use the Galasa CLI to build a hierarchy of projects, where the parent project _dev.galasa.example.banking_ contains the following modules: - Two test sub-projects or modules called _dev.galasa.example.banking.payee_ and _dev.galasa.example.banking.account_ @@ -175,24 +165,6 @@ Running the example Galasa CLI `project create` command with the `--maven` flag ``` -## Importing the example test project into Eclipse - -If you want to edit source code using an IDE, you might want to import the projects into your IDE workspace. - -The following steps show you how to import an example test project built using Maven into Eclipse: - -1. Launch Eclipse and choose _File > Import..._ -1. In the _Select_ dialog, expand _Maven_, choose _Existing Maven Projects_ and click _Next_. -1. Navigate to your root project directory - _dev.galasa.example.banking_ in this case - and follow the remaining prompts to complete the import. If you see a warning or error dialog, opt to resolve the error later. -1. View your set of projects in _Package Explorer_. - -Complete the following steps to import an example test project built using Gradle into Eclipse: - -1. Launch Eclipse and choose _File > Import..._ -1. In the _Select_ dialog, expand _Gradle_, choose _Existing Gradle Projects_ and click _Next_. -1. Navigate to your root project directory - _dev.galasa.example.banking_ in this case - and follow the remaining prompts to complete the import. If you see a warning or error dialog, opt to resolve the error later. -1. View your set of projects in _Package Explorer_. - ## More about the parent project The top level folder, which is called `dev.galasa.example.banking` in this example, is the parent project. The parent project is a convenient container in which to hold all of the generated files. In Maven the `pom.xml` in the parent project is used to build all the other generated files. In Gradle, the `settings.gradle` file is used. @@ -288,3 +260,23 @@ Other elements that are contained within the generated parent pom.xml are listed ## The test pom.xml file elements - The `` element is set to `galasa-obr` which causes the Galasa Maven plugin to build this project. + + + ## Importing the example test project into Eclipse + +If you want to edit source code using an IDE, you might want to import the projects into your IDE workspace. + +The following steps show you how to import an example test project built using Maven into Eclipse: + +1. Launch Eclipse and choose _File > Import..._ +1. In the _Select_ dialog, expand _Maven_, choose _Existing Maven Projects_ and click _Next_. +1. Navigate to your root project directory - _dev.galasa.example.banking_ in this case - and follow the remaining prompts to complete the import. If you see a warning or error dialog, opt to resolve the error later. +1. View your set of projects in _Package Explorer_. + +Complete the following steps to import an example test project built using Gradle into Eclipse: + +1. Launch Eclipse and choose _File > Import..._ +1. In the _Select_ dialog, expand _Gradle_, choose _Existing Gradle Projects_ and click _Next_. +1. Navigate to your root project directory - _dev.galasa.example.banking_ in this case - and follow the remaining prompts to complete the import. If you see a warning or error dialog, opt to resolve the error later. +1. View your set of projects in _Package Explorer_. + diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index 8349cfe0..cf2f184e 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -292,7 +292,7 @@ These settings assume a zOS/MF server on MV2D and the port overridden from `443` - z/OS Batch Manager (beta) - enabling tests and Managers to submit, monitor and retrieve z/OS batch jobs. - CICS CECI Manager (alpha) - providing CECI 3270 interaction - initially supporting containers and link programs. -- Ecosystem Manager (alpha) - enabling deployment of an entire Galasa ecosystem to Kubernetes to enable integration testing against Galasa. +- Ecosystem Manager (alpha) - enabling deployment of an entire Galasa Ecosystem to Kubernetes to enable integration testing against Galasa. - Docker Manager (release) - enabling containers to run on infrastructure Docker engines - either for testing directly or for assisting the testing process. - Documentation update - how to start writing your own Simbank tests. - Documentation update - new SimBank z/OS Batch Manager tutorial available. From db2f8fddafe333de9e1e48552b1435d63f9b1535 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Mon, 25 Sep 2023 13:33:29 +0100 Subject: [PATCH 3/6] fix links --- .../docs/first-steps/installing-offline.md | 2 +- .../setting-up-galasa-project-eclipse.md | 24 +++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) rename src/markdown-pages/docs/{running-simbank-tests => first-steps}/setting-up-galasa-project-eclipse.md (95%) diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 6dff42d6..68f1e707 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -14,7 +14,7 @@ The `docs.jar` file enables you to run the Galasa website locally on your machin ## Getting started -If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. +If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](/docs/prerequisites) documentation. 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). diff --git a/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md similarity index 95% rename from src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md rename to src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md index 5740bc69..0934c256 100644 --- a/src/markdown-pages/docs/running-simbank-tests/setting-up-galasa-project-eclipse.md +++ b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md @@ -3,11 +3,11 @@ path: "/docs/running-simbank-tests/setting-up-galasa-project-eclipse" title: "Creating a Galasa project using Eclipse" --- -Galasa SimBank comes with a selection of [supplied Galasa SimBank tests](/docs/running-simbank-tests) which become available to run when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. +Galasa SimBank comes with a selection of [supplied Galasa SimBank tests](../running-simbank-tests.md) which become available to run when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. -If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](c) section. +If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](#headmaven) section. -If you are using the Galasa plug-in from the external update site and are using Gradle, follow the instructions in the [_Creating an example Galasa project using Gradle_](#headonlinegradle) section. +If you are using the Galasa plug-in from the external update site and are using Gradle, follow the instructions in the [_Creating an example Galasa project using Gradle_](#createprojectgradle) section. If you are using the Galasa zipped distribution you must use Gradle to build your project, so follow the instructions in the [_Creating an example Galasa project using Gradle (zipped distribution)_](#headgradle) section. @@ -26,7 +26,7 @@ The Gradle project structure looks somewhat different to the Maven structure bec The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](docs/prerequisites) documentation. +You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. ## Before you start @@ -61,11 +61,11 @@ For simplicity, it is assumed that you will only have one version of a test in p 4. Right-click on `dev.galasa.simbank.manager` and choose _Run As > Maven install_ - wait a few moments for the Maven build and then right-click on `dev.galasa.simbank.tests` and do the same. Note that the order in which you do this is significant - first `dev.galasa.simbank.manager` and then `dev.galasa.simbank.tests`. This is because the SimBank tests have a dependency on the SimBank Manager. 5. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. 6. Explore the `dev.galasa.simbanks.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./provided-tests.png) + ![SimBank tests](../provided-tests.png) -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](../running-simbank-tests/simbank-IVT) is the best place to start. -## Creating an example Galasa project using Gradle +## Creating an example Galasa project using Gradle 1. Ensure that Eclipse is running. 2. Depending on your operating system, choose either _Window > Preferences_ or _Eclipse > Preferences_, check that you are using the correct version of Gradle. @@ -81,14 +81,14 @@ Explore these tests by selecting from the left-hand menu - if you are new to Gal 6. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. 7. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. 8. Provide a meaningful name and set up your Gradle Task to run a clean build. - ![SimBank tests](./clean-build.png) + ![SimBank tests](../clean-build.png) 9. In _Working Directory_, click *Workspace*, select `dev.galasa.simbank.parent` and click `OK`. 10. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. 11. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. 12. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./gradle-tests.png) + ![SimBank tests](../gradle-tests.png) -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](../running-simbank-tests/simbank-IVT) is the best place to start. ## Creating an example Galasa project using Gradle (zipped distribution) @@ -205,9 +205,9 @@ Explore these tests by selecting from the left-hand menu - if you are new to Gal 16. Click _Apply_ then _Run_. A _BUILD SUCCESSFUL_ message is displayed in the _Console_ tab. 17. Expand `dev.galasa.simbank.tests` and then expand `src/main/java`. 18. Explore the `dev.galasa.simbank.tests` package. You'll see the group of tests provided with SimBank: - ![SimBank tests](./gradle-tests.png) + ![SimBank tests](../gradle-tests.png) -Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](/docs/running-simbank-tests/simbank-IVT) is the best place to start. +Explore these tests by selecting from the left-hand menu - if you are new to Galasa, [The SimBank IVT](../running-simbank-tests/simbank-IVT) is the best place to start. ## More about the parent project From 36d9d50e9f0a9ed08cf7192f6b4c4947ae8fd8ae Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Mon, 25 Sep 2023 14:58:01 +0100 Subject: [PATCH 4/6] fixes --- src/data/nav.yaml | 2 +- src/markdown-pages/doc_root.md | 2 +- .../cli-command-reference/cli-command-reference.md | 6 +++--- .../docs/cli-command-reference/installing-cli-tool.md | 10 +++++----- .../docs/cli-command-reference/runs-local-debug.md | 2 +- src/markdown-pages/docs/first-steps/getting-started.md | 2 +- .../docs/first-steps/initialising-home-folder.md | 2 +- .../docs/first-steps/installing-offline.md | 2 +- .../first-steps/setting-up-galasa-project-eclipse.md | 6 +++--- src/markdown-pages/docs/first-steps/simbank.md | 8 ++++---- src/markdown-pages/docs/running-simbank-tests.md | 4 ++-- src/markdown-pages/docs/writing-own-tests.md | 2 +- .../writing-own-tests/setting-up-galasa-project.md | 2 +- 13 files changed, 25 insertions(+), 25 deletions(-) diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 73d75c92..ffacaed5 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -35,7 +35,7 @@ - title: Getting started using the Galasa CLI path: /docs/cli-command-reference/cli-command-reference items: - - title: Downloading and installing the Galasa CLI + - title: Installing the Galasa CLI path: /docs/cli-command-reference/installing-cli-tool - title: Initialising your local environment path: /docs/initialising-home-folder diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 744a846b..467501d3 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -16,7 +16,7 @@ If you do not have access to Maven Central, Eclipse Marketplace, and Docker Hub ## Next steps -If you are installing Galasa for using in the command-line, following the instructions in [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation. +If you are installing Galasa for using in the command-line, follow the instructions in the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation. If you are installing Galasa for using in the Eclipse, or if you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using Eclipse](/docs/getting-started) documentation. diff --git a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md index e83f64ce..1ef450d6 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md @@ -27,7 +27,7 @@ Once you have installed the Galasa CLI, you can use the following command to get galasactl --help ``` -Use the following options to send logging information to a file. Any folder that is referrenced must exist. Existing files are overwritten. Specify `-` to log to `stderr`. The default is no logging. +Use the `--log` option to send logging information to a file. Any folder that is referenced must exist. Existing files are overwritten. Specify `-` to log to `stderr`. The default is no logging. ``` galasactl --log @@ -35,11 +35,11 @@ galasactl --log ## Errors -You can view a list of error messages that can be output by the galasactl tool in the Galasa cli repository in GitHub. +You can view a list of error messages that can be generated by the galasactl tool in the Galasa cli repository in GitHub. ## Next steps -To install Galasa for using in the command line, follow the instructions in [Downloading and installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool). +To install Galasa for using in the command line, follow the instructions in the [Installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool) documentation. diff --git a/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md index 95ca14af..8010605a 100644 --- a/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md +++ b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md @@ -1,9 +1,9 @@ --- path: "/docs/cli-command-reference/installing-cli-tool" -title: "Downloading and installing the Galasa CLI" +title: "Installing the Galasa CLI" --- -This section provides details about prerequisite software requirements and information about how to download and install the Galasa CLI on your local machine. +This section provides details about prerequisite software requirements and information about how to download and install the Galasa command line interface tool (Galasa CLI) on your local machine. ## Prerequisites @@ -40,11 +40,11 @@ On Mac or Unix: 1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. 2. Download the appropriate binary of the Galasa CLI for your machine architecture from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub and re-name it to `galasactl`. -3. Add Galasa CLI to your PATH to enable you to run CLI commands from anywhere on your file system without having to specify the absolute path. To set the path permanently, you need add the Galasa CLI path to your shell's initialization file. For example, if you downloaded the galasactl executable to a folder called `~/tools` in your home directory, you need to add `~/tools` to the list of directories that your shell searches through when you enter a command. You can do this by adding the line ```export PATH=$PATH:$HOME/tools``` to your shell’s initialization file (for example `~/.bashrc` or `~/.zshrc`). You should now be able to run the Galasa CLI too from any directory in your file system. +3. Add Galasa CLI to your PATH to enable you to run CLI commands from anywhere on your file system without having to specify the absolute path. To set the path permanently, you need add the Galasa CLI path to your shell's initialization file. For example, if you downloaded the galasactl executable to a folder called `~/tools` in your home directory, you need to add `~/tools` to the list of directories that your shell searches through when you enter a command. You can do this by adding the line ```export PATH=$PATH:$HOME/tools``` to your shell’s initialization file (for example `~/.bashrc` or `~/.zshrc`). 4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. 5. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command. -You are now able to run Galasa CLI commands from the command line. +You can now run the Galasa CLI too from any directory in your file system without having to specify the absolute path. On Windows (Powershell) @@ -53,7 +53,7 @@ On Windows (Powershell) 2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. 3. Open `cmd.exe` and type `start galasactl.exe` in the directory containing `galasactl`. -You are now able to run Galasa CLI commands from the command line. +You can now run the Galasa CLI too from any directory in your file system without having to specify the absolute path. ## Next steps diff --git a/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md b/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md index 46ea4f19..e4d6004d 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md @@ -3,7 +3,7 @@ path: "/docs/cli-command-reference/cli-runs-local-debug" title: "Debugging a test locally" --- -The following section describes how to connect your Galasa test with a Java debugger on a specified port, and then configure your IDE (IDE options covered in this topic are Microsoft VSCode,IntelliJ, and Eclipse) to connect to that same port so that you can run your test locally in debug mode. +The following section describes how to connect your Galasa test with a Java debugger on a specified port, and then configure your IDE (IDE options covered in this topic are Microsoft VSCode, IntelliJ, and Eclipse) to connect to that same port so that you can run your test locally in debug mode. ## Using the debug option diff --git a/src/markdown-pages/docs/first-steps/getting-started.md b/src/markdown-pages/docs/first-steps/getting-started.md index d3072d00..f5230cdc 100644 --- a/src/markdown-pages/docs/first-steps/getting-started.md +++ b/src/markdown-pages/docs/first-steps/getting-started.md @@ -3,7 +3,7 @@ path: "/docs/getting-started" title: "Getting started using Eclipse" --- -Before development of the Galasa command line tool (galasactl), Eclipse was the main focus for getting started with using Galasa and exploring Simbank and it continues to provide an alternative UI experience to the equivalent command line option. +Before development of the Galasa command line tool (Galasa CLI), Eclipse was the main focus for getting started with using Galasa and exploring Simbank and it continues to provide an alternative UI experience to the equivalent command line option. If you are planning to install and use Galasa with Eclipse, you need to have an Eclipse installation on your machine. 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. diff --git a/src/markdown-pages/docs/first-steps/initialising-home-folder.md b/src/markdown-pages/docs/first-steps/initialising-home-folder.md index abec7fd7..ee3d2b8a 100644 --- a/src/markdown-pages/docs/first-steps/initialising-home-folder.md +++ b/src/markdown-pages/docs/first-steps/initialising-home-folder.md @@ -5,7 +5,7 @@ title: "Initialising your local environment" To start using Galasa tools, or running Galasa tests, you need to set up some basic file structures and files in your home folder. These files include a default bootstrap file, and some local properties files. For more information about these files and what they are used for, see the [About the properties files](#about) section. -The following section shows you how to initialise your Galasa home folder by using the Galasa command line interface (Galasa CLI) tool that is provided with Galasa. Once your home folder is initialised, you can start running Galasa tests on your local JVM. +The following section shows you how to initialise your Galasa home folder by using the Galasa command line interface tool (Galasa CLI) that is provided with Galasa. Once your home folder is initialised, you can start running Galasa tests on your local JVM. You can view the full list of options (flags) that are available with the `galasactl local init` command in the [Galasa cli repository](https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_local_init.md). diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 68f1e707..1f7e9aee 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -14,7 +14,7 @@ The `docs.jar` file enables you to run the Galasa website locally on your machin ## Getting started -If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Prerequisites](/docs/prerequisites) documentation. +If you are installing Galasa by using Eclipse, begin with the Eclipse IDE (you can download it from the Eclipse website) and the download and integration of the Galasa plug-in. Check the current compatibility between Eclipse and Galasa versions in the table provided in the [Getting started using Eclipse](/docs/getting-started) documentation. 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). diff --git a/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md index 0934c256..59bf7754 100644 --- a/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md +++ b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md @@ -1,9 +1,9 @@ --- path: "/docs/running-simbank-tests/setting-up-galasa-project-eclipse" -title: "Creating a Galasa project using Eclipse" +title: "Creating a project using Eclipse" --- -Galasa SimBank comes with a selection of [supplied Galasa SimBank tests](../running-simbank-tests.md) which become available to run when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. +Galasa SimBank comes with a selection of [supplied Galasa SimBank tests](../running-simbank-tests) which become available to run when you set up a Galasa example project within Eclipse. You can set up a project by using either [Maven](#maven) or [Gradle](#gradle), unless you are using the zipped distribution of Galasa, in which case you must use Gradle. If you are using the Galasa plug-in from the external update site and are using Maven, follow the instructions in the [_Creating an example Galasa project using Maven_](#headmaven) section. @@ -26,7 +26,7 @@ The Gradle project structure looks somewhat different to the Maven structure bec The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Prerequisites](prerequisites) documentation. +All Galasa versions are compatible with Gradle releases 6.8.x and later. ## Before you start diff --git a/src/markdown-pages/docs/first-steps/simbank.md b/src/markdown-pages/docs/first-steps/simbank.md index 82d4b944..f21ff63e 100644 --- a/src/markdown-pages/docs/first-steps/simbank.md +++ b/src/markdown-pages/docs/first-steps/simbank.md @@ -45,19 +45,19 @@ When you launch SimBank, its banking application listens on port 2023 for incomi 1. With Eclipse and the *Galasa SimBank* component still running, configure your 3270 terminal emulator to access port *2023* of *localhost* (or IP address 127.0.0.1 if the *localhost* alias has not been set up) via the Telnet protocol. No SSL configuration is required. 1. Connect to the listening Telnet service with your 3270 emulator and review the logon screen: - ![SimBank logon screen](simbank-logon.png) + ![SimBank logon screen](../first-steps/simbank-logon.png) 1. Ensure that the cursor is in the `Userid` field - if it is not, use the TAB key to position it: - ![TAB to the userid field](simbank-userid.png) + ![TAB to the userid field](../first-steps/simbank-userid.png) 1. Enter the userid `IBMUSER` - ![Enter your userid](./simbank-ibmuser.png) + ![Enter your userid](../first-steps/simbank-ibmuser.png) 1. Press TAB to move the cursor into the `Password` field, type the password `SYS1` and press your terminal emulator's ENTER key to logon and transfer to the SimBank main menu: - ![Banktest home screen](./simbank-banktest.png) + ![Banktest home screen](../first-steps/simbank-banktest.png) > *Note:* Depending on your terminal emulator, its ENTER key may not be mapped to the physical ENTER key on your computer. For example, > on PCOMM, by default, the ENTER key is mapped to the host machine's right CTRL key. If you are unsure about this, review diff --git a/src/markdown-pages/docs/running-simbank-tests.md b/src/markdown-pages/docs/running-simbank-tests.md index 0e4f6d05..6d3fe563 100644 --- a/src/markdown-pages/docs/running-simbank-tests.md +++ b/src/markdown-pages/docs/running-simbank-tests.md @@ -15,8 +15,8 @@ The following sections explain how to run the `SimBankIVT` test class by using E ## Running the SimBank IVT test class using Eclipse -1. Create your initial example projects as described in Running the supplied SimBank tests - a once-only activity. -1. Ensure that Eclipse is running, your example projects are open and that you have launched SimBank as described in Exploring SimBank. +1. Create your initial example projects as described in Creating a project using Eclipse - a once-only activity. +1. Ensure that Eclipse is running, your example projects are open and that you have launched SimBank as described in Exploring Galasa SimBank. 1. Choose _Run > Run Configurations_ and look for and select _Galasa - Java_ in the left pane (not Galasa SimBank). 1. Right-click _Galasa_, choose _New Configuration_ and give it a name. 1. In the dialog, choose _Browse_ to locate your project - `dev.galasa.simbank.tests`, then press _OK_. Then press _Search_ to locate your test class, `SimBankIVT` and press _OK_. diff --git a/src/markdown-pages/docs/writing-own-tests.md b/src/markdown-pages/docs/writing-own-tests.md index 93ab9e7f..28724cd3 100644 --- a/src/markdown-pages/docs/writing-own-tests.md +++ b/src/markdown-pages/docs/writing-own-tests.md @@ -5,7 +5,7 @@ title: "Writing your own independent Galasa tests" Writing your own tests (that is, tests within an independent project of your own creation) involves two kinds of activity: -- Using the [Galasa command line interface](/docs/cli-command-reference/cli-command-reference) to create an appropriate project structure. +- Using the [Galasa command line interface](/docs/cli-command-reference/cli-command-reference) (or Eclipse) to create an appropriate project structure. - Leveraging a collection of organisational principles that will help guide you towards a clean implementation that can eventually be moved into CI/CD and full automation. These two strands involve exploiting the features of a well-known and trusted Open Source application called Maven for project setup and dependency management. diff --git a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md index 3ab32464..6f5f1094 100644 --- a/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md +++ b/src/markdown-pages/docs/writing-own-tests/setting-up-galasa-project.md @@ -31,7 +31,7 @@ The Gradle project structure looks somewhat different to the Maven structure bec The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -You can check the current compatibility between Gradle and Galasa versions in the table provided in the [Downloading and installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool) documentation. +All Galasa versions are compatible with Gradle releases 6.8.x and later. From 3d44a41222934f50b38b566d3dc8532cfaa3032c Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 28 Sep 2023 13:56:29 +0100 Subject: [PATCH 5/6] review updates --- src/markdown-pages/doc_root.md | 2 +- .../installing-cli-tool.md | 4 +- .../docs/ecosystem/ecosystem-architecture.md | 2 +- .../first-steps/initialising-home-folder.md | 22 +++--- .../docs/first-steps/prerequisites.md | 71 ------------------- 5 files changed, 14 insertions(+), 87 deletions(-) delete mode 100644 src/markdown-pages/docs/first-steps/prerequisites.md diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 467501d3..6b0123a5 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -5,7 +5,7 @@ title: "Installing options" There are a few options available when installing Galasa. Prerequisites vary, depending on the option that is chosen. -You can install Galasa for using in the command-line, for using Eclipse, or for sharing with your department (using the Galasa zipped distribution). +You can install Galasa for using in the command-line, for using in Eclipse, or for sharing with your department (using the Galasa zipped distribution). There are benefits of installing Galasa for using in the command-line. Much of the configuration set-up that is required is done for you automatically by scripts, so less manual intervention is needed. You can then import the configuration into an IDE of your choice, rather than having to use Eclipse. diff --git a/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md index 8010605a..06e2bba6 100644 --- a/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md +++ b/src/markdown-pages/docs/cli-command-reference/installing-cli-tool.md @@ -29,8 +29,6 @@ The following versions of the Galasa CLI are available to download for different | zLinux | galasactl-linux-s390x | | Windows | galasactl-windows-x86_64.exe | -You can find out the architecture of your machine by typing the command `uname -m` into your Mac or Linux terminal. - ## Installing the Galasa CLI @@ -50,7 +48,7 @@ You can now run the Galasa CLI too from any directory in your file system withou On Windows (Powershell) 1. Download the binary and re-name it to `galasactl`. -2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. +2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. For example, save the galasactl executable to a folder called `~/tools` in your `C:` directory and run the `setx PATH "C:\tools;%PATH%"` command to add it to your PATH. 3. Open `cmd.exe` and type `start galasactl.exe` in the directory containing `galasactl`. You can now run the Galasa CLI too from any directory in your file system without having to specify the absolute path. diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index 6e4cbb13..000b484a 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -19,7 +19,7 @@ The following diagram highlights a some of the key components that make up the G | | | | ------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | -| **Configuration Property Store** | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. | +| **Configuration Property Store** | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. *Note:* As IP addresses and ports of test machines are stored within the CPS on a users system, we recommend that hard drive encryption is turned on in the operating system where possible. | | **Dynamic Status Store** | The dynamic status store (DSS) provides status information about the ecosystem and the tests that are running. The DSS is used by the resource manager and engine controller to ensure the limits that are set in the CPS configuration are not exceeded. DSS property values change dynamically as tests are run, showing the resources that are currently being used, shared or locked by a test, so that workloads can be limited to avoid throttling. When running in automation, the DSS is shared by every instance of the framework. | | **Result Archive Store** | The result archive store (RAS) is a single database which stores all elements of a test, including the test results, run logs, and test artifacts. These elements can be used to help diagnose the cause of any failures encountered as a result of running a test, or to gather information about a test. Storing all of this information in one place makes it simple for entire teams to view results. | | **Credentials Store** | The credentials store (CREDs) securely provides the credentials, for example, password, username and authentication token that are required for a test to run in automation. The CREDs is hosted in the etcd server. | diff --git a/src/markdown-pages/docs/first-steps/initialising-home-folder.md b/src/markdown-pages/docs/first-steps/initialising-home-folder.md index ee3d2b8a..1aca9fbc 100644 --- a/src/markdown-pages/docs/first-steps/initialising-home-folder.md +++ b/src/markdown-pages/docs/first-steps/initialising-home-folder.md @@ -3,9 +3,9 @@ path: "/docs/initialising-home-folder" title: "Initialising your local environment" --- -To start using Galasa tools, or running Galasa tests, you need to set up some basic file structures and files in your home folder. These files include a default bootstrap file, and some local properties files. For more information about these files and what they are used for, see the [About the properties files](#about) section. +To start using Galasa tools, or running Galasa tests, you need to set up some basic file structures and files in your home directory. These files include a default bootstrap file, and some local properties files. For more information about these files and what they are used for, see the [About the properties files](#about) section. -The following section shows you how to initialise your Galasa home folder by using the Galasa command line interface tool (Galasa CLI) that is provided with Galasa. Once your home folder is initialised, you can start running Galasa tests on your local JVM. +The following section shows you how to initialise your Galasa home directory by using the Galasa command line interface tool (Galasa CLI) that is provided with Galasa. Once your home directory is initialised, you can start running Galasa tests on your local JVM. You can view the full list of options (flags) that are available with the `galasactl local init` command in the [Galasa cli repository](https://github.com/galasa-dev/cli/blob/main/docs/generated/galasactl_local_init.md). @@ -45,7 +45,7 @@ galasactl local init ``` -This one-time command is run once per user and helps you to quickly create the folder and files that you need. If you already have a Galasa home folder set up, the folder and files are not created. +This one-time command is run once Galasa home directory and helps you to quickly create the folder and files that you need. If you already have a Galasa home folder set up, the folder and files are not created. The command creates the following file structure, with default contents in each of the properties files: @@ -67,7 +67,7 @@ The following table explains a bit more about the purpose of the properties file | Name | Description | | :---- | :-------- | | bootstrap.properties | The bootstrap contains the information that Galasa needs to bring up a framework in the environment to connect to the Galasa Ecosystem. If you are running a test on your local machine, the bootstrap file is blank as it does not need to refer to the ecosystem. | -| cps.properties | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. You can extract a test property value from the CPS file for use in a test by using the `@TestProperty` annotation that is provided by the Core Manager.| +| cps.properties | The configuration property store (CPS) defines object properties, topologies, system configurations, and definitions which instruct the way in which a Galasa test runs. For example, properties for endpoints, ports and timeouts. When running in an ecosystem, all Galasa tests will use the same CPS configuration, unless any overrides are passed at submission. It is the CPS and the configurational properties that enable tests to run against multiple environments, without changing the code inside the test. You can extract a test property value from the CPS file for use in a test by using the `@TestProperty` annotation that is provided by the Core Manager. | | credentials.properties | It is likely that a test will need to pass credentials to the application being tested. For example, as HTTP credentials or as username and password values entered onto a 3270 screen. Rather than hard code the credentials inside a test class, you can store the values in the credentials.properties file when the test is run locally. The ability to get credentials from a credentials store means that you do not need to hard code these values inside a test, enabling the test to be run in different environments without changing a single line of code. You can extract credentials to use in your test by using the `getCredentials` method that is provided by the Core Manager. | | dss.properties | The dynamic status store (DSS) provides status information about the ecosystem and the tests that are running. The DSS is used by the resource manager and engine controller to ensure the limits that are set in the CPS configuration are not exceeded. DSS property values change dynamically as tests are run, showing the resources that are currently being used, shared or locked by a test, so that workloads can be limited to avoid throttling. When running tests locally (inside Eclipse or using the CLI), all tests use the local file as the DSS. | | overrides.properties | Specifying overrides is useful if you want to run a set of tests against a particular configuration without changing the test code. For example, you might have multiple versions of software that you need to test. How can you do that without changing the test code? The answer is to use override properties. If you are running tests locally, you can set overrides properties by editing your Overrides Properties file. | @@ -80,26 +80,26 @@ The bootstrap is a simple properties file that contains the information that Gal If you are planning to only run tests locally, with everything running on the local machine, you do not need to set the Galasa bootstrap. Otherwise, you can set the bootstrap either by using the `--bootstrap` option on the CLI command or by setting the `GALASA_BOOTSTRAP` environment variable. If both are provided, the `--bootstrap` option takes precedence. -You can set environment variables on a terminal by using the `export` (if you are on Mac or Linux) or `set` (if you are on Windows) command. For example, to set `GALASA_BOOTSTRAP` to `http://my-bootstrap-url`, use the following command: +You can set environment variables on a terminal by using the `export` (if you are on Mac or Linux) or `set` (if you are on Windows) command. For example, to set `GALASA_BOOTSTRAP` to `http://galasa-bootstrap.example.org`, use the following command: On Mac or Unix: ``` -export GALASA_BOOTSTRAP=http://my-bootstrap-url +export GALASA_BOOTSTRAP=http://galasa-bootstrap.example.org ``` On Windows: ``` -set GALASA_BOOTSTRAP=http://my-bootstrap-url +set GALASA_BOOTSTRAP=http://galasa-bootstrap.example.org ``` -## Initialising the settings.xml file - -The `settings.xml` file enables you to set configurations for Maven to use during test runs. For example, you can set local and remote repository locations, credentials for private repositories, and Maven profile settings. +## Initialising the Maven settings.xml file + +If you have Maven installed, and have run a Maven command, an `/.m2` directory, containing a folder called `repositories`, should exist in your home directory. Running the `galasa local init` command then automatically creates a `settings.xml` file in this `/.m2` directory, and populates the file with basic configuration settings. If an `/.m2` directory does not exist, the `galasactl local init` command creates it, as well as the `settings.xml` file. -If you have Maven installed, and have run a Maven command, an `/.m2` folder, containing a folder called `repositories`, should exist in your home directory. Running the `galasa local init` command then automatically creates a `settings.xml` file in this `/.m2` folder, and populates the file with basic configuration settings. +The `settings.xml` file enables you to set configurations for Maven to use during test runs. For example, you can set local and remote repository locations, credentials for private repositories, and Maven profile settings. ## Next steps diff --git a/src/markdown-pages/docs/first-steps/prerequisites.md b/src/markdown-pages/docs/first-steps/prerequisites.md deleted file mode 100644 index 57aea02d..00000000 --- a/src/markdown-pages/docs/first-steps/prerequisites.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -path: "/docs/prerequisites" -title: "Galasa Prerequisites" ---- - -This section takes you through the software prerequisites required before installing Galasa. The prerequisites vary, depending on the whether you are installing Galasa for using in the command-line, or for using in Eclipse. If you are installing Galasa for using in Eclipse, the prerequisites also vary depending on whether you are downloading Galasa directly from the external update site, or are using the zipped distribution. - -For information about installing options, see the [Installing options](../../about_Galasa.md) documentation. - -
- -### Installing Galasa for using in the command-line - -| Software | Description | -| :---- | :-------- | -| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | -| Maven or [Gradle](#gradle) | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. | -| Galasa CLI tool | Required. The tool enables interactions with Galasa via the command line. See [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference) for more information about installing the tool. | -| 3270 emulator | Optional. 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.| - - -Once you have installed the relevant software, you are ready to install Galasa. To install Galasa for using the command line, follow the instructions in [Getting started using the Galasa CLI](/docs/cli-command-reference/cli-command-reference). - -
- -### Installing Galasa for using in Eclipse - -| Software | Description | -| :---- | :-------- | -| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | -| Eclipse | Required. Provides the ability to interact with and use Galasa. See the [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | -| Maven or [Gradle](#gradle) | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration.| -| 3270 emulator | Optional. 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.| - -Once you have installed the relevant software, you are ready to install Galasa. To install the Galasa for using in Eclipse, follow the instructions in [Installing the Galasa plug-in](/docs/getting-started/installing-online). - -
- -### Installing Galasa for using in Eclipse (zipped distribution) - -| Software | Description | -| :---- | :-------- | -| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | -| [Gradle](#gradle) | Required to install the zipped distribution. You can also build Galasa projects using Gradle (or you can use Maven to build projects if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. | -| Eclipse | Required. Provides the ability to interact with and use Galasa. See [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | -| 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. | -| Maven | Optional (as Gradle is required). You can use Maven rather than Gradle to build Galasa projects. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | -| 3270 emulator | Optional. 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.| - -Once you have installed the relevant software, you are ready to install Galasa. To install the zipped distribution of Galasa, follow the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). - - -### Gradle - -Gradle is required if you are installing the zipped distribution of Galasa, or if you want to use Gradle rather than Maven to build Galasa projects (hierarchical file structures that provide the ability to store and run Galasa tests). - -The following table shows the current compatibility between Gradle and Galasa versions: - - -| Gradle release | Compatible Galasa version | -| :---- | :-------- | -| 6.8.x | All | -| 6.9.x | All | -| 7.x.x | All | - - - -## Next steps - -Start exploring Galasa Simbank; a component distributed with Galasa that you can start playing with to help you to learn about the Galasa basics. - From 874a7ccd39204b72fbc698450ae547b4c77e0b55 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 28 Sep 2023 14:13:27 +0100 Subject: [PATCH 6/6] review updates --- src/markdown-pages/docs/first-steps/initialising-home-folder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/markdown-pages/docs/first-steps/initialising-home-folder.md b/src/markdown-pages/docs/first-steps/initialising-home-folder.md index 1aca9fbc..347ac091 100644 --- a/src/markdown-pages/docs/first-steps/initialising-home-folder.md +++ b/src/markdown-pages/docs/first-steps/initialising-home-folder.md @@ -45,7 +45,7 @@ galasactl local init ``` -This one-time command is run once Galasa home directory and helps you to quickly create the folder and files that you need. If you already have a Galasa home folder set up, the folder and files are not created. +This one-time command is run once per Galasa home directory and helps you to quickly create the folder and files that you need. If you already have a Galasa home folder set up, the folder and files are not created. The command creates the following file structure, with default contents in each of the properties files: