From 41bf22f228d3bfab737bda28f9f7a6bfa6e06e8a Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 7 Feb 2024 11:42:57 +0000 Subject: [PATCH 01/22] runs reset and cancel cmds --- src/data/nav.yaml | 2 + .../cli-command-reference/runs-download.md | 2 +- .../runs-reset-cancel.md | 46 +++++++++++++++++++ 3 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md diff --git a/src/data/nav.yaml b/src/data/nav.yaml index c7d7baaa..21dbde37 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -115,6 +115,8 @@ path: /docs/cli-command-reference/ecosystem-cli-runs-prepare - title: Running tests in the Ecosystem path: /docs/cli-command-reference/ecosystem-cli-runs-submit + - title: Retrying and deleting tests + path: /docs/cli-command-reference/runs-reset-cancel - title: Viewing test run results path: /docs/cli-command-reference/cli-runs-get - title: Downloading test artifacts diff --git a/src/markdown-pages/docs/cli-command-reference/runs-download.md b/src/markdown-pages/docs/cli-command-reference/runs-download.md index ca0c34ad..0a650d73 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-download.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-download.md @@ -62,7 +62,7 @@ GAL2501I: Downloaded 11 files to folder U5432_2023-05-06_10:30:15 ### Identifying output for test retries -If a test is scheduled to run at a particular time but is unable to start, for example due to a lack of resources that are available in the environment, the ecosystem might retry the test at a later time. When investigating problems with a test running in an ecosystem, it is useful to download the artifacts that are associated with the retries of that test. +If a test is scheduled to run at a particular time but is unable to start, for example due to a lack of resources that are available in the environment, the Ecosystem might retry the test at a later time. When investigating problems with a test running in an Ecosystem, it is useful to download the artifacts that are associated with the retries of that test. When using the `runs download` command, if a test has run more than once, a number is added to the folder name to indicate the number of the retry, as shown in the following example: diff --git a/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md new file mode 100644 index 00000000..9b9d9a24 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md @@ -0,0 +1,46 @@ +--- +path: "/docs/cli-command-reference/runs-reset-cancel" +title: "Retrying and deleting tests" +--- + + +Sometimes tests can become stuck in a loop and fail to finish running, for example, due to a lack of available resources, an environmental problem, or a timeout. You can retry a test to run again by using the `runs reset` command. If the test continues to fail to finish running, you can use the `runs cancel` command to delete the test. + +Retrying a test sets the status of the test run in the DSS to `queued` status. Deleting a test deletes all entries in the DSS for that test run. For this reason it is preferable to retry a test rather than delete a test. All information that is stored in the RAS about the test is kept and is not deleted when either the `runs reset` or `runs cancel` command is run. + + +You can view the full list of options that are available with the `runs reset` and `runs cancel` commands in the +Galasa cli repository. + +## Working with the `runs reset` command + +The following example retrys a test run called _C1234_ by using the following command: + +``` +galasactl runs reset --name C1234 +``` + +### Output for test retries + +When using the [galasactl runs download](ecosystem-cli-runs-download) command to view test results, if a test has run more than once, a number is added to the folder name to indicate the number of the retry, as shown in the following example: + +``` +C1234-1-2023-05-25_18:30:26 +C1234-2-2023-05-25_18:30:26 +C1234-3 +``` + +In this example, the test _C1234_ tried to run twice unsuccessfully and completed on the third try. The numbers _1_ and _2_ in the folder names of the first two test run attempts indicate the retry order. The inclusion of the timestamp in folder name of the first two tries indicates that the test did not finish running. The third time the test finished running, so no timestamp is included as part of the name of the folder. + +## Working with the `runs cancel` command + +The following example deletes a test run called _C1234_ by using the following command: + +``` +galasactl runs cancel --name C1234 +``` + +All information that is held in the DSS about the test run is deleted. + + + From f7cbbb4b2e48c8732f38128f6f40f482dd1b9774 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 7 Feb 2024 14:56:31 +0000 Subject: [PATCH 02/22] update delete to cancel --- src/data/nav.yaml | 2 +- .../docs/cli-command-reference/runs-reset-cancel.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 21dbde37..77d18981 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -115,7 +115,7 @@ path: /docs/cli-command-reference/ecosystem-cli-runs-prepare - title: Running tests in the Ecosystem path: /docs/cli-command-reference/ecosystem-cli-runs-submit - - title: Retrying and deleting tests + - title: Retrying and cancelling tests path: /docs/cli-command-reference/runs-reset-cancel - title: Viewing test run results path: /docs/cli-command-reference/cli-runs-get diff --git a/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md index 9b9d9a24..91c41e26 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md @@ -1,12 +1,12 @@ --- path: "/docs/cli-command-reference/runs-reset-cancel" -title: "Retrying and deleting tests" +title: "Retrying and cancelling tests" --- -Sometimes tests can become stuck in a loop and fail to finish running, for example, due to a lack of available resources, an environmental problem, or a timeout. You can retry a test to run again by using the `runs reset` command. If the test continues to fail to finish running, you can use the `runs cancel` command to delete the test. +Sometimes tests can become stuck in a loop and fail to finish running, for example, due to a lack of available resources, an environmental problem, or a timeout. You can retry a test to run again by using the `runs reset` command. If the test continues to fail to finish running, you can use the `runs cancel` command to cancel the test. -Retrying a test sets the status of the test run in the DSS to `queued` status. Deleting a test deletes all entries in the DSS for that test run. For this reason it is preferable to retry a test rather than delete a test. All information that is stored in the RAS about the test is kept and is not deleted when either the `runs reset` or `runs cancel` command is run. +Retrying a test sets the status of the test run in the DSS to `queued` status. Cancelling a test removes all entries in the DSS for that test run. For this reason it is preferable to retry a test rather than cancel a test. All information that is stored in the RAS about the test is kept and is not removed when either the `runs reset` or `runs cancel` command is run. You can view the full list of options that are available with the `runs reset` and `runs cancel` commands in the @@ -34,13 +34,13 @@ In this example, the test _C1234_ tried to run twice unsuccessfully and complete ## Working with the `runs cancel` command -The following example deletes a test run called _C1234_ by using the following command: +The following example cancels a test run called _C1234_ by using the following command: ``` galasactl runs cancel --name C1234 ``` -All information that is held in the DSS about the test run is deleted. +All information that is held in the DSS about the test run is removed. From 90f2aae6fd79dc77eda7170d841dc6c2f673e5bc Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 7 Feb 2024 16:18:24 +0000 Subject: [PATCH 03/22] add log info --- .../docs/cli-command-reference/runs-reset-cancel.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md index 91c41e26..8182ea0d 100644 --- a/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md +++ b/src/markdown-pages/docs/cli-command-reference/runs-reset-cancel.md @@ -40,7 +40,17 @@ The following example cancels a test run called _C1234_ by using the following c galasactl runs cancel --name C1234 ``` -All information that is held in the DSS about the test run is removed. +All information that is held in the DSS about the test run is removed. A message is returned in the log to say that the test run was lost and results are returned on the terminal in the following example format: + +``` +2024/02/07 13:34:28 Run C1234 was lost - inttests/dev.galasa.inttests/dev.galasa.inttests.core.local.CoreLocalJava11Ubuntu +submitted-time(UTC) name requestor status result test-name + +Total:1 Lost:1 +2024/02/07 13:34:28 GAL1017E: Not all runs passed. 1 failed. +GAL1017E: Not all runs passed. 1 failed. +2024/02/07 13:34:28 Exit code is 2 +``` From 09e00243fe12c734023caad5c38fc55b38300c87 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Mon, 26 Feb 2024 12:24:18 +0000 Subject: [PATCH 04/22] add authentication --- src/data/nav.yaml | 4 ++- .../docs/ecosystem/ecosystem-architecture.md | 2 +- .../ecosystem/ecosystem-authentication.md | 27 ++++++++++++++++ .../docs/ecosystem/ecosystem-cluster-auth.svg | 31 +++++++++++++++++++ .../ecosystem/ecosystem-installing-k8s.md | 2 +- .../docs/first-steps/installing-offline.md | 8 ++--- 6 files changed, 67 insertions(+), 7 deletions(-) create mode 100644 src/markdown-pages/docs/ecosystem/ecosystem-authentication.md create mode 100644 src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 4f7c3b86..9e56f312 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -104,7 +104,9 @@ - title: Ecosystem architecture path: /docs/ecosystem/architecture - title: Installing an Ecosystem using Helm - path: /docs/ecosystem/installing/k8s + path: /docs/ecosystem/ecosystem-installing-k8s + - title: Configuring authentication + path: /docs/ecosystem/ecosystem-authentication - title: Test streams path: /docs/writing-own-tests/test-streams - title: Managing integrated test runs diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index ed6f33a7..3f9139fd 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -22,7 +22,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. *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. | +| **Credentials Store** | The credentials store (CREDs) securely provides the credentials, for example, password, username and personal access token that are required for a test to run in automation. The CREDs is hosted in the etcd server. | | **etcd** | The etcd server is a highly available key-value pair store which hosts the Configuration Property Store (CPS), the Dynamic Status Store (DSS) and the Credentials Store (CREDs). The etcd server stores and maintains a single, consistent source of the truth about the status of the ecosystem at any given point in time. | | **CouchDB** | This database runs inside Docker container or Kubernetes pod and contains the Result Archive Store (RAS). | diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md new file mode 100644 index 00000000..e54bed1e --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md @@ -0,0 +1,27 @@ +--- +path: "/docs/ecosystem/ecosystem-authentication" +title: "Configuring authentication" +--- + +Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem by using the Galasa command line tool (galasactl). Personal access tokens are stored in the `GALASA_TOKEN` property of the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user. + +If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is valid only for that session. + + +## Authentication architecture + +The following diagram shows the architecture for the authentication process: + +![Galasa ecosystem architecture:](ecosystem-cluster-auth.svg) + + +## Configuring a personal access token into Galasa’s CLI tool + +1. Log into the Galasa Web UI and click `Request personal access token`. +1. Enter a token name - this is helpful to distinguish between tokens in the future - and click `Submit request`. +1. From the `Personal access token details` screen that is returned, click the `Copy to clipboard` icon to copy the `GALASA_TOKEN` value. +1. Paste the copied value into your `galasactl.properties` file and save your change. (If you do not have a `galasactl.properties` file in your Galasa home directory, you can create one by running the `galasa local init` command). + +You can now interact with your Galasa Ecosystem by using the Galasa command-line tool. + + diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg new file mode 100644 index 00000000..4d6b21c2 --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md index ccb18a70..e4393573 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md @@ -1,5 +1,5 @@ --- -path: "/docs/ecosystem/installing/k8s" +path: "/docs/ecosystem/ecosystem-installing-k8s" title: "Installing an Ecosystem using Helm" --- diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 2014f721..1fa07738 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -33,14 +33,14 @@ Note: The example uses port `8080` but you can use a different port. docker load -i isolated.tar ``` -The following confirmation message is received: _Loaded image: icr.io/galasadev/galasa-distribution:latest_. +The following confirmation message is received: _Loaded image: icr.io/galasadev/galasa-distribution:main_. 2. Run the container by using the following command: ``` -docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:latest +docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:main ``` -3. Go to `http:\\hostname:8080` to view the running container. +3. Go to `http:\\localhost:8080` to view the running container. You are now ready to install the Galasa plug-in. @@ -53,7 +53,7 @@ You are now ready to install the Galasa plug-in. 1. Click *Add* and then Select *Local* 1. Navigate to the directory into which the zip was extracted, select the Eclipse directory, and click *OK* 1. Check that the `Location` field is populated with the filepath information, for example, `file:///home/username/galasa-isolated-mvp/eclipse/` and press _Enter_. - 1. If you are using the Docker hosting mechanism, populate the `Location` field with the URL to the running container, for example, `http://hostname:8080/eclipse` and press _Enter_. + 1. If you are using the Docker hosting mechanism, populate the `Location` field with the URL to the running container, for example, `http://localhost:8080/eclipse` and press _Enter_. 1. Tick the _Galasa_ box in the main panel, ensuring that _Galasa_ and all of its child elements are ticked and press _Next_. 1. Follow the prompts to download and install the Galasa plug-in. You will be asked to accept the terms of the license agreement and restart Eclipse to complete the installation. You may also be asked to acknowledge and agree that you are installing unsigned content. 1. After Eclipse has restarted, you can verify that the plug-in is now available by observing the presence of a new _Galasa_ option on the main menu between _Run_ and _Window_. If you choose _Run > Run Configurations_ from the main menu, you will also observe three new entries: _Galasa - Gherkin_, _Galasa - Java_ and _Galasa SimBank_ as available options in the left-hand panel of the pop-up window. From 880670f448fc6c53777018c26003f0becc02f846 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 27 Feb 2024 09:42:24 +0000 Subject: [PATCH 05/22] remove eclipse --- src/data/nav.yaml | 20 +- src/markdown-pages/doc_root.md | 12 +- .../docs/first-steps/eclipse-prereqs.md | 43 --- .../first-steps/getting-started-zipped.md | 11 + .../docs/first-steps/getting-started.md | 21 -- .../docs/first-steps/installing-online.md | 116 ------- .../running-simbank-tests-eclipse.md | 33 -- .../setting-up-galasa-project-eclipse.md | 306 ------------------ .../docs/first-steps/simbank.md | 113 ------- 9 files changed, 19 insertions(+), 656 deletions(-) delete mode 100644 src/markdown-pages/docs/first-steps/eclipse-prereqs.md create mode 100644 src/markdown-pages/docs/first-steps/getting-started-zipped.md delete mode 100644 src/markdown-pages/docs/first-steps/getting-started.md delete mode 100644 src/markdown-pages/docs/first-steps/installing-online.md delete mode 100644 src/markdown-pages/docs/first-steps/running-simbank-tests-eclipse.md delete mode 100644 src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md delete mode 100644 src/markdown-pages/docs/first-steps/simbank.md diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 4f7c3b86..9ff64a22 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -55,23 +55,11 @@ path: /docs/cli-command-reference/simbank-cli - title: Running the SimBank tests using the CLI path: /docs/running-simbank-tests-cli - - title: Getting started using Eclipse - path: /docs/getting-started/ - items: - - title: Eclipse prerequisites - path: /docs/getting-started/eclipse-prereqs - - title: Installing the Galasa plug-in - path: /docs/getting-started/installing-online + - title: Getting started using the zipped distribution + path: /docs/getting-started-zipped + items: - title: Installing the Galasa plug-in offline - path: /docs/getting-started/installing-offline - - title: Exploring Galasa SimBank using Eclipse - path: /docs/getting-started/simbank - - title: Creating a project using Eclipse - path: /docs/running-simbank-tests/setting-up-galasa-project-eclipse - - title: Running the SimBank tests using Eclipse - path: /docs/running-simbank-tests-eclipse - - title: Viewing test results locally - path: /docs/running-simbank-tests/viewing-test-results + path: /docs/getting-started/installing-offline - title: Exploring the supplied SimBank tests path: /docs/exploring-simbank-tests items: diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 32d65364..8c5331dc 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -3,21 +3,17 @@ path: "/docs" title: "Installing options" --- -There are a few options available when installing Galasa. Prerequisites vary, depending on the option that is chosen. +There are two 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 in Eclipse, or for sharing with your department (using the Galasa zipped distribution). +You can install Galasa for using in the command-line, or for sharing with your department (using the Galasa zipped distribution). If you do not have access to Maven Central, Eclipse Marketplace, and Docker Hub from your company network, use the Galasa zipped distribution. Otherwise, you can download the binary file for the Galasa CLI from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub. -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. - -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. - -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. +You can then import the configuration into an IDE of your choice. ## Next steps 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 Eclipse, or if you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using Eclipse](/docs/getting-started) documentation. +If you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using the zipped distribution](/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/first-steps/eclipse-prereqs.md b/src/markdown-pages/docs/first-steps/eclipse-prereqs.md deleted file mode 100644 index 655717f6..00000000 --- a/src/markdown-pages/docs/first-steps/eclipse-prereqs.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -path: "/docs/getting-started/eclipse-prereqs" -title: "Eclipse prerequisites" ---- - - -Depending on how you use Galasa, there are several software prerequisites, some or all of which you may have already installed. - -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. - -## Prerequisites - - -| Software | Description | -| :---- | :-------- | -| Eclipse | Required. 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 at the start of this topic. | -| 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. If you are not installing the zipped distribution, you can choose to 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.9.x.| -| Maven | 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. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | -| 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. | -| 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.| - - -## Next steps - -You can download Galasa for using in Eclipse 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). - -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). \ No newline at end of file diff --git a/src/markdown-pages/docs/first-steps/getting-started-zipped.md b/src/markdown-pages/docs/first-steps/getting-started-zipped.md new file mode 100644 index 00000000..831da592 --- /dev/null +++ b/src/markdown-pages/docs/first-steps/getting-started-zipped.md @@ -0,0 +1,11 @@ +--- +path: "/docs/getting-started-zipped" +title: "Getting started using the zipped distribution" +--- + + +You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, follow the instructions in [Installing the Galasa plug-in offline](installing-offline) documentation. + +## Next steps + +You can then start [exploring Galasa Simbank](../cli-command-reference/simbank-cli.md); 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/getting-started.md b/src/markdown-pages/docs/first-steps/getting-started.md deleted file mode 100644 index b384857f..00000000 --- a/src/markdown-pages/docs/first-steps/getting-started.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -path: "/docs/getting-started" -title: "Getting started using Eclipse" ---- - -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. - - -## 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 [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). - -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](/docs/getting-started/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/installing-online.md b/src/markdown-pages/docs/first-steps/installing-online.md deleted file mode 100644 index a9a02ae2..00000000 --- a/src/markdown-pages/docs/first-steps/installing-online.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -path: "/docs/getting-started/installing-online" -title: "Installing the Galasa plug-in" ---- - -The Galasa plug-in is accompanied by Galasa SimBank - a demonstration application - which sits on top of a very small middleware layer called SimPlatform (you may see its name in some console messages, but you will otherwise not need to interact with SimPlatform). - - - -This section describes 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. - - -## Installing the Galasa plug-in - -1. Launch Eclipse. If present, close any initial welcome screen. -1. Choose _Help > Install New Software_ from the main menu. -1. Paste `https://p2.galasa.dev/` into the _Work with_ field and press _Enter_. -1. Tick the _Galasa_ box in the main panel, ensuring that _Galasa_ and all of its child elements are ticked. -1. Follow the prompts to download and install the Galasa plug-in. You will be asked to accept the terms of the license agreement and restart Eclipse to complete the installation. You may also be asked to acknowledge and agree that you are installing unsigned content. -1. After Eclipse has restarted, you can verify that the plug-in is now available by observing the presence of a new _Galasa_ option on the main menu between _Run_ and _Window_. If you choose _Run > Run Configurations_ from the main menu, you will also observe three new entries: _Galasa - Gherkin_, _Galasa - Java_ and _Galasa SimBank_ as available options in the left-hand panel of the pop-up window. - -## Configuring Eclipse for Galasa - - - - -1. Choose _Galasa > Setup Galasa Workspace_ from the main Eclipse menu - this command creates some necessary configuration files. Your Eclipse console confirms its progress with some messages: - - ``` - Setting up the Galasa workspace - Creating the ~/.galasa files - Created the ~/.galasa directory - Created an empty Bootstrap Properties file ~/.galasa/bootstrap.properties - Created an empty Overrides Properties file ~/.galasa/overrides.properties - Created an empty Credentials Properties file ~/.galasa/credentials.properties - Created an empty CPS Properties file ~/.galasa/cps.properties - Created an empty DSS Properties file ~/.galasa/dss.properties - The ~/.m2 directory already exists - Created the ~/.m2/.settings.xml example file - Setup complete - ``` -1. Locate your user home directory and confirm 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 operating system to show hidden files. -1. Edit a file called `overrides.properties` in your `.galasa` folder so that it contains the following configuration properties. Configuration properties held in this file are used by Galasa tests at runtime. You can change the value of the properties that are set in this file to enable you to run tests against different configurations without changing the test code. The following example configuration properties enable the provided Galasa SimBank tests to run on your machine: - - ```properties - zos.dse.tag.SIMBANK.imageid=SIMBANK - zos.dse.tag.SIMBANK.clusterid=SIMBANK - - simbank.dse.instance.name=SIMBANK - simbank.instance.SIMBANK.zos.image=SIMBANK - - zos.image.SIMBANK.ipv4.hostname=127.0.0.1 - zos.image.SIMBANK.telnet.port=2023 - zos.image.SIMBANK.webnet.port=2080 - zos.image.SIMBANK.telnet.tls=false - zos.image.SIMBANK.credentials=SIMBANK - - zosmf.image.SIMBANK.servers=SIMBANK - zosmf.server.SIMBANK.image=SIMBANK - zosmf.server.SIMBANK.port=2040 - zosmf.server.SIMBANK.https=false - ``` -1. Edit a file called `credentials.properties` in your `.galasa` folder. Credentials that are held in this file are used by Galasa tests, for example to pass credentials to the application being tested. Storing values in this file avoids the need to hard-code credentials inside a test class, enabling the test to run in different environments without changing any test code. The following example properties enable the provided Galasa SimBank tests to run on your machine: - - ```properties - secure.credentials.SIMBANK.username=IBMUSER - secure.credentials.SIMBANK.password=SYS1 - ``` - - Note: If you have previously installed Galasa, this file is already populated. - - -Your local Eclipse Galasa installation is now ready for some work. Start by [exploring Galasa Simbank](/docs/getting-started/simbank) to help you to learn about the Galasa basics. diff --git a/src/markdown-pages/docs/first-steps/running-simbank-tests-eclipse.md b/src/markdown-pages/docs/first-steps/running-simbank-tests-eclipse.md deleted file mode 100644 index 149a4c5f..00000000 --- a/src/markdown-pages/docs/first-steps/running-simbank-tests-eclipse.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -path: "/docs/running-simbank-tests-eclipse" -title: "Running the SimBank tests 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`. - -The following section explains how to run the `SimBankIVT` test class by using Eclipse. - - -## Running the SimBank IVT test class using Eclipse - -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_. -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. - - -## Next steps - -Explore the SimBankIVT test and the other SimBank tests in the [Exploring the supplied SimBank tests](exploring-simbank-tests) 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/first-steps/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md deleted file mode 100644 index 39ce3b51..00000000 --- a/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md +++ /dev/null @@ -1,306 +0,0 @@ ---- -path: "/docs/running-simbank-tests/setting-up-galasa-project-eclipse" -title: "Creating a project using Eclipse" ---- - -Galasa SimBank comes with a selection of supplied Galasa 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. - -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. - -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. - - - -## 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](../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](../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](../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/first-steps/simbank.md b/src/markdown-pages/docs/first-steps/simbank.md deleted file mode 100644 index 0117a3b1..00000000 --- a/src/markdown-pages/docs/first-steps/simbank.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -path: "/docs/getting-started/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. - -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 -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. Start Eclipse. -1. From the main menu, choose *Run > Run Configurations*. -1. In the *Create, manage and run configurations* dialog, right-click *Galasa SimBank* in the left pane and choose *New Configuration*. -1. Type your preferred name for the run configuration in the *Name:* field (a relevant name such as *SimBank* is fine), press *Apply* and then *Run*. Once created, your run configuration is available for future runs. -In a few seconds, the Eclipse *Console* 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. - -5. 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 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](../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](../first-steps/simbank-userid.png) - -1. Enter the userid `IBMUSER` - - ![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) - -> *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](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) - -As you have been progressing through this process, Eclipse has been logging selected events to its console: - -``` -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](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](simbank-transfer.png) - -1. Press ENTER - a `Transfer Successful` message appears. A log message is also written to the Eclipse *Console* 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 From 1a0ccbb3f4c2e9e360d13c43c3e3007947444f9d Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 27 Feb 2024 11:54:50 +0000 Subject: [PATCH 06/22] add blog and update auth --- .../docs/ecosystem/ecosystem-authentication.md | 15 +++++---------- src/markdown-pages/docs/galasa-hub.md | 8 ++++++++ 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md index e54bed1e..bdfc4c38 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md @@ -3,25 +3,20 @@ path: "/docs/ecosystem/ecosystem-authentication" title: "Configuring authentication" --- -Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem by using the Galasa command line tool (galasactl). Personal access tokens are stored in the `GALASA_TOKEN` property of the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user. - -If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is valid only for that session. +Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem by using the Galasa command line tool (galasactl). +Personal access tokens are stored in the `GALASA_TOKEN` property in the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user. ## Authentication architecture +If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is valid only for that session. + The following diagram shows the architecture for the authentication process: ![Galasa ecosystem architecture:](ecosystem-cluster-auth.svg) -## Configuring a personal access token into Galasa’s CLI tool - -1. Log into the Galasa Web UI and click `Request personal access token`. -1. Enter a token name - this is helpful to distinguish between tokens in the future - and click `Submit request`. -1. From the `Personal access token details` screen that is returned, click the `Copy to clipboard` icon to copy the `GALASA_TOKEN` value. -1. Paste the copied value into your `galasactl.properties` file and save your change. (If you do not have a `galasactl.properties` file in your Galasa home directory, you can create one by running the `galasa local init` command). +When a user logs into the Galasa Web UI via their browser, the Web UI contacts the authorization REST endpoint which in turn talks to a Dex server, providing it with the user ID. The Dex server acts as authentication concentrator, talking to an identity provider, for example, GitHub or LDAP to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to interact with a Galasa Ecosystem. -You can now interact with your Galasa Ecosystem by using the Galasa command-line tool. diff --git a/src/markdown-pages/docs/galasa-hub.md b/src/markdown-pages/docs/galasa-hub.md index 3fde1628..ce9fac4d 100644 --- a/src/markdown-pages/docs/galasa-hub.md +++ b/src/markdown-pages/docs/galasa-hub.md @@ -5,6 +5,14 @@ title: "Galasa Blogs" Stay up-to-date with all things Galasa with blogs, podcasts and videos from fellow Galasians. +## Blog: Galasa: What is Application Integration Testing? +Application integration allows software to be created as a unique and bespoke set of applications that knit together to form critical business processes. Application integration testing ensures that individual components interact with each other in a desirable way, and automation of this stage of testing is critical because there typically are so many configurations, routes, and scenarios to consider. Galasa could be your first step to understanding how to build test cases that cover multiple applications and can even be extended to cover proprietary applications with the use of Managers. Read the blog post by Louisa Seers to find out more.
+ +**Author: Louisa Seers, February 12 2024**
+*Source: Open Mainframe Project*

+ + Read the blog + ## Blog: Galasa: My First 6 Months as a TSC Chair Read the blog post by Louisa Seers to find out about her experiences and thoughts during her first six months as Galasa IBM Product Manager and Chair of the Galasa Technical Steering Committee (TSC), and the Galasa journey to adoption by the Open Mainframe Project (OMP).
From 70becb524698ef70db0fe0be3d66cf4227a175b8 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 27 Feb 2024 13:14:38 +0000 Subject: [PATCH 07/22] update blog and auth --- src/markdown-pages/docs/ecosystem/ecosystem-authentication.md | 2 +- src/markdown-pages/docs/galasa-hub.md | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md index bdfc4c38..674e85c5 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md @@ -16,7 +16,7 @@ The following diagram shows the architecture for the authentication process: ![Galasa ecosystem architecture:](ecosystem-cluster-auth.svg) -When a user logs into the Galasa Web UI via their browser, the Web UI contacts the authorization REST endpoint which in turn talks to a Dex server, providing it with the user ID. The Dex server acts as authentication concentrator, talking to an identity provider, for example, GitHub or LDAP to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to interact with a Galasa Ecosystem. +When a user logs into the Galasa Web UI via their browser, the Web UI contacts the authorization REST endpoint which in turn talks to a Dex server, providing it with the user ID. The Dex server acts as authentication concentrator, talking to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to interact with a Galasa Ecosystem. diff --git a/src/markdown-pages/docs/galasa-hub.md b/src/markdown-pages/docs/galasa-hub.md index ce9fac4d..13431d67 100644 --- a/src/markdown-pages/docs/galasa-hub.md +++ b/src/markdown-pages/docs/galasa-hub.md @@ -5,6 +5,9 @@ title: "Galasa Blogs" Stay up-to-date with all things Galasa with blogs, podcasts and videos from fellow Galasians. +Galasa blogs that are hosted by the Open Mainframe Project are available on the +Galasa page of the website. + ## Blog: Galasa: What is Application Integration Testing? Application integration allows software to be created as a unique and bespoke set of applications that knit together to form critical business processes. Application integration testing ensures that individual components interact with each other in a desirable way, and automation of this stage of testing is critical because there typically are so many configurations, routes, and scenarios to consider. Galasa could be your first step to understanding how to build test cases that cover multiple applications and can even be extended to cover proprietary applications with the use of Managers. Read the blog post by Louisa Seers to find out more.
From 423ab0b15babf1cd4df736444d3735cf338775a3 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 28 Feb 2024 11:14:14 +0000 Subject: [PATCH 08/22] updates to eclipse removal --- src/data/nav.yaml | 4 ++- src/markdown-pages/doc_root.md | 10 ++++---- .../docs/cli-command-reference/cli-prereqs.md | 1 - .../docs/ecosystem/ecosystem-architecture.md | 2 +- .../docs/ecosystem/ecosystem-installing.md | 3 +-- .../docs/ecosystem/ecosystem-manage-cps.md | 2 +- .../first-steps/getting-started-zipped.md | 4 +-- .../docs/first-steps/installing-offline.md | 6 ++--- .../docs/first-steps/zipped-prerequisites.md | 25 +++++++++++++++++++ .../docs/managers/zos3270terminal-manager.md | 2 +- .../batch-accounts-open-test.md | 2 +- .../writing-a-simbank-test.md | 8 +++--- src/markdown-pages/docs/writing-own-tests.md | 2 +- .../writing-own-tests/running-test-modes.md | 4 +-- .../docs/writing-own-tests/test-streams.md | 2 +- 15 files changed, 50 insertions(+), 27 deletions(-) create mode 100644 src/markdown-pages/docs/first-steps/zipped-prerequisites.md diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 9ff64a22..e78c46be 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -56,8 +56,10 @@ - title: Running the SimBank tests using the CLI path: /docs/running-simbank-tests-cli - title: Getting started using the zipped distribution - path: /docs/getting-started-zipped + path: /docs/getting-started/getting-started-zipped items: + - title: Zipped distribution prerequisites + path: /docs/getting-started/zipped-prerequisites - title: Installing the Galasa plug-in offline path: /docs/getting-started/installing-offline - title: Exploring the supplied SimBank tests diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 8c5331dc..0569dcdf 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -3,17 +3,17 @@ path: "/docs" title: "Installing options" --- -There are two options available when installing Galasa. Prerequisites vary, depending on the option that is chosen. +There are two options available when downloading Galasa. Prerequisites vary, depending on the option that is chosen. -You can install Galasa for using in the command-line, or for sharing with your department (using the Galasa zipped distribution). If you do not have access to Maven Central, Eclipse Marketplace, and Docker Hub from your company network, use the Galasa zipped distribution. Otherwise, you can download the binary file for the Galasa CLI from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub. +You can download Galasa from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub, or you can download the Galasa zipped distribution for sharing with your department. If you do not have access to Maven Central or Docker Hub from your company network, use the Galasa zipped distribution. Otherwise, download the binary file for the Galasa CLI from GitHub. -You can then import the configuration into an IDE of your choice. +You downloaded and installed Galasa, you can import the configuration into an IDE of your choice. ## Next steps -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 from GitHub, follow the instructions in the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation. -If you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using the zipped distribution](/docs/getting-started) documentation. +If you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using the zipped distribution](/docs/getting-started/getting-started-zipped) 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/cli-command-reference/cli-prereqs.md b/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md index e047aa05..bf00b117 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md @@ -6,7 +6,6 @@ title: "CLI prerequisites" The following section explains more about the software prerequisites that you need to install so that you are ready to install Galasa for using in the command-line. - ## Prerequisites | Software | Description | diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md index ed6f33a7..5f297d8f 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-architecture.md @@ -39,7 +39,7 @@ The following diagram highlights a some of the key components that make up the G | **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. | +| **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 IDE must be updated to point to the bootstrap that is configured to use the ecosystem. | | **Galasa Web UI** | The Galasa Web UI 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. | | **Dex** | The Galasa Ecosystem Helm chart's use of Dex is under development and is subject to change. In a future release, Dex will be used to authenticate users interacting with a Galasa Ecosystem. | diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md index d6cfd564..f1c01251 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md @@ -81,7 +81,7 @@ The Galasa Ecosystem is now successfully installed on the VM. ### 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 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: @@ -94,7 +94,6 @@ In Eclipse, you can edit the bootstrap by completing the following steps: You can verify the ecosystem installation by using the Galasa command line interface (Galasa CLI) to run the _runs prepare_ and _runs submit_ commands. To find out more about the Galasa CLI, see [Using the Galasa CLI](/docs/cli-command-reference/cli-command-reference). -Alternatively, you can submit automation tests from within Eclipse; select the *Galasa > Submit tests to automation* option from the Eclipse menu to choose the runs that you want to submit. ## Next steps diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md index 0344982a..7fcd445f 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md @@ -17,7 +17,7 @@ A video - https://resources.galasa.dev/ site and can be downloaded and extracted to a directory of your choice. The zip file contains four directories (galasactl, eclipse, maven, and javadoc), an `isolated.tar` file and a `docs.jar` file. +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 (galasactl, maven, and javadoc), an `isolated.tar` file and a `docs.jar` file. -The `galasactl` directory contains the binaries that are required to run the Galasa command line interface tool (Galasa CLI). 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 `galasactl` directory contains the binaries that are required to run the Galasa command line interface tool (Galasa CLI). 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. @@ -17,7 +17,7 @@ The Galasa plug-in is accompanied by Galasa SimBank - a demonstration applicatio -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. +This section describes using the Galasa command line tool (galasactl) 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. ## Unpacking the zip file diff --git a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md new file mode 100644 index 00000000..d88b96c6 --- /dev/null +++ b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md @@ -0,0 +1,25 @@ +--- +path: "/docs/getting-started/zipped-prerequisites" +title: "Zipped distribution prerequisites" +--- + + +The following section explains more about the software prerequisites that you need to install so that you are ready to install the zipped distribution for Galasa. + + +## 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. | +| Gradle | Required to install the zipped distribution. You can also build Galasa projects using Gradle. (You can build projects using Maven 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.9.x.| +| Maven | 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. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | +| 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. | +| 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.| + + + +## Next steps + +Install the Galasa plug-in using the zipped distribution by following the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). \ No newline at end of file diff --git a/src/markdown-pages/docs/managers/zos3270terminal-manager.md b/src/markdown-pages/docs/managers/zos3270terminal-manager.md index 9a00df70..b5ab16b4 100644 --- a/src/markdown-pages/docs/managers/zos3270terminal-manager.md +++ b/src/markdown-pages/docs/managers/zos3270terminal-manager.md @@ -22,7 +22,7 @@ The ConfidentialTextFiltering service enables confidential informat Examples of using colour support and screen sizing are available in the [Code snippets and examples](#codesnippets) section. -When running a Galasa test with Eclipse or the Galasa CLI, terminal images are logged to the run log and PNG representations of the terminal screens can also be saved to the Result Archive Store (RAS) as the outputs are now controlled by the `zos3270.terminal.output` CPS property. In Eclipse, live terminal updates are displayed to enable swift diagnosis of failures. +When running a Galasa test with the Galasa CLI, terminal images are logged to the run log and PNG representations of the terminal screens can also be saved to the Result Archive Store (RAS) as the outputs are now controlled by the `zos3270.terminal.output` CPS property. *Note:* The feature for saving PNG representations of the terminal screens to the RAS is available in the current release as experimental code only. diff --git a/src/markdown-pages/docs/running-simbank-tests/batch-accounts-open-test.md b/src/markdown-pages/docs/running-simbank-tests/batch-accounts-open-test.md index bdf7f0d8..d9240ee5 100644 --- a/src/markdown-pages/docs/running-simbank-tests/batch-accounts-open-test.md +++ b/src/markdown-pages/docs/running-simbank-tests/batch-accounts-open-test.md @@ -31,7 +31,7 @@ For brevity, package declarations and imports are omitted in the following walkt First, some Managers are declared, including a new Manager - `ZosBatch` and a related annotation and interface `ZosBatchJobname`. ```java -@ZosBatch(imageTag = "SIMBANK"") +@ZosBatch(imageTag = "SIMBANK") public IZosBatch zosBatch; @ZosBatchJobname(imageTag = "SIMBANK") diff --git a/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md b/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md index ce69dd6e..24995eb3 100644 --- a/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md +++ b/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md @@ -11,12 +11,10 @@ Don't forget that whenever you create a test, or modify an existing one, you nee ## Create a new Galasa test class -1. Launch SimBank, either using [Eclipse](/docs/getting-started/simbank) or the [CLI](../cli-command-reference/simbank-cli). -1. Create a new test class. If you are using the CLI, manually create the test class file, for example in VS Code. If you are using Eclipse you can do this by selecting *File > New > Class* (or if this option is not present, select *File > New > Other*, and choose *Class* in the dialog). Complete the next dialog as follows and then click *Finish*. Note that in the example a new package is created that is called `dev.galasa.simbanks.tests`. ![New Java Class](./create-new-class.png) +1. Launch SimBank, either using the [CLI](../cli-command-reference/simbank-cli). +1. Create a new test class. If you are using the CLI, manually create the test class file, for example in VS Code. Complete the next dialog as follows and then click *Finish*. Note that in the example a new package is created that is called `dev.galasa.simbanks.tests`. ![New Java Class](./create-new-class.png) 1. Annotate the new class with the `@Test` annotation. -If you are using Eclipse you can click on the error indication for `@Test` and then double-click on `Import '@Test' (dev.galasa)` to create the correct import: -![Fix @Test import](./fix-import.png) -You can use a similar technique later on when you need to resolve exceptions in the `throws` clause of the `transferCredit()` method. +
Stage 1 - code so far diff --git a/src/markdown-pages/docs/writing-own-tests.md b/src/markdown-pages/docs/writing-own-tests.md index 28724cd3..93ab9e7f 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) (or Eclipse) to create an appropriate project structure. +- Using the [Galasa command line interface](/docs/cli-command-reference/cli-command-reference) 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/running-test-modes.md b/src/markdown-pages/docs/writing-own-tests/running-test-modes.md index fc229d13..77abc593 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 @@ -30,7 +30,7 @@ When you run a test locally, without using shared configuration, everything runs ![running in local mode:](running-local.svg) -You can run a test in this mode by using the `runs submit local` Galasa CLI command, or by using the Eclipse plugin, in which case the test is hosted within the Eclipse JVM. +You can run a test in this mode by using the `runs submit local` Galasa CLI command. ## Running a test in the Galasa Ecosystem @@ -49,7 +49,7 @@ When you run a test locally, but using shared configuration, the Galasa bootstra ![running in local mode with shared configuration:](hybridrunmode.svg) -You can run a test in this mode by setting up your bootstrap to refer to the ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. Alternatively, you can use the Eclipse plugin, in which case the test is hosted within the Eclipse JVM. +You can run a test in this mode by setting up your bootstrap to refer to the ecosystem in which the shared configuration is stored, and using the `runs submit local` Galasa CLI command. ### When to run a test in the Galasa Ecosystem diff --git a/src/markdown-pages/docs/writing-own-tests/test-streams.md b/src/markdown-pages/docs/writing-own-tests/test-streams.md index 8d8e64f4..d56f480f 100644 --- a/src/markdown-pages/docs/writing-own-tests/test-streams.md +++ b/src/markdown-pages/docs/writing-own-tests/test-streams.md @@ -7,7 +7,7 @@ Galasa's ecosystem organises tests into _streams_. Test streams give you more op You can have as few or as many test streams as you wish. -A stream is a group of tests that you wish to run in automation represented by a single OBR (OSGi Bundle Repository) and its equivalent test catalog. Galasa uses an OBR to locate your tests in a Maven repository, along with all of the Managers that a test project requires. A test catalog is generated directly from the test source, is always up to date, and is what you would use in Eclipse or specify in the [Galasa CLI](/docs/cli-command-reference/cli-command-reference) to select tests to run in automation. +A stream is a group of tests that you wish to run in automation represented by a single OBR (OSGi Bundle Repository) and its equivalent test catalog. Galasa uses an OBR to locate your tests in a Maven repository, along with all of the Managers that a test project requires. A test catalog is generated directly from the test source, is always up to date, and is what you would specify in the [Galasa CLI](/docs/cli-command-reference/cli-command-reference) to select tests to run in automation. There are many ways to organise test streams: From a12fbd3d4d5a121c93bfc86cdd6b6ab140a7cd50 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 28 Feb 2024 14:39:38 +0000 Subject: [PATCH 09/22] add gherkin info --- .../runs-submit-local.md | 46 +++++++++++++++++-- .../docs/managers/core-manager.md | 5 +- .../docs/managers/zos3270terminal-manager.md | 2 + .../setting-up-galasa-project.md | 2 +- 4 files changed, 46 insertions(+), 9 deletions(-) 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 e5b49f71..4e05ee3c 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,8 +3,11 @@ path: "/docs/cli-command-reference/cli-runs-submit-local" title: "Running tests locally using the command line" --- + 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. +You can submit [Java tests](#Java) and [Gherkin tests](#Gherkin) by using the command but must to specify different flags on the command line for each test type. Read on to find out more about how to submit each type of test on your local machine. + 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. @@ -15,8 +18,12 @@ To use the `galasactl runs submit local` command, the `JAVA_HOME` environment va 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. +You can view the full list of options that are available with the `galasactl runs submit local` command in the +Galasa cli repository. + +## Running a Java test with the `runs submit local` command -Use the following command to run a test in the local JVM. +Use the following command to run a Java test in the local JVM. On Mac or Unix: @@ -40,14 +47,45 @@ 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 `galasactl runs submit local` command in the -Galasa cli repository. + +## Running a Gherkin test with the `runs submit local` command + +Use the following command to run a Gherkin test in the local JVM. Note that the `--gherkin` flag is specified and that the `--obr` or `--class` flags are not required. + +On Mac or Unix: + +``` +galasactl runs submit local --log - \ +--gherkin file:///path/to/gherkin/file.feature +``` + + +On Windows (Powershell): + +``` +galasactl runs submit local --log - ` +--gherkin file:///path/to/gherkin/file.feature +``` + +where: + +- `--log` specifies that debugging information is directed somewhere, and the `-` means that it is sent to the console (stderr). +- `--gherkin` specifies the path where the CLI tool can find the Gherkin file containing the Gherkin tests. The path must be specified in a URL form, ending in a `.feature` extension. For example,`file:///Users/myuserid/gherkin/MyGherkinFile.feature` or `file:///C:/Users/myuserid/gherkin/MyGherkinFile.feature`. + + +Examples of Galasa Managers in GitHub that have Gherkin support currently available are the +Core Manager, and the +zos3270Terminal Manager. For more information about these Managers, see the [Manager](../managers) documentation section. + + + +For more information about Gherkin, see the Cucumber website. ## Overriding the path to the default local Maven repository In order to run, tests require compiled artifacts to be hosted in a Maven repository. The artifacts must be bundled as an OSGI bundle. When you build a Galasa project locally, the built artifacts are placed by default in the `~/.m2/` repository in your home directory; the default location of the local Maven repository. -If you want to use a non-standard location for your local Maven repository when running a test locally, rather than the default `~/.m2/` repository, you can specify the path to your non-standard local Maven repository folder when launching a test by setting the `--localMaven` flag on the `galasactl runs submit local` command. The `--localMaven` parameter tells the CLI tool where Galasa bundles can be loaded from on your local file system. The parameter value must be given in a URL form, for example, `file:///Users/myuserid/mylocalrepository` or `file://C:/Users/myuserid/mylocalrepository`. +If you want to use a non-standard location for your local Maven repository when running a test locally, rather than the default `~/.m2/` repository, you can specify the path to your non-standard local Maven repository folder when launching a test by setting the `--localMaven` flag on the `galasactl runs submit local` command. The `--localMaven` parameter tells the CLI tool where Galasa bundles can be loaded from on your local file system. The parameter value must be given in a URL form, for example, `file:///Users/myuserid/mylocalrepository` or `file:///C:/Users/myuserid/mylocalrepository`. *Note:* the repository that is referenced by the `--localMaven` flag must contain the test, Manager, and Galasa framework OBRs (OSGi Bundle Repositories) that the test needs in order to run. Galasa uses OBRs to locate tests in the specified Maven repository, along with all of the Managers that the test requires. diff --git a/src/markdown-pages/docs/managers/core-manager.md b/src/markdown-pages/docs/managers/core-manager.md index 2477f222..01321a0c 100644 --- a/src/markdown-pages/docs/managers/core-manager.md +++ b/src/markdown-pages/docs/managers/core-manager.md @@ -14,10 +14,7 @@ This Manager is at Release level. You can view the Overview -The Core Manager provides tests with access to some of the core features within the Galasa Framework. The Core Manager is always initialised and included in a test run and contributes the Logger, StoredArtifactRoot, ResourceString, RunName and TestProperty annotations.

The Logger annotation is provided by the Core Manager to create the log which is then automatically stored in the Result Archive Store (RAS) by the Galasa framework.

The StoredArtifactRoot annotation lets your test write specific output to the RAS. Whilst the Galasa framework automatically sends test output to be stored in the RAS, this annotation enables you to write code to send output specific to your application to be stored. You can use this output for review or to enable compares to be done when tests fail.

The Core Manager uses methods including getCredentials, getUsernamePassword, getRunName and ConfidentialText credentials. getCredentials lets you retrieve a user id and password from a file to use in your test as well as other forms of credentials such as tokens, whilst getUsernamePassword lets you retrieve a user id and password only from a file to use in your test and ConfidentialText ensures that the password value is masked. The ability to get credentials from a file means that you do not need to hard code these values in your test and that the test can be run in different environments without the need to change a single line of code.

. - - -You can view the Javadoc documentation for this Manager here.

+The Core Manager provides tests with access to some of the core features within the Galasa Framework. The Core Manager is always initialised and included in a test run and contributes the Logger, StoredArtifactRoot, ResourceString, RunName and TestProperty annotations.

The Logger annotation is provided by the Core Manager to create the log which is then automatically stored in the Result Archive Store (RAS) by the Galasa framework.

The StoredArtifactRoot annotation lets your test write specific output to the RAS. Whilst the Galasa framework automatically sends test output to be stored in the RAS, this annotation enables you to write code to send output specific to your application to be stored. You can use this output for review or to enable compares to be done when tests fail.

The Core Manager uses methods including getCredentials, getUsernamePassword, getRunName and ConfidentialText credentials. getCredentials lets you retrieve a user id and password from a file to use in your test as well as other forms of credentials such as tokens, whilst getUsernamePassword lets you retrieve a user id and password only from a file to use in your test and ConfidentialText ensures that the password value is masked. The ability to get credentials from a file means that you do not need to hard code these values in your test and that the test can be run in different environments without the need to change a single line of code. The Core Manager supports Gherkin keywords.

## Including the Manager in a test diff --git a/src/markdown-pages/docs/managers/zos3270terminal-manager.md b/src/markdown-pages/docs/managers/zos3270terminal-manager.md index 9a00df70..12e6e713 100644 --- a/src/markdown-pages/docs/managers/zos3270terminal-manager.md +++ b/src/markdown-pages/docs/managers/zos3270terminal-manager.md @@ -24,6 +24,8 @@ Examples of using colour support and screen sizing are available in the [Code sn When running a Galasa test with Eclipse or the Galasa CLI, terminal images are logged to the run log and PNG representations of the terminal screens can also be saved to the Result Archive Store (RAS) as the outputs are now controlled by the `zos3270.terminal.output` CPS property. In Eclipse, live terminal updates are displayed to enable swift diagnosis of failures. +The zos3270Terminal Manager supports Gherkin keywords. + *Note:* The feature for saving PNG representations of the terminal screens to the RAS is available in the current release as experimental code only. 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 9870dbe1..0b5d7827 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 @@ -8,7 +8,7 @@ You can quickly and easily create a project structure to accommodate your own in Use the following information 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. -Once you have created and built your Galasa tests, you can run the tests in your local environment. Find out more in the [Running a test locally](../cli-command-reference/cli-runs-submit-local) topic. +Once you have created and built your Galasa tests, you can run the tests in your local environment. You can run Galasa tests that are written in Java and Galasa tests that are written in Gherkin in your local environment. Find out more in the [Running a test locally](../cli-command-reference/cli-runs-submit-local) topic. ## Getting started From 0132f68dcf18a01569d940eb9f4e0798eee0a0df Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 29 Feb 2024 15:52:09 +0000 Subject: [PATCH 10/22] review updates --- .../ecosystem/ecosystem-authentication.md | 19 +++++++++--- .../ecosystem/ecosystem-cluster-auth-old.svg | 31 +++++++++++++++++++ .../docs/ecosystem/ecosystem-cluster-auth.svg | 10 +++--- 3 files changed, 51 insertions(+), 9 deletions(-) create mode 100644 src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth-old.svg diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md index 674e85c5..e3db23bb 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-authentication.md @@ -3,20 +3,31 @@ path: "/docs/ecosystem/ecosystem-authentication" title: "Configuring authentication" --- -Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem by using the Galasa command line tool (galasactl). +Before interacting with a Galasa Ecosystem using the Galasa command line tool (galasactl), you must be authenticated with it. Galasa uses personal access tokens to authenticate users who want to interact with a Galasa Ecosystem provided by the `GALASA_BOOTSTRAP` environment variable or through the `--bootstrap` flag. + Personal access tokens are stored in the `GALASA_TOKEN` property in the `galasactl.properties` file in your Galasa home folder. The `galasactl.properties` file is created when you run the `galasa local init` command. Setting the `GALASA_TOKEN` property in this file with a valid token value allows the galasactl tool to access and communicate with an Ecosystem on behalf of the user. -## Authentication architecture -If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is valid only for that session. +If you have [installed your Galasa Ecosystem](../ecosystem/ecosystem-installing-k8s) by using the Galasa Ecosystem Helm chart that is provided with Galasa, you will have access to the Galasa Web UI. To get a value for the `GALASA_TOKEN` property, log into the Galasa Web UI and request a personal access token which can be copied into the `GALASA_TOKEN` property. The instructions on how to do this are displayed in a dialog box in the Galasa Web UI. You can choose to set the token as an environmental variable but the value would not persist across terminals, so is only valid for that session. + +## Authentication architecture The following diagram shows the architecture for the authentication process: ![Galasa ecosystem architecture:](ecosystem-cluster-auth.svg) -When a user logs into the Galasa Web UI via their browser, the Web UI contacts the authorization REST endpoint which in turn talks to a Dex server, providing it with the user ID. The Dex server acts as authentication concentrator, talking to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to interact with a Galasa Ecosystem. +When a user logs into the Galasa Web UI via their browser, the Web UI contacts the Galasa API server which in turn talks to a Dex server, providing it with the user ID. The Dex server talks to an identity provider, for example GitHub or LDAP, to authenticate that user. If the user is successfully authenticated, the provider returns an access token to the Dex server which sends that token to Galasa API server. The token is then sent to the Galasa Web UI where it is visible to the user. The user can then configure that token into the galasactl command line tool by updating the `GALASA_TOKEN` property in the `galasactl.properties` file. The user can then be authenticated each time the galasactl tool is used to log into a Galasa Ecosystem. + +On a successful login, a `bearer-token.json` file is created in the Galasa home directory. This file contains a bearer token that galasactl uses to authenticate requests when communicating with a Galasa Ecosystem. If the bearer token expires, galasactl automatically attempts to re-authenticate with the Galasa Ecosystem using the properties in the `galasactl.properties` file within the Galasa home directory. + +### Logging in to a Galasa Ecosystem using the auth login command + +You can log in to a Galasa Ecosystem explicitly by using the `galasactl auth login` command. You might want to do an explicit log in if you are running galasactl as part of a build pipeline, or if you just want to make sure you can log in. + +### Logging out of a Galasa Ecosystem using the auth logout command +To log out of a Galasa Ecosystem using galasactl, you can use the `galasactl auth logout` command. If you run a galasactl command that interacts with an Ecosystem while logged out, galasactl will attempt to automatically log in using the properties in your `galasactl.properties` file within your Galasa home directory. diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth-old.svg b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth-old.svg new file mode 100644 index 00000000..4d6b21c2 --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth-old.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg index 4d6b21c2..55e0abff 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg +++ b/src/markdown-pages/docs/ecosystem/ecosystem-cluster-auth.svg @@ -3,10 +3,10 @@ - - - - + + + + @@ -27,5 +27,5 @@ - + From 792c8785ef3b433f515542be024bca943c5c13f1 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Mon, 4 Mar 2024 13:52:51 +0000 Subject: [PATCH 11/22] minor update --- .../docs/cli-command-reference/runs-submit-local.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 4e05ee3c..56049bfa 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 @@ -6,7 +6,7 @@ title: "Running tests locally using the command line" 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. -You can submit [Java tests](#Java) and [Gherkin tests](#Gherkin) by using the command but must to specify different flags on the command line for each test type. Read on to find out more about how to submit each type of test on your local machine. +You can submit a [Java test](#Java) and a [Gherkin test](#Gherkin) by using the command but must to specify different flags on the command line for each test type. Read on to find out more about how to submit each type of test on your local machine. 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. From aef86a2e1ee6f546969846defe97d1482ec57e42 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 5 Mar 2024 14:39:35 +0000 Subject: [PATCH 12/22] fix links and edit nav --- src/data/nav.yaml | 6 +++--- .../docs/first-steps/getting-started-zipped.md | 2 +- src/markdown-pages/docs/first-steps/installing-offline.md | 2 +- src/markdown-pages/highlights.md | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/data/nav.yaml b/src/data/nav.yaml index e78c46be..7630970b 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -43,7 +43,7 @@ path: /docs/cli-command-reference/cli-command-reference-about - title: Initialising your local environment path: /docs/initialising-home-folder - - title: Creating a project using the CLI + - title: Creating a Galasa project path: /docs/writing-own-tests/setting-up-galasa-project - title: Running a test locally path: /docs/cli-command-reference/cli-runs-submit-local @@ -51,9 +51,9 @@ path: /docs/cli-command-reference/cli-runs-local-debug - title: Viewing test results locally path: /docs/cli-command-reference/viewing-test-results-cli - - title: Exploring Galasa SimBank using the CLI + - title: Exploring Galasa SimBank path: /docs/cli-command-reference/simbank-cli - - title: Running the SimBank tests using the CLI + - title: Running the SimBank tests path: /docs/running-simbank-tests-cli - title: Getting started using the zipped distribution path: /docs/getting-started/getting-started-zipped diff --git a/src/markdown-pages/docs/first-steps/getting-started-zipped.md b/src/markdown-pages/docs/first-steps/getting-started-zipped.md index ce16119e..6ef22863 100644 --- a/src/markdown-pages/docs/first-steps/getting-started-zipped.md +++ b/src/markdown-pages/docs/first-steps/getting-started-zipped.md @@ -4,7 +4,7 @@ title: "Getting started using the zipped distribution" --- -You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, check you have installed the [pre-requisite software](zipped-prequisites) that you need to start using Galasa. Yout can then follow the instructions in [Installing the Galasa plug-in offline](installing-offline) documentation. +You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, check you have installed the [pre-requisite software](../first-steps/zipped-prerequisites) that you need to start using Galasa. Yout can then follow the instructions in [Installing the Galasa plug-in offline](installing-offline) documentation. ## Next steps diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 5e28c51f..b5d3118c 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -151,4 +151,4 @@ dss.properties 1. Change the _Remote Maven URI_ to the local maven directory, for example, `file:///home/username/galasa-isolated-mvp/maven` 1. Click _Apply and Close_. --> -Your local Eclipse Galasa installation is now ready for some work. Start by [exploring Galasa Simbank](/docs/getting-started/simbank) to help you to learn about the Galasa basics. +Your local Eclipse Galasa installation is now ready for some work. Start by [exploring Galasa Simbank](../cli-command-reference/simbank-cli) to help you to learn about the Galasa basics. diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index b53719e1..127b04b4 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -5,7 +5,7 @@ title: "Highlights" # Galasa Delivery -Galasa is an open source project and is delivered using a continuous delivery model. There are instructions on [getting started](/docs/getting-started) on this site. +Galasa is an open source project and is delivered using a continuous delivery model. There are instructions on [getting started](/src/markdown-pages/docs/cli-command-reference/cli-command-reference) on this site. Post a question or share your experiences with other users in our Galasa Slack workspace. Register to join first if you're not yet a member. From 5af3971d972a8d104c1f176436c0e46e5f305098 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 5 Mar 2024 15:01:27 +0000 Subject: [PATCH 13/22] update link --- src/data/nav.yaml | 6 +++--- .../docs/first-steps/getting-started-zipped.md | 4 ++-- src/markdown-pages/docs/first-steps/installing-offline.md | 2 +- .../docs/first-steps/zipped-prerequisites.md | 2 +- src/markdown-pages/docs/galasa-hub.md | 8 -------- src/markdown-pages/highlights.md | 2 +- 6 files changed, 8 insertions(+), 16 deletions(-) diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 7630970b..2c896772 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -56,12 +56,12 @@ - title: Running the SimBank tests path: /docs/running-simbank-tests-cli - title: Getting started using the zipped distribution - path: /docs/getting-started/getting-started-zipped + path: /docs/first-steps/getting-started-zipped items: - title: Zipped distribution prerequisites - path: /docs/getting-started/zipped-prerequisites + path: /docs/first-steps/zipped-prerequisites - title: Installing the Galasa plug-in offline - path: /docs/getting-started/installing-offline + path: /docs/first-steps/installing-offline - title: Exploring the supplied SimBank tests path: /docs/exploring-simbank-tests items: diff --git a/src/markdown-pages/docs/first-steps/getting-started-zipped.md b/src/markdown-pages/docs/first-steps/getting-started-zipped.md index 6ef22863..5e733814 100644 --- a/src/markdown-pages/docs/first-steps/getting-started-zipped.md +++ b/src/markdown-pages/docs/first-steps/getting-started-zipped.md @@ -1,10 +1,10 @@ --- -path: "/docs/getting-started/getting-started-zipped" +path: "/docs/first-steps/getting-started-zipped" title: "Getting started using the zipped distribution" --- -You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, check you have installed the [pre-requisite software](../first-steps/zipped-prerequisites) that you need to start using Galasa. Yout can then follow the instructions in [Installing the Galasa plug-in offline](installing-offline) documentation. +You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, check you have installed the [pre-requisite software](../first-steps/zipped-prerequisites) that you need to start using Galasa. Yout can then follow the instructions in [Installing the Galasa plug-in offline](../first-steps/installing-offline) documentation. ## Next steps diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index b5d3118c..b8b0253d 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -1,5 +1,5 @@ --- -path: "/docs/getting-started/installing-offline" +path: "/docs/first-steps/installing-offline" title: "Installing the Galasa plug-in offline" --- diff --git a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md index d88b96c6..d1a98618 100644 --- a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md +++ b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md @@ -1,5 +1,5 @@ --- -path: "/docs/getting-started/zipped-prerequisites" +path: "/docs/first-steps/zipped-prerequisites" title: "Zipped distribution prerequisites" --- diff --git a/src/markdown-pages/docs/galasa-hub.md b/src/markdown-pages/docs/galasa-hub.md index 3fde1628..14402165 100644 --- a/src/markdown-pages/docs/galasa-hub.md +++ b/src/markdown-pages/docs/galasa-hub.md @@ -67,14 +67,6 @@ Find out how the IBM Z and z/OS Platform Evaluation and Test (zPET) team are usi Read the blog -## Blog: IBM Z Application Continuous Testing using Galasa -A tutorial focusing on using the Galasa framework for automated application testing on IBM Z applications. You will learn how to setup a Galasa Ecosystem, integrate Eclipse and Jenkins with the Ecosystem and run IBM Z application Galasa test cases in the Ecosystem from Eclipse and a Jenkins pipeline.
- -**Author: Anuprakash Moothedath, June 11, 2021**
-*Source: IBM Developer*

- - Read the blog - ## Video: Mainframe a La Mode: Galasa - Integration testing for IBM Z and beyond Galasa's open source automation framework enables mainframe developers to automate their apps for both IBM and hybrid cloud.
diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index 127b04b4..95698461 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -5,7 +5,7 @@ title: "Highlights" # Galasa Delivery -Galasa is an open source project and is delivered using a continuous delivery model. There are instructions on [getting started](/src/markdown-pages/docs/cli-command-reference/cli-command-reference) on this site. +Galasa is an open source project and is delivered using a continuous delivery model. There are instructions on [getting started](https://galasa.dev/docs/cli-command-reference/cli-command-reference) on this site. Post a question or share your experiences with other users in our Galasa Slack workspace. Register to join first if you're not yet a member. From 6448ea47b019dcbc8e4563c8ba0d827d4679022a Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Tue, 5 Mar 2024 15:11:20 +0000 Subject: [PATCH 14/22] minor update --- src/markdown-pages/doc_root.md | 2 +- src/markdown-pages/docs/first-steps/zipped-prerequisites.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root.md index 0569dcdf..56327da7 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root.md @@ -14,6 +14,6 @@ You downloaded and installed Galasa, you can import the configuration into an ID If you are installing Galasa from GitHub, follow the instructions in the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation. -If you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using the zipped distribution](/docs/getting-started/getting-started-zipped) documentation. +If you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using the zipped distribution](/docs/first-steps/getting-started-zipped) 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/first-steps/zipped-prerequisites.md b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md index d1a98618..b9598767 100644 --- a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md +++ b/src/markdown-pages/docs/first-steps/zipped-prerequisites.md @@ -22,4 +22,4 @@ The following section explains more about the software prerequisites that you ne ## Next steps -Install the Galasa plug-in using the zipped distribution by following the instructions in [Installing the Galasa plug-in offline](/docs/getting-started/installing-offline). \ No newline at end of file +Install the Galasa plug-in using the zipped distribution by following the instructions in [Installing the Galasa plug-in offline](../first-steps/installing-offline). \ No newline at end of file From df4e723a6f8d4787bdd7896f4359dec5d3c4fef7 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 7 Mar 2024 10:53:21 +0000 Subject: [PATCH 15/22] updates to offline install --- .../installing-cli-tool.md | 5 +- .../docs/first-steps/installing-offline.md | 106 +++++------------- src/markdown-pages/docs/upgrading.md | 71 ++++++------ 3 files changed, 66 insertions(+), 116 deletions(-) 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 eea73596..d5b30f05 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 @@ -32,10 +32,9 @@ 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`). -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 `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. +4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`.If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command 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. +You can now run the Galasa CLI tool from any directory in your file system without having to specify the absolute path. On Windows (Powershell): diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index b8b0253d..a218ea33 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -33,57 +33,34 @@ Note: The example uses port `8080` but you can use a different port. docker load -i isolated.tar ``` -The following confirmation message is received: _Loaded image: icr.io/galasadev/galasa-distribution:latest_. +The following confirmation message is received: _Loaded image: icr.io/galasadev/galasa-distribution:main_. 2. Run the container by using the following command: ``` -docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:latest +docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:main ``` -3. Go to `http:\\hostname:8080` to view the running container. +3. Go to `http:\\localhost:8080` to view the running container. -You are now ready to install the Galasa plug-in. -## Installing the Galasa plug-in -1. Launch Eclipse. If present, close any initial welcome screen. -1. Choose _Help > Install New Software_ from the main menu. -1. Choose from the following options: - 1. If you have the zip extracted locally, complete the following steps: - 1. Click *Add* and then Select *Local* - 1. Navigate to the directory into which the zip was extracted, select the Eclipse directory, and click *OK* - 1. Check that the `Location` field is populated with the filepath information, for example, `file:///home/username/galasa-isolated-mvp/eclipse/` and press _Enter_. - 1. If you are using the Docker hosting mechanism, populate the `Location` field with the URL to the running container, for example, `http://hostname:8080/eclipse` and press _Enter_. -1. Tick the _Galasa_ box in the main panel, ensuring that _Galasa_ and all of its child elements are ticked and press _Next_. -1. Follow the prompts to download and install the Galasa plug-in. You will be asked to accept the terms of the license agreement and restart Eclipse to complete the installation. You may also be asked to acknowledge and agree that you are installing unsigned content. -1. After Eclipse has restarted, you can verify that the plug-in is now available by observing the presence of a new _Galasa_ option on the main menu between _Run_ and _Window_. If you choose _Run > Run Configurations_ from the main menu, you will also observe three new entries: _Galasa - Gherkin_, _Galasa - Java_ and _Galasa SimBank_ as available options in the left-hand panel of the pop-up window. +## Configuring the Galasa CLI for offline use -## Configuring Eclipse for Galasa +On Mac or Unix: - - +1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. -1. Choose _Galasa > Setup Galasa Workspace_ from the main Eclipse menu - this command creates some necessary configuration files. Your Eclipse console confirms its progress with some messages: +1. Re-name the appropriate binary of the Galasa CLI for your machine architecture from inside the `galasactl` directory of the zipped distribution to `galasactl`. - ``` - Setting up the Galasa workspace - Creating the ~/.galasa files - Created the ~/.galasa directory - Created an empty Bootstrap Properties file ~/.galasa/bootstrap.properties - Created an empty Overrides Properties file ~/.galasa/overrides.properties - Created an empty Credentials Properties file ~/.galasa/credentials.properties - Created an empty CPS Properties file ~/.galasa/cps.properties - Created an empty DSS Properties file ~/.galasa/dss.properties - The ~/.m2 directory already exists - Created the ~/.m2/.settings.xml example file - Setup complete - ``` -1. Locate your user home directory and confirm 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 operating system to show hidden files. +1. Add it 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`). + +1. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command 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. + +## Configuring your Galasa home to run the sample tests + +1. Check to see if you have a `.galasa` folder in your user home directory. On Windows, the user home directory resembles: `C:\Users\`, on MacOS or Linux, entering `cd ~` in a terminal takes you to your user home directory, whatever it has been configured to be. Note that any file or folder beginning with a `.` is a hidden folder, so you might need to change the settings on your operating system to show hidden files. If there isn't a `.galasa` folder in your home directory, create it with `galasactl local init`. 1. Edit a file called `overrides.properties` in your `.galasa` folder so that it contains the following configuration properties. Configuration properties held in this file are used by Galasa tests at runtime. You can change the value of the properties that are set in this file to enable you to run tests against different configurations without changing the test code. The following example configuration properties enable the provided Galasa SimBank tests to run on your machine: ```properties zos.dse.tag.SIMBANK.imageid=SIMBANK @@ -111,44 +88,21 @@ dss.properties ``` Note: If you have previously installed Galasa, this file is already populated. - - -Your local Eclipse Galasa installation is now ready for some work. Start by [exploring Galasa Simbank](../cli-command-reference/simbank-cli) to help you to learn about the Galasa basics. +You can now run local Galasa tests offline. diff --git a/src/markdown-pages/docs/upgrading.md b/src/markdown-pages/docs/upgrading.md index be4b1196..0ce34ac6 100644 --- a/src/markdown-pages/docs/upgrading.md +++ b/src/markdown-pages/docs/upgrading.md @@ -3,29 +3,41 @@ path: "/docs/upgrading" title: "Upgrading" --- -## Upgrading using the external update site +## Upgrading using the command line -You can get the latest version of Galasa in Eclipse by completing the following steps: +You can get the upgrade your version of Galasa by completing the following steps: -1. Launch Eclipse. -2. Choose *Help > Install New Software* from the main menu. -3. Select `https://p2.galasa.dev/` in the _Work with_ field to check whether a new version of Galasa is available. -4. If a new version is available, tick the *Galasa* box in the main panel, ensuring that *Galasa* and all child elements are ticked. -5. Follow the prompts to download and install the new version of Galasa. Eclipse restarts and the latest version is installed. +1. Download the appropriate version of the Galasa CLI for your machine architecture from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub. +2. Re-name the your existing `galasactl` binary so that you can re-name the Galasa binary that you just downloaded to `galasactl` to replace it. +3. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`.If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. -## Upgrading using the Galasa zipped distribution +If you have already added the Galasa CLI path to your shell's initialization file, as described in the [Installing the Galasa CLI](../docs/cli-command-reference/installing-cli-tool) topic, you should now be able to run the upgraded version of the Galasa CLI tool from any directory in your file system. + + +## Upgrading the Galasa zipped distribution using the command line Download and extract the Galasa zip file to a directory of your choice and complete the following steps: -1. Launch Eclipse. -2. Choose *Help > Install New Software* from the main menu. -3. Click *Add* and then Select *Local*. -4. Navigate to the directory into which the zip was extracted, select the Eclipse directory, and click *OK*. -5. Check that the _Location_ field is populated with the filepath information or URL to the running container, for example, `file:///home/username/galasa-isolated-mvp/eclipse/` or `http://hostname:8080/eclipse` and press *Enter*. -6. Tick the *Galasa* box in the main panel, ensuring that *Galasa* and all child elements are ticked. -7. Follow the prompts to download and install the new version of Galasa. Eclipse restarts and the latest version is installed. +## Upgrading from using Eclipse to using the command line + +Version 0.31.0 is the last version of the Eclipse plug-in for Galasa that is produced and maintained by the Galasa Team. +You can work with later versions of Galasa by using the Galasa command line interface (CLI). The galasactl tool can do everything that the Eclipse tooling can do, and can be run from the command-line of any IDE, for example, the Eclipse terminal view. You can find out more about the Galasa command line tool (galasactl) in the [Getting started using the Galasa CLI](../docs/cli-command-reference/cli-command-reference) topic. + + +There is also a video about +the Galasa command line tool that is available to watch on YouTube. Watch the video to learn about the software requirements you need to get started with galasactl and find out how to download and install it on your local machine. There is also a demo that takes you through the process of creating, building and running Galasa tests, and viewing the output of those test runs.
+ + +To upgrade to a Galasa version that uses the CLI when your previous Galasa version was using Eclipse, complete the following steps: + +1. Check that you have the software that you need installed by viewing the [CLI prerequisites](../docs/cli-command-reference/cli-prereqs) topic. +2. Complete the steps outlined in the [Installing the Galasa CLI](../docs/cli-command-reference/installing-cli-tool) topic to download and install the correct Galasa CLI binary file for your machine architecture. +3. Check that you have an OBR project for your test code. If not, you can create a project that uses the names that you want by using the `galasactl project create` command, and copying your test code into the correct places. For more information about the `galasactl project create` command, see the [Creating a Galasa project using the command line](../docs/writing-own-tests/setting-up-galasa-project) topic. + +If you encounter any difficulties, reach out for help in our Galasa Slack workspace in the `#galasa-users` channel. + ## Upgrading existing tests @@ -34,8 +46,8 @@ If you have a pre-built version of tests that were created against an earlier ve A simple way to do this is to complete the following steps: -1. Search your Galasa files for the version number against which the tests were created, for example *0.9.0*. A filtered list of files containing *0.9.0* is returned. -2. Check each pom.xml file and replace that version number with the new version number, for example, *0.10.0*. +1. Search your Galasa files for the version number against which the tests were created, for example *0.27.0*. A filtered list of files containing *0.27.0* is returned. +2. Check each pom.xml file and replace that version number with the new version number, for example, *0.28.0*. **NOTE:** Do not update version numbers for non-Galasa dependencies or plug-ins. Only replace the version number for Galasa dependencies, where the *groupId* is set to *dev.galasa*, as per the following examples: @@ -43,7 +55,7 @@ A simple way to do this is to complete the following steps: dev.galasa galasa-parent -0.10.0 +0.28.0 ``` @@ -52,36 +64,21 @@ A simple way to do this is to complete the following steps: dev.galasa dev.galasa - 0.10.0 + 0.28.0 provided ``` 3. Check that the OBR version in the Galasa preferences references the new version of Galasa.

- If you are using Eclipse, complete the following steps:

- a. Go to *Eclipse > Preferences > Galasa* on a Mac or *Window > Preferences > Galasa* on Windows.

- b. Check the *OBR Version* field is blank, to automatically select the latest version.

If you are using VS code, complete the following steps:

a. Go to *File > Preferences > Settings* and expand the *Extensions* section.

- b. Select *Galasa* and check that the *Version* field is using the default value of ```LATEST```, to automatically select the latest version. + b. Select *Galasa* and check that the *Version* field is using the default value of ```main```, to automatically select the latest version. ## Troubleshooting If you have problems after completing the steps for upgrading, try running a clean install. -To run a clean Maven install in Eclipse, complete the following steps: - -1. Right click your project and select *Run as > Maven clean* -2. Right click your project and select *Run as > Maven install* - -Alternatively, run the ```mvn clean install ``` command from the command line. - -To run a clean Gradle install in Eclipse, complete the following steps: - -1. 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. -1. Navigate to *Run > Run Configurations*. The *Create, manage and run configurations* dialog box appears. -1. Depending on version of Eclipse that you are using, either right-click *Gradle Project* or *Gradle Task* and choose *New Configuration*. -1. Provide a meaningful name and set up your Gradle Task to run a clean build. +To run a clean Maven install, run the ```mvn clean install ``` command from the command line. -Alternatively, run the ```gradle clean build``` command from the command line. +To run a clean Gradle install, run the ```gradle clean build``` command from the command line. If you are still having issues, you can force a full rebuild by deleting your *.m2* repository and creating a new build against your test projects and Managers by running a clean install. \ No newline at end of file From 9a87e70864481b68d20e0002ae38e23a1a9a7c9e Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 7 Mar 2024 11:22:13 +0000 Subject: [PATCH 16/22] add 32 release notes and update 31 to 32 where needed --- src/markdown-pages/highlights.md | 23 ++++++++++++++++++++++- src/pages/index.js | 2 +- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index b53719e1..263d47bb 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -17,7 +17,27 @@ We have the following available Slack channels: Access the Galasa source code in [GitHub](https://github.com/galasa-dev) and open issues in the [project management repository](https://github.com/galasa-dev/projectmanagement). -## 0.31.0 - Release Highlights + +## 0.32.0 - Release Highlights + +- CLI updates: + + • You can re-try running a test run which appears to be hanging or looping by using the `galasactl runs reset` command. + + • You can cancel a test that is hanging or looping by using the `galasactl runs cancel` command. Cancelling a test removes all entries in the DSS for that test run. All information that is stored in the RAS about the test is kept and is not removed when either the `runs reset` or `runs cancel` command is run. + + • You can run Gherkin tests locally on your machine by setting the `--gherkin` flag on the `galasactl runs submit local` command. + +- Updates to the Galasa authentication token and documentation updates around authentication, architecture, and logging into and out of a Galasa Ecosystem by using the `galasactl auth login` and `galasactl auth logout` commands. + +- The Eclipse plug-in for Galasa is no longer supported. You can work with Galasa version 0.32.0 and later by using the Galasa command line interface (CLI). + +- Various documentation enhancements. + + + +
+0.31.0 - Release Highlights - CLI updates: @@ -35,6 +55,7 @@ Access the Galasa source code in [GitHub](https://github.com/galasa-dev) and ope - Various documentation enhancements - A new blog post by Louisa Seers, encapsulating her experiences during her first six months as Chair of the Galasa Technical Steering Committee (TSC) and the Galasa journey to adoption by the Open Mainframe Project (OMP), is now available on the Open Mainframe Project website. +
diff --git a/src/pages/index.js b/src/pages/index.js index ebedda38..82e0b5ee 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -126,7 +126,7 @@ const IndexPage = () => ( Learn more From b5e784155595962fd3c5a3746e58a7420635c666 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Mon, 11 Mar 2024 13:01:38 +0000 Subject: [PATCH 17/22] r32 release notes --- .../docs/cli-command-reference/running-simbank-tests-cli.md | 2 +- .../docs/ecosystem/ecosystem-installing-k8s.md | 6 +++--- src/markdown-pages/docs/ecosystem/ecosystem-installing.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md index c89890f9..29e0a043 100644 --- a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md @@ -50,7 +50,7 @@ In order to run the Galasa SimBanks tests you need to add some configuration inf The SimBank tests are held in the Galasa simplatform repository in GitHub. To start running the tests you need to clone the repository, if you have not already done so. To find out how to clone the cli repository, follow the instruction in the `Launching SimBank` section in the [Exploring Galasa SimBank using the CLI](exploring-simbank-tests) documentation. -After cloning the repository, complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0` and Galasa uber OBR version `0.31.0`. +After cloning the repository, complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0` and Galasa uber OBR version `0.32.0`. You can find the version of the `dev.galasa.simbank.obr` that you are using by looking in the `pom.xml` file in the `dev.galasa.simbank.obr` folder. The `dev.galasa.uber.obr` is the OBR that contains all the bundles that are needed for Galasa to work including Managers, any required dependencies, the framework, etc. The version of the `dev.galasa.uber.obr` depends on which version of Galasa you have installed. diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md index ccb18a70..b0ba3b27 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md @@ -259,21 +259,21 @@ You can then deploy your Galasa tests to a Maven repository and set up a test st ## Upgrading the Galasa Ecosystem -To upgrade the Galasa Ecosystem to use a newer version of Galasa, for example version 0.31.0, run the following command: +To upgrade the Galasa Ecosystem to use a newer version of Galasa, for example version 0.32.0, run the following command: On Mac or Unix: ```console helm upgrade galasa/ecosystem --reuse-values \ ---set galasaVersion=0.31.0 --wait +--set galasaVersion=0.32.0 --wait ``` On Windows (Powershell): ```console helm upgrade galasa/ecosystem --reuse-values ` ---set galasaVersion=0.31.0 --wait +--set galasaVersion=0.32.0 --wait ``` where:
diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md index d6cfd564..fb6e2cc3 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md @@ -50,10 +50,10 @@ The ecosystem needs to know the hostname or IP address of the VM on which the Do ``` hostname: 192.168.1.87 galasaRegistry: icr.io/galasadev -version: 0.31.0 +version: 0.32.0 engineController: - controllerVersion: 0.31.0 - engineVersion: 0.31.0 + controllerVersion: 0.32.0 + engineVersion: 0.32.0 simplatform: version: 0.15.0 ``` From 7b1c58aa4650169cdcd53c23caac435960063b27 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 13 Mar 2024 14:21:12 +0000 Subject: [PATCH 18/22] add installing offline doc --- src/data/nav.yaml | 31 ++-- .../{doc_root.md => doc_root_old.md} | 2 +- src/markdown-pages/docs/architecture.md | 2 +- .../cli-command-reference.md | 19 --- .../docs/cli-command-reference/cli-prereqs.md | 8 +- .../docs/cli-command-reference/doc_root.md | 22 +++ .../initialising-home-folder.md | 151 ++++++++++++++++++ .../installing-cli-tool.md | 12 +- .../installing-offline.md | 88 ++++++++++ .../running-simbank-tests-cli-offline.md | 97 +++++++++++ .../running-simbank-tests-cli.md | 8 +- .../cli-command-reference/runs-local-debug.md | 2 +- .../runs-submit-local.md | 4 +- .../simbank-cli-offline.md | 121 ++++++++++++++ .../docs/cli-command-reference/simbank-cli.md | 4 +- .../viewing-test-results-cli.md | 2 +- .../zipped-prerequisites.md | 12 +- .../first-steps/getting-started-zipped.md | 4 +- .../first-steps/initialising-home-folder.md | 3 +- .../docs/first-steps/installing-offline.md | 70 +++----- .../docs/running-simbank-tests/simbank-IVT.md | 2 +- .../writing-a-simbank-test.md | 2 +- src/markdown-pages/docs/upgrading.md | 4 +- src/markdown-pages/docs/writing-own-tests.md | 2 +- src/markdown-pages/faqs-galasa.md | 2 +- 25 files changed, 555 insertions(+), 119 deletions(-) rename src/markdown-pages/{doc_root.md => doc_root_old.md} (98%) delete mode 100644 src/markdown-pages/docs/cli-command-reference/cli-command-reference.md create mode 100644 src/markdown-pages/docs/cli-command-reference/doc_root.md create mode 100644 src/markdown-pages/docs/cli-command-reference/initialising-home-folder.md create mode 100644 src/markdown-pages/docs/cli-command-reference/installing-offline.md create mode 100644 src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md create mode 100644 src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md rename src/markdown-pages/docs/{first-steps => cli-command-reference}/zipped-prerequisites.md (58%) diff --git a/src/data/nav.yaml b/src/data/nav.yaml index 2c896772..4346b4d4 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -30,19 +30,21 @@ items: - title: Galasa Architecture path: /docs/architecture - - title: Installing options - path: /docs/ - title: Getting started using the Galasa CLI - path: /docs/cli-command-reference/cli-command-reference + path: /docs items: - - title: CLI prerequisites + - title: CLI prerequisites online path: /docs/cli-command-reference/cli-prereqs - - title: Installing the Galasa CLI + - title: CLI prerequisites offline + path: /docs/cli-command-reference/zipped-prerequisites + - title: Installing the Galasa CLI online path: /docs/cli-command-reference/installing-cli-tool + - title: Installing the Galasa CLI offline + path: /docs/cli-command-reference/installing-offline - title: Galasa CLI commands path: /docs/cli-command-reference/cli-command-reference-about - title: Initialising your local environment - path: /docs/initialising-home-folder + path: /docs/cli-command-reference/initialising-home-folder - title: Creating a Galasa project path: /docs/writing-own-tests/setting-up-galasa-project - title: Running a test locally @@ -51,17 +53,14 @@ path: /docs/cli-command-reference/cli-runs-local-debug - title: Viewing test results locally path: /docs/cli-command-reference/viewing-test-results-cli - - title: Exploring Galasa SimBank + - title: Exploring Galasa SimBank online path: /docs/cli-command-reference/simbank-cli - - title: Running the SimBank tests - path: /docs/running-simbank-tests-cli - - title: Getting started using the zipped distribution - path: /docs/first-steps/getting-started-zipped - items: - - title: Zipped distribution prerequisites - path: /docs/first-steps/zipped-prerequisites - - title: Installing the Galasa plug-in offline - path: /docs/first-steps/installing-offline + - title: Exploring Galasa SimBank offline + path: /docs/cli-command-reference/simbank-cli-offline + - title: Running the SimBank tests online + path: /docs/cli-command-reference/running-simbank-tests-cli + - title: Running the SimBank tests offline + path: /docs/cli-command-reference/running-simbank-tests-cli-offline - title: Exploring the supplied SimBank tests path: /docs/exploring-simbank-tests items: diff --git a/src/markdown-pages/doc_root.md b/src/markdown-pages/doc_root_old.md similarity index 98% rename from src/markdown-pages/doc_root.md rename to src/markdown-pages/doc_root_old.md index 56327da7..19fdbd79 100644 --- a/src/markdown-pages/doc_root.md +++ b/src/markdown-pages/doc_root_old.md @@ -1,5 +1,5 @@ --- -path: "/docs" +path: "/docs/old" title: "Installing options" --- diff --git a/src/markdown-pages/docs/architecture.md b/src/markdown-pages/docs/architecture.md index ed1d88e8..34af7be8 100644 --- a/src/markdown-pages/docs/architecture.md +++ b/src/markdown-pages/docs/architecture.md @@ -3,7 +3,7 @@ path: "/docs/architecture" title: "Architecture" --- -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. +To get going with Galasa as quickly as possible, explore the [Getting started using the Galasa CLI](/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 deleted file mode 100644 index 398e6893..00000000 --- a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -path: "/docs/cli-command-reference/cli-command-reference" -title: "Getting started using the Galasa CLI" ---- - - -If you are installing Galasa for using in the command-line, you can use the Galasa command line interface (CLI) tool (galasactl) to interact with Galasa. The galasactl tool helps you to set up your environment for developing Galasa tests, generate sample Galasa test code, and submit and monitor Galasa test runs. - -The same set of Galasa CLI commands can be used to run a given task, regardless of the technology that you are using. - -The following topics in this section take you through the software requirements, and explain how to download and install the galasactl tool. You can then find out how to initialise your local environment so that you can start creating, building and running Galasa tests, and viewing the test run output. - -## Next steps - -To learn about the software that you need to install to start using Galasa, see the [CLI prerequisites](/docs/cli-command-reference/cli-prereqs) documentation. - -You can also watch a video about the The Galasa command line tool, which guides you through the process of setting up and using the tool from start to finish. - - diff --git a/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md b/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md index bf00b117..0e56ac04 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-prereqs.md @@ -1,10 +1,10 @@ --- path: "/docs/cli-command-reference/cli-prereqs" -title: "CLI prerequisites" +title: "CLI prerequisites online" --- -The following section explains more about the software prerequisites that you need to install so that you are ready to install Galasa for using in the command-line. +The following section explains more about the software prerequisites that you need so that you are ready to install Galasa from the Galasa CLI repository in GitHub. ## Prerequisites @@ -12,10 +12,10 @@ The following section explains more about the software prerequisites that you ne | :---- | :-------- | | 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. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation.| | 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.9.x. Remember to add Gradle to your Path. You can check by running `echo $PATH` on Mac or Unix, or `echo %PATH%` on Windows (PowerShell). | -| 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](../cli-command-reference/simbank-cli), 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.| +| 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 online](../cli-command-reference/simbank-cli), 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.| ## Next steps -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. +To install Galasa for using in the command line, follow the instructions in the [Installing the Galasa CLI online](/docs/cli-command-reference/installing-cli-tool) documentation. diff --git a/src/markdown-pages/docs/cli-command-reference/doc_root.md b/src/markdown-pages/docs/cli-command-reference/doc_root.md new file mode 100644 index 00000000..4f6a2387 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/doc_root.md @@ -0,0 +1,22 @@ +--- +path: "/docs" +title: "Getting started using the Galasa CLI" +--- + + +There are two options available when downloading Galasa. You can download Galasa from the Galasa CLI repository in GitHub, or you can download the Galasa zipped distribution for sharing with your department. If you do not have access to Maven Central or Docker Hub from your company network, use the Galasa zipped distribution. Otherwise, download the binary file for the Galasa CLI from GitHub. Once you have downloaded and installed Galasa, you can import the configuration into an IDE of your choice. + +Prerequisites vary, depending on the option that is chosen. For the purposes of the Galasa documentation, the term `online` refers to the Galasa binary that is downloaded from the Galasa CLI repository in GitHub, and the term `offline` refers to Galasa zipped distribution. + +The following topics in this section take you through the software requirements for each install option, and explain how to get started with the galasactl tool. You can then find out how to initialise your local environment so that you can start creating, building and running Galasa tests, and viewing the test run output. + + +## Next steps + +To learn about the software that you need to install to start using Galasa, see the [CLI prerequisites online](/docs/cli-command-reference/cli-prereqs) documentation, or the [CLI prerequisites offline](/docs/cli-command-reference/zipped-prerequisites) documentation, depending on which option you have chosen. + +To find out about the architecture of Galasa and some of its key components, take a look at the [Galasa architecture](/docs/architecture) documentation. + +If you have access to YouTube, you can also watch a video about the The Galasa command line tool, which guides you through the process of setting up and using the tool from start to finish. + + diff --git a/src/markdown-pages/docs/cli-command-reference/initialising-home-folder.md b/src/markdown-pages/docs/cli-command-reference/initialising-home-folder.md new file mode 100644 index 00000000..9195cacd --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/initialising-home-folder.md @@ -0,0 +1,151 @@ +--- +path: "/docs/cli-command-reference/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 directory. You can set up this structure easily by using the galasactl tool to initialise your local environment. Once your local environment is initialised, you can start running Galasa tests on your local JVM. + +## Setting the Galasa home folder (optional) + +Galasa has 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. + +You do not need to change the default setting, but if you want to, the default value can be overridden by 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_HOME=/temp/mygalasatests +``` + +On Windows: + +``` +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. + +## Setting up the Galasa file structure + +You can initialise your local environment, and set up the files and file structure you need, by running the following command on a command line: + +`galasactl local init` + + +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: + +``` +${HOME}/.galasa +├── bootstrap.properties +├── cps.properties +├── credentials.properties +├── dss.properties +├── overrides.properties +``` + +For more information about these files and what they are used for, see the [About the properties files](#about) section. + +Running the `galasactl local init` command also creates an `/.m2` directory, containing a `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. + +You can validate the set up by locating your user home directory and confirming that it contains a `.galasa` and a `.m2` 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. + + +*Note - online installation only:*
If an `.~/.m2/settings.xml` file already exists, the `galasactl local init` command does not update it. View the file contents and check that it has the required `maven.central` and `plugin` repositories configured. The file should contain the following content: + +``` + + + dev.galasa + + + + + galasa + + true + + + + maven.central + https://repo.maven.apache.org/maven2/ + + + + + + maven.central + https://repo.maven.apache.org/maven2/ + + + + + + +``` + +If you have access to GitHub, you can view the full list of options (flags) that are available with the `galasactl local init` command in the Galasa CLI repository. + +## About the properties files + +The following table explains a bit more about the purpose of the properties files that are created in the `.galasa` folder after running the `galasactl local init` command: + +| 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 | In a local environment, or when running tests locally within a pipeline, the Dynamic Status Store (DSS) is stored in a file. In an Ecosystem, the DSS is hosted on the `etcd` server. The DSS contains a number of settings, and counters that Managers put there, to indicate what resources are currently in-use so far. If a z/OS machine only has 10 ports configured for example, the counter reaches 10, which will prevent any more tests trying to allocate a port for them to use. There is a danger if tests are stopped, that the proper clean-up is skipped, and the port number doesn't decrease when a test owning that port stops abnormally. Normal operation of an Ecosystem includes a resource monitor which looks for this situation and releases resources that a failed test owns. In a local run that isn't present, so the DSS might not accurately reflect the number of resources that are available. To resolve, if no tests are running, you can clear out the `dss.properties` files in your pipeline, which steps all the counters down to 0. Note that if you always clear out the dss file, the `run name` of tests will always start from the same number, as the `latest test number allocated` counter is also stored in 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. | + + + +## 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://galasa-bootstrap.url.com`, use the following command: + +On Mac or Unix: + +``` +export GALASA_BOOTSTRAP=http://galasa-bootstrap.url.com/bootstrap +``` + +On Windows: + +``` +set GALASA_BOOTSTRAP=http://galasa-bootstrap.url.com/bootstrap +``` + +where: +`http://galasa-bootstrap.url.com` is the URL of the Galasa Ecosystem in which you want to run your test or in which the shared configuration is stored. + + + +## Next steps + +You can now start [creating a project using the CLI](/docs/writing-own-tests/setting-up-galasa-project) to accommodate your Galasa tests in your local storage. + + + 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 d5b30f05..cc49e08f 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,16 +1,14 @@ --- path: "/docs/cli-command-reference/installing-cli-tool" -title: "Installing the Galasa CLI" +title: "Installing the Galasa CLI online" --- -This section provides details about how to download and install the Galasa command line interface tool (galasactl) on your local machine and tells you a little bit about getting started with the Galasa CLI commands. +This section provides details about how to download and install the binary file for the Galasa CLI from the Galasa CLI respository in GitHub to your local machine, and tells you a little bit about getting started with the Galasa CLI commands. ## 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 | Architecture | Download | @@ -30,8 +28,8 @@ 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`). +2. Download the appropriate binary of the Galasa CLI for your machine architecture from the Galasa CLI repository in GitHub and re-name it to `galasactl`. +3. Add the 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`.If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. You can now run the Galasa CLI tool from any directory in your file system without having to specify the absolute path. @@ -43,7 +41,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. For example, save the galasactl executable to a folder called `~/tools` in your `C:` directory and run the `set 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. +You can now run the Galasa CLI tool from any directory in your file system without having to specify the absolute path. diff --git a/src/markdown-pages/docs/cli-command-reference/installing-offline.md b/src/markdown-pages/docs/cli-command-reference/installing-offline.md new file mode 100644 index 00000000..7094fcd5 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/installing-offline.md @@ -0,0 +1,88 @@ +--- +path: "/docs/cli-command-reference/installing-offline" +title: "Installing the Galasa CLI 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 (galasactl, maven, and javadoc), an `isolated.tar` file and a `docs.jar` file. + +The `galasactl` directory contains the binaries that are required to run the Galasa command line interface tool (Galasa CLI). 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. + +The `docs.jar` file enables you to run the Galasa website locally on your machine or on an internal server. Instructions on how to do this are available in the `README.txt` that is provided in the Galasa zip file. + +## Getting started + +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 using the Galasa command line tool (galasactl) 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. + + +## Unpacking the zip file + +Extract the contents of the zip file into a directory of your choice. + +If you are using the zipped distribution hosted in Docker, ensure that you have the appropriate privileges to run Docker commands on the server on which you are hosting the Galasa artifacts and complete the following steps to load and run the Docker image: + +Note: The example uses port `8080` but you can use a different port. + +1. Within the directory that contains the Docker image (`isolated.tar`), run the following command: +``` +docker load -i isolated.tar +``` + +The following confirmation message is received: _Loaded image: icr.io/galasadev/galasa-distribution:main_. + +2. Run the container by using the following command: +``` +docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:main +``` + +3. Go to `http:\\localhost:8080` to view the running container. + + + +## Configuring the Galasa CLI for offline use + +To install Galasa for using in the command-line you first need to select the appropriate binary file for the Galasa CLI from the `galasactl` directory that is provided in the zip file you downloaded. + +The following versions of the Galasa CLI are available to download for different operating systems and machine architectures: + +| Operating system | Architecture | Download | +| :---- | :---- | :-------- | +| MacOSX | x86_64 | galasactl-darwin-x86_64 | +| MacOSX | arm64 | galasactl-darwin-arm64 | +| Linux | x86_64 | galasactl-linux-x86_64 | +| Linux arm64 | arm64 | galasactl-linux-arm64 | +| zLinux | s390x| galasactl-linux-s390x | +| Windows | x86_64| galasactl-windows-x86_64.exe | + + +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. You can use the information that is returned to understand which binary of the Galasa CLI you need to use for your particular machine architecture. + +1. Open the `galasactl` directory that is provided in the zip file and re-name the appropriate binary to `galasactl`. + +1. Add the 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`). + +1. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. + + +On Windows (Powershell): + +1. Open the `galasactl` directory that is provided in the zip file and re-name the appropriate to `galasactl`. +2. Add the Galasa CLI 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 `set 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 tool from any directory in your file system without having to specify the absolute path. + +## Next steps + +Find out more about the Galasa CLI commands by reading the [Galasa CLI commands](cli-command-reference-about) documentation. + +Move on to the [Initialising your local environment](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/running-simbank-tests-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md new file mode 100644 index 00000000..25c99825 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md @@ -0,0 +1,97 @@ +--- +path: "/docs/cli-command-reference/running-simbank-tests-cli-offline" +title: "Running the SimBank tests using the CLI offline" +--- + +You can explore Galasa further with Galasa Simbank. Galasa Simbank is a simulated bank application that showcases Galasa's functionality within an application. 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`. + +The following sections explain how to run the `SimBankIVT` test class by using the CLI. Make sure that you have installed the Galasa CLI tool and Java version 11 JDK, and have set the JAVA_HOME environment variable, as described in the [CLI prerequisites offline](zipped-prerequisites) documentation. + + +## Updating the overrides and credentials property files + + +In order to run the Galasa SimBanks tests you need to add some configuration information in the `overrides.properties` and `credentials.properties` files that were created when you initialised your Galasa home folder by running the ```galasactl local init``` command. Complete the following steps to edit the files: + + +1. Edit a file called `overrides.properties` in your `.galasa` folder so that it contains the following configuration properties. Configuration properties held in this file are used by Galasa tests at runtime. You can change the value of the properties that are set in this file to enable you to run tests against different configurations without changing the test code. The following example configuration properties enable the provided Galasa SimBank tests to run on your machine: + + ```properties + zos.dse.tag.SIMBANK.imageid=SIMBANK + zos.dse.tag.SIMBANK.clusterid=SIMBANK + + simbank.dse.instance.name=SIMBANK + simbank.instance.SIMBANK.zos.image=SIMBANK + + zos.image.SIMBANK.ipv4.hostname=127.0.0.1 + zos.image.SIMBANK.telnet.port=2023 + zos.image.SIMBANK.webnet.port=2080 + zos.image.SIMBANK.telnet.tls=false + zos.image.SIMBANK.credentials=SIMBANK + + zosmf.image.SIMBANK.servers=SIMBANK + zosmf.server.SIMBANK.image=SIMBANK + zosmf.server.SIMBANK.port=2040 + zosmf.server.SIMBANK.https=false + ``` +1. Edit a file called `credentials.properties` in your `.galasa` folder. Credentials that are held in this file are used by Galasa tests, for example to pass credentials to the application being tested. Storing values in this file avoids the need to hard-code credentials inside a test class, enabling the test to run in different environments without changing any test code. The following example properties enable the provided Galasa SimBank tests to run on your machine: + + ```properties + secure.credentials.SIMBANK.username=IBMUSER + secure.credentials.SIMBANK.password=SYS1 + ``` + +## Running the SimBank IVT test class by using the CLI + +The SimBank tests are located in the `maven` directory of the `isolated.zip` downloadable file. complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.32.0`. + +Remember to initialise your local environment by running the `galasactl local init` command and to start the SimPlatform server by running the `run-simplatform.sh` script, as described in the `Launching SimBank` section in the [Exploring Galasa SimBank using the CLI offline](simbank-cli-offline) documentation. + + +You are now ready to run a local Galasa test offline with just the contents of the zipped distribution. + +1. Open a terminal and run the SimBankIVT test locally by using the following command: +On Mac or Unix: +``` +galasactl runs submit local --log - \ +--obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr \ +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven +``` +On Windows (Powershell): +``` +galasactl runs submit local --log - ` +--obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr ` +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven +``` +Note the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. +1. The `SimBankIVT` test class runs, and the terminal displays its progress through to completion, with an Exit code of `0`. +1. View the results of the test runs in your terminal. You can also view results in the `run.log` file in the result archive store (RAS). 3270 terminal interactions can be viewed in the `artifacts` directory in the RAS. Find out more in the [Viewing test results locally](viewing-test-results-cli-offline) documentation. + +To run other SimBank tests, for example `BasicAccountCreditTest`, replace the test class name in the `--class` parameter. For example: + +On Mac or Unix: + +``` +galasactl runs submit local --log - \ +--obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr \ +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest +``` + +On Windows (Powershell): + +``` +galasactl runs submit local --log - ` +--obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr ` +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest +``` + + + +## Next steps + +Explore the SimBankIVT test and the other SimBank tests in the [Exploring the supplied SimBank tests](/docs/exploring-simbank-tests) 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/cli-command-reference/running-simbank-tests-cli.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md index c89890f9..17263c2d 100644 --- a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli.md @@ -1,5 +1,5 @@ --- -path: "/docs/running-simbank-tests-cli" +path: "/docs/cli-command-reference/running-simbank-tests-cli" title: "Running the SimBank tests using the CLI" --- @@ -10,7 +10,7 @@ You can explore Galasa further with Galasa Simbank. Galasa Simbank is a simulate - 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 CLI. Make sure that you have installed the Galasa CLI tool and Java version 11 JDK, and have set the JAVA_HOME environment variable, as described in the [CLI prerequisites](/docs/cli-command-reference/cli-prereqs) documentation. +The following sections explain how to run the `SimBankIVT` test class by using the CLI. Make sure that you have installed the Galasa CLI tool and Java version 11 JDK, and have set the JAVA_HOME environment variable, as described in the [CLI prerequisites online](cli-prereqs) documentation. ## Updating the overrides and credentials property files @@ -48,7 +48,7 @@ In order to run the Galasa SimBanks tests you need to add some configuration inf ## Running the SimBank IVT test class by using the CLI -The SimBank tests are held in the Galasa simplatform repository in GitHub. To start running the tests you need to clone the repository, if you have not already done so. To find out how to clone the cli repository, follow the instruction in the `Launching SimBank` section in the [Exploring Galasa SimBank using the CLI](exploring-simbank-tests) documentation. +The SimBank tests are held in the Galasa simplatform repository in GitHub. To start running the tests you need to clone the repository, if you have not already done so. To find out how to clone the cli repository, follow the instruction in the `Launching SimBank` section in the [Exploring Galasa SimBank online](simbank-cli) documentation. After cloning the repository, complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0` and Galasa uber OBR version `0.31.0`. @@ -123,4 +123,4 @@ galasactl runs submit local --log - ` ## Next steps -Explore the SimBankIVT test and the other SimBank tests in the [Exploring the supplied SimBank tests](exploring-simbank-tests) 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 +Explore the SimBankIVT test and the other SimBank tests in the [Exploring the supplied SimBank tests](/docs/exploring-simbank-tests) 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/cli-command-reference/runs-local-debug.md b/src/markdown-pages/docs/cli-command-reference/runs-local-debug.md index fe87b203..90adec30 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 @@ -125,4 +125,4 @@ galasactl runs submit local --debug Read the [Viewing test results locally](viewing-test-results-cli) documentation to learn how to view the output of your test runs in your local environment. -Take a look at the [Exploring Galasa SimBank using the CLI](simbank-cli) documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn the basic principles of Galasa's operation before you start connecting Galasa to your own mainframe application-under-test. \ No newline at end of file +Take a look at the [Exploring Galasa SimBank online](simbank-cli) or [Exploring Galasa SimBank offline](simbank-cli-offline)documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn the basic principles of Galasa's operation before you start connecting Galasa to your own mainframe application-under-test. \ No newline at end of file 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 e5b49f71..5c8236b0 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 @@ -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 `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, as described in the [CLI prerequisites](/docs/cli-command-reference/cli-prereqs) documentation. 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, as described in the [CLI prerequisites online](/docs/cli-command-reference/cli-prereqs) and [CLI prerequisites offline](/docs/cli-command-reference/zipped-prerequisites) documentation. 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. @@ -57,7 +57,7 @@ Use `Ctrl-C` to stop the Galasa CLI, ending all test activity. Note that this mi ## Troubleshooting -If you have problems running the command, check that you have installed the correct version of Java installed and that you have set your JAVA_HOME environment variable, as described in the [CLI prerequisites](cli-prereqs) documentation. Make sure you have added the Galasa CLI to your PATH and that you have [initialised your local environment](../../docs/initialising-home-folder) by running the `galasactl local init` command. Ensure that you have created and built the example project, as described in the [Creating a Galasa project using the command line](../writing-own-tests/setting-up-galasa-project) documentation. +If you have problems running the command, check that you have installed the correct version of Java installed and that you have set your JAVA_HOME environment variable, as described in the [CLI prerequisites](cli-prereqs) and [CLI prerequisites offline](/docs/cli-command-reference/zipped-prerequisites) documentation. Make sure you have added the Galasa CLI to your PATH and that you have [initialised your local environment](../../docs/initialising-home-folder) by running the `galasactl local init` command. Ensure that you have created and built the example project, as described in the [Creating a Galasa project](../writing-own-tests/setting-up-galasa-project) documentation. ## Next steps diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md new file mode 100644 index 00000000..2ef99c71 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md @@ -0,0 +1,121 @@ +--- +path: "/docs/cli-command-reference/simbank-cli-offline" +title: "Exploring Galasa SimBank offline" +--- +Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform. 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 understand Galasa's basic principles of operation before you learn how to connect Galasa to your own mainframe application-under-test. + + +## Launching SimBank offline + +SimBank applications and a set of sample SimBank tests are located in the `maven` directory of the `isolated.zip` downloadable file. + +To start exploring the Galasa Simbank application and to run the sample SimBank tests by using the Galasa CLI, you need to complete the following steps: + +1. Start the Simplatform server by running the `run-simplatform.sh` script provided in the `isolated.zip`. + 1. Navigate to the directory of the zipped distribution that you downloaded, for example, `~/Downloads/isolated`. A `run-simplatform.sh` script is available within the directory. This script starts the Simplatform server which is required to run the SimBank tests. + 1. Set execute permission on the script by running the `chmod +x run-simplatform.sh` command in the directory containing the `run-simplatform.sh` script. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine run-simplatform.sh` command in the same directory. + 1. Run the script in server mode by using the following example command, remembering to set the `--location` flag to the location of the galasa-simplatform artefact in the `isolated.zip` file that you downloaded. For example, `~/Downloads/isolated/maven/dev/galasa`. + ``` + ./run-simplatform.sh --server --location ~/Downloads/isolated/maven/dev/galasa + ``` + In a few seconds, the terminal window displays 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. + 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](../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](../first-steps/simbank-userid.png) + +1. Enter the userid `IBMUSER` + + ![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 3270 terminal emulator's ENTER key to logon and transfer to the SimBank main menu: + + ![Banktest home screen](../first-steps/simbank-banktest.png) + +> *Note:* Depending on your 3270 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 3270 terminal emulator's CLEAR SCREEN key. +1. Enter the transaction name `BANK` and press your 3270 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 to your terminal: + +``` +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: + +``` +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 offline](running-simbank-tests-cli-offline). + diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md index 1d0903d9..94c04c6f 100644 --- a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md +++ b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md @@ -1,6 +1,6 @@ --- path: "/docs/cli-command-reference/simbank-cli" -title: "Exploring Galasa SimBank using the CLI" +title: "Exploring Galasa SimBank online" --- Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform. 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. @@ -114,5 +114,5 @@ Press PF3 and once again browse the 123456789 account as described previously to 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](../../docs/running-simbank-tests-cli). +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 online](running-simbank-tests-cli). diff --git a/src/markdown-pages/docs/cli-command-reference/viewing-test-results-cli.md b/src/markdown-pages/docs/cli-command-reference/viewing-test-results-cli.md index 27642937..c428c3fa 100644 --- a/src/markdown-pages/docs/cli-command-reference/viewing-test-results-cli.md +++ b/src/markdown-pages/docs/cli-command-reference/viewing-test-results-cli.md @@ -31,4 +31,4 @@ You can then view the terminal interactions from your test runs in the `images` ## Next steps -Take a look at the [Exploring Galasa SimBank using the CLI](simbank-cli) documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn Galasa's basic principles of operation before you start connecting Galasa to your own mainframe application-under-test. \ No newline at end of file +Take a look at the [Exploring Galasa SimBank online](simbank-cli) or [Exploring Galasa SimBank offline](simbank-cli-offline)documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn Galasa's basic principles of operation before you start connecting Galasa to your own mainframe application-under-test. \ No newline at end of file diff --git a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md b/src/markdown-pages/docs/cli-command-reference/zipped-prerequisites.md similarity index 58% rename from src/markdown-pages/docs/first-steps/zipped-prerequisites.md rename to src/markdown-pages/docs/cli-command-reference/zipped-prerequisites.md index b9598767..b51c6df4 100644 --- a/src/markdown-pages/docs/first-steps/zipped-prerequisites.md +++ b/src/markdown-pages/docs/cli-command-reference/zipped-prerequisites.md @@ -1,10 +1,10 @@ --- -path: "/docs/first-steps/zipped-prerequisites" -title: "Zipped distribution prerequisites" +path: "/docs/cli-command-reference/zipped-prerequisites" +title: "CLI prerequisites offline" --- -The following section explains more about the software prerequisites that you need to install so that you are ready to install the zipped distribution for Galasa. +The following section explains more about the software prerequisites that you need to install so that you are ready to install the zipped distribution for Galasa for running offline. ## Prerequisites @@ -12,14 +12,14 @@ The following section explains more about the software prerequisites that you ne | 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. | +| 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. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation. | | Gradle | Required to install the zipped distribution. You can also build Galasa projects using Gradle. (You can build projects using Maven 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.9.x.| | Maven | 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. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | | 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. | -| 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.| +| 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 offline](simbank-cli-offline), 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.| ## Next steps -Install the Galasa plug-in using the zipped distribution by following the instructions in [Installing the Galasa plug-in offline](../first-steps/installing-offline). \ No newline at end of file +Install the Galasa plug-in using the zipped distribution by following the instructions in [Installing the Galasa CLI offline](installing-offline). \ No newline at end of file diff --git a/src/markdown-pages/docs/first-steps/getting-started-zipped.md b/src/markdown-pages/docs/first-steps/getting-started-zipped.md index 5e733814..47257dea 100644 --- a/src/markdown-pages/docs/first-steps/getting-started-zipped.md +++ b/src/markdown-pages/docs/first-steps/getting-started-zipped.md @@ -4,8 +4,6 @@ title: "Getting started using the zipped distribution" --- -You can download Galasa from a downloadable zip file (zipped distribution). To install the Galasa plug-in using the zipped distribution, check you have installed the [pre-requisite software](../first-steps/zipped-prerequisites) that you need to start using Galasa. Yout can then follow the instructions in [Installing the Galasa plug-in offline](../first-steps/installing-offline) documentation. +You can download Galasa from a downloadable zip file (zipped distribution) for use offline if you do not have access to Maven Central or Docker Hub from your company network. To install the Galasa CLI using the zipped distribution, check you have installed the [Zipped distribution pre-requisite software](../first-steps/zipped-prerequisites) that you need to start using Galasa. You can then follow the instructions in [Installing the Galasa CLI](../first-steps/installing-offline) documentation. -## Next steps -You can then start [exploring Galasa Simbank](../cli-command-reference/simbank-cli.md); 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/initialising-home-folder.md b/src/markdown-pages/docs/first-steps/initialising-home-folder.md index a6e2e8dc..6c0dc7d6 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 directory. You can set up this structure easily by using the galasactl tool to initialise your local environment. Once your local environment is initialised, you can start running Galasa tests on your local JVM. -## Setting the Galasa home folder +## Setting the Galasa home folder (optional) Galasa has 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. @@ -119,6 +119,7 @@ The following table explains a bit more about the purpose of the properties file ## 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. diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index a218ea33..3efc9912 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -1,6 +1,6 @@ --- path: "/docs/first-steps/installing-offline" -title: "Installing the Galasa plug-in offline" +title: "Installing the Galasa CLI 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 (galasactl, maven, and javadoc), an `isolated.tar` file and a `docs.jar` file. @@ -15,8 +15,6 @@ The `docs.jar` file enables you to run the Galasa website locally on your machin 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 using the Galasa command line tool (galasactl) 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. @@ -46,63 +44,45 @@ docker run -d -p 8080:80 --name galasa icr.io/galasadev/galasa-distribution:main ## Configuring the Galasa CLI for offline use -On Mac or Unix: - -1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. +To install Galasa for using in the command-line you first need to select the appropriate binary file for the Galasa CLI from the `galasactl` directory that is provided in the zip file you downloaded. -1. Re-name the appropriate binary of the Galasa CLI for your machine architecture from inside the `galasactl` directory of the zipped distribution to `galasactl`. +The following versions of the Galasa CLI are available to download for different operating systems and machine architectures: -1. Add it 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`). +| Operating system | Architecture | Download | +| :---- | :---- | :-------- | +| MacOSX | x86_64 | galasactl-darwin-x86_64 | +| MacOSX | arm64 | galasactl-darwin-arm64 | +| Linux | x86_64 | galasactl-linux-x86_64 | +| Linux arm64 | arm64 | galasactl-linux-arm64 | +| zLinux | s390x| galasactl-linux-s390x | +| Windows | x86_64| galasactl-windows-x86_64.exe | -1. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command 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. +Complete the following steps to install Galasa for using the command line: -## Configuring your Galasa home to run the sample tests +On Mac or Unix: -1. Check to see if you have a `.galasa` folder in your user home directory. On Windows, the user home directory resembles: `C:\Users\`, on MacOS or Linux, entering `cd ~` in a terminal takes you to your user home directory, whatever it has been configured to be. Note that any file or folder beginning with a `.` is a hidden folder, so you might need to change the settings on your operating system to show hidden files. If there isn't a `.galasa` folder in your home directory, create it with `galasactl local init`. -1. Edit a file called `overrides.properties` in your `.galasa` folder so that it contains the following configuration properties. Configuration properties held in this file are used by Galasa tests at runtime. You can change the value of the properties that are set in this file to enable you to run tests against different configurations without changing the test code. The following example configuration properties enable the provided Galasa SimBank tests to run on your machine: - ```properties - zos.dse.tag.SIMBANK.imageid=SIMBANK - zos.dse.tag.SIMBANK.clusterid=SIMBANK +1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. You can use the information that is returned to understand which binary of the Galasa CLI you need to use for your particular machine architecture. - simbank.dse.instance.name=SIMBANK - simbank.instance.SIMBANK.zos.image=SIMBANK +1. Open the `galasactl` directory that is provided in the zip file and re-name the appropriate binary to `galasactl`. - zos.image.SIMBANK.ipv4.hostname=127.0.0.1 - zos.image.SIMBANK.telnet.port=2023 - zos.image.SIMBANK.webnet.port=2080 - zos.image.SIMBANK.telnet.tls=false - zos.image.SIMBANK.credentials=SIMBANK +1. Add the 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`). - zosmf.image.SIMBANK.servers=SIMBANK - zosmf.server.SIMBANK.image=SIMBANK - zosmf.server.SIMBANK.port=2040 - zosmf.server.SIMBANK.https=false - ``` -1. Edit a file called `credentials.properties` in your `.galasa` folder. Credentials that are held in this file are used by Galasa tests, for example to pass credentials to the application being tested. Storing values in this file avoids the need to hard-code credentials inside a test class, enabling the test to run in different environments without changing any test code. The following example properties enable the provided Galasa SimBank tests to run on your machine: +1. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. - ```properties - secure.credentials.SIMBANK.username=IBMUSER - secure.credentials.SIMBANK.password=SYS1 - ``` - Note: If you have previously installed Galasa, this file is already populated. +On Windows (Powershell): +1. Open the `galasactl` directory that is provided in the zip file and re-name the appropriate to `galasactl`. +2. Add the Galasa CLI 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 `set 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`. -## Running the SimBank IVT offline using the zipped distribution +You can now run the Galasa CLI tool from any directory in your file system without having to specify the absolute path. -1. **TEMPORARY** Replace `~/.m2/repository` in line 130 in the run-locally.sh script with the `maven` directory of wherever you have the zipped distribution saved: `~/Users/youruserid/Downloads/isolated/maven` for example. +## Next steps -1. Run the run-locally.sh script to start the Simplatform server with `run-locally.sh --server` (**TO DO: Add this script to the zipped distribution**) +Find out more about the Galasa CLI commands by reading the [Galasa CLI commands](cli-command-reference-about-offline) documentation. -You are now ready to run a local Galasa test offline with just the contents of the zipped distribution. +Move on to the [Initialising your local environment offline](initialising-home-folder-offline) documentation to help you to set up some basic file structures and files in your home folder so that you can start using Galasa. -1. Run the SimBankIVT test locally using the following command. Note the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. -``` -galasactl runs submit local --log - \ ---obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr \ ---class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven -``` -You can now run local Galasa tests offline. 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 df26ac53..f9c67946 100644 --- a/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md +++ b/src/markdown-pages/docs/running-simbank-tests/simbank-IVT.md @@ -11,7 +11,7 @@ Even without any prior knowledge of Galasa, if you know a little Java, you will The class is first annotated with `@Test` - informing the framework that a method or (as in this case) a class is a test. -Next at the beginning of the test class proper, several Galasa Managers are declared via annotations, together with their corresponding public interfaces - `@ZosImage`, `@Zos3270Terminal` and so on. Using the `imageTag="SIMBANK"` argument with `@ZosImage` allows you to associate an instance of a Manager with a set of configuration properties. In this example, the associated configuration properties are the ones that are set in the `overrides.properties` file, as described in the [Running the SimBank tests using the CLI](../../docs/running-simbank-tests-cli) documentation. +Next at the beginning of the test class proper, several Galasa Managers are declared via annotations, together with their corresponding public interfaces - `@ZosImage`, `@Zos3270Terminal` and so on. Using the `imageTag="SIMBANK"` argument with `@ZosImage` allows you to associate an instance of a Manager with a set of configuration properties. In this example, the associated configuration properties are the ones that are set in the `overrides.properties` file, as described in the [Running the SimBank tests online](/docs/cli-command-reference/running-simbank-tests-cli) and [Running the SimBank tests offline](/docs/cli-command-reference/running-simbank-tests-cli-offline) documentation. ```java @Test diff --git a/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md b/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md index 24995eb3..a3fa786d 100644 --- a/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md +++ b/src/markdown-pages/docs/running-simbank-tests/writing-a-simbank-test.md @@ -11,7 +11,7 @@ Don't forget that whenever you create a test, or modify an existing one, you nee ## Create a new Galasa test class -1. Launch SimBank, either using the [CLI](../cli-command-reference/simbank-cli). +1. Launch SimBank using the instructions in the [CLI online](../cli-command-reference/simbank-cli) or [CLI offline](../cli-command-reference/simbank-cli) documentation. 1. Create a new test class. If you are using the CLI, manually create the test class file, for example in VS Code. Complete the next dialog as follows and then click *Finish*. Note that in the example a new package is created that is called `dev.galasa.simbanks.tests`. ![New Java Class](./create-new-class.png) 1. Annotate the new class with the `@Test` annotation. diff --git a/src/markdown-pages/docs/upgrading.md b/src/markdown-pages/docs/upgrading.md index 0ce34ac6..39965153 100644 --- a/src/markdown-pages/docs/upgrading.md +++ b/src/markdown-pages/docs/upgrading.md @@ -7,7 +7,7 @@ title: "Upgrading" You can get the upgrade your version of Galasa by completing the following steps: -1. Download the appropriate version of the Galasa CLI for your machine architecture from the [Galasa cli repository](https://github.com/galasa-dev/cli/releases) in GitHub. +1. Download the appropriate version of the Galasa CLI for your machine architecture from the Galasa CLI repository in GitHub. 2. Re-name the your existing `galasactl` binary so that you can re-name the Galasa binary that you just downloaded to `galasactl` to replace it. 3. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`.If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. @@ -23,7 +23,7 @@ Download and extract the Galasa zip file to a directory of your choice and compl ## Upgrading from using Eclipse to using the command line Version 0.31.0 is the last version of the Eclipse plug-in for Galasa that is produced and maintained by the Galasa Team. -You can work with later versions of Galasa by using the Galasa command line interface (CLI). The galasactl tool can do everything that the Eclipse tooling can do, and can be run from the command-line of any IDE, for example, the Eclipse terminal view. You can find out more about the Galasa command line tool (galasactl) in the [Getting started using the Galasa CLI](../docs/cli-command-reference/cli-command-reference) topic. +You can work with later versions of Galasa by using the Galasa command line interface (CLI). The galasactl tool can do everything that the Eclipse tooling can do, and can be run from the command-line of any IDE, for example, the Eclipse terminal view. You can find out more about the Galasa command line tool (galasactl) in the [Getting started using the Galasa CLI](../docs/cli-command-reference/doc_root) topic. There is also a video about diff --git a/src/markdown-pages/docs/writing-own-tests.md b/src/markdown-pages/docs/writing-own-tests.md index 93ab9e7f..423e6854 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 CLI 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/faqs-galasa.md b/src/markdown-pages/faqs-galasa.md index 61f58138..b6f37dfa 100644 --- a/src/markdown-pages/faqs-galasa.md +++ b/src/markdown-pages/faqs-galasa.md @@ -150,5 +150,5 @@ Try clearing out the `dss.properties` file on your local machine. The DSS (Dynam Normal operation of an Ecosystem includes a resource monitor which looks for this situation and releases resources that a failed test owns. In a local run the resource monitor isn't present, so the DSS might not accurately reflect how much resource is available. In this example, a test is run, the 3270 port counter increases up to one, the test fails, and the DSS is not cleaned up but gets re-used in the next pipeline run. The counter then starts at one and increases to two and so forth until the limit is reached and a test is no longer able to get access to the resources it needs. The same situation might occur with counters of images on a cluster. -Clearing out the `dss.properties` file resets the counters down to zero again. It is safe to do this providing that no tests are running. In principle, if you run multiple tests in parallel, you can see some of this limiting safety feature start failing tests even if you did not clean out the dss. It is worth noting that if you always clear out the `dss.properties` file, the run name of tests always start from the same number, as the latest test number allocated counter is also kept there. +Clearing out the `dss.properties` file resets the counters down to zero again. It is safe to do this providing that no tests are running. In principle, if you run multiple tests in parallel, you can see some of this limiting safety feature start failing tests even if you did not clean out the DSS. It is worth noting that if you always clear out the `dss.properties` file, the run name of tests always start from the same number, as the latest test number allocated counter is also kept there. From 943a4c4aadc325be6e7029ef0e46a1d1054851a2 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 13 Mar 2024 14:51:03 +0000 Subject: [PATCH 19/22] fix links --- .../running-simbank-tests-cli-offline.md | 2 +- src/markdown-pages/docs/upgrading.md | 20 ++++++++++--------- .../docs/writing-own-tests/binding-tests.md | 2 +- .../setting-up-galasa-project.md | 2 +- .../docs/writing-own-tests/test-streams.md | 2 +- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md index 25c99825..1db98a7b 100644 --- a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md @@ -70,7 +70,7 @@ galasactl runs submit local --log - ` ``` Note the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. 1. The `SimBankIVT` test class runs, and the terminal displays its progress through to completion, with an Exit code of `0`. -1. View the results of the test runs in your terminal. You can also view results in the `run.log` file in the result archive store (RAS). 3270 terminal interactions can be viewed in the `artifacts` directory in the RAS. Find out more in the [Viewing test results locally](viewing-test-results-cli-offline) documentation. +1. View the results of the test runs in your terminal. You can also view results in the `run.log` file in the result archive store (RAS). 3270 terminal interactions can be viewed in the `artifacts` directory in the RAS. Find out more in the [Viewing test results locally](viewing-test-results-cli) documentation. To run other SimBank tests, for example `BasicAccountCreditTest`, replace the test class name in the `--class` parameter. For example: diff --git a/src/markdown-pages/docs/upgrading.md b/src/markdown-pages/docs/upgrading.md index 39965153..b54779a1 100644 --- a/src/markdown-pages/docs/upgrading.md +++ b/src/markdown-pages/docs/upgrading.md @@ -3,7 +3,7 @@ path: "/docs/upgrading" title: "Upgrading" --- -## Upgrading using the command line +## Upgrading (online) You can get the upgrade your version of Galasa by completing the following steps: @@ -11,19 +11,19 @@ You can get the upgrade your version of Galasa by completing the following steps 2. Re-name the your existing `galasactl` binary so that you can re-name the Galasa binary that you just downloaded to `galasactl` to replace it. 3. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`.If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine galasactl` command in the directory containing `galasactl`. -If you have already added the Galasa CLI path to your shell's initialization file, as described in the [Installing the Galasa CLI](../docs/cli-command-reference/installing-cli-tool) topic, you should now be able to run the upgraded version of the Galasa CLI tool from any directory in your file system. +If you have already added the Galasa CLI path to your shell's initialization file, as described in the [Installing the Galasa CLI online](../docs/cli-command-reference/installing-cli-tool) topic, you should now be able to run the upgraded version of the Galasa CLI tool from any directory in your file system. -## Upgrading the Galasa zipped distribution using the command line +## Upgrading the Galasa zipped distribution using the command line (offline) -Download and extract the Galasa zip file to a directory of your choice and complete the following steps: +Download and extract the Galasa zip file to a directory of your choice and complete the steps documented in the [Installing the Galasa CLI offline](../docs/cli-command-reference/installing-offline) topic. -## Upgrading from using Eclipse to using the command line +## Upgrading from using Eclipse to using the command line (online) Version 0.31.0 is the last version of the Eclipse plug-in for Galasa that is produced and maintained by the Galasa Team. -You can work with later versions of Galasa by using the Galasa command line interface (CLI). The galasactl tool can do everything that the Eclipse tooling can do, and can be run from the command-line of any IDE, for example, the Eclipse terminal view. You can find out more about the Galasa command line tool (galasactl) in the [Getting started using the Galasa CLI](../docs/cli-command-reference/doc_root) topic. +You can work with later versions of Galasa by using the Galasa command line interface (CLI). The galasactl tool can do everything that the Eclipse tooling can do, and can be run from the command-line of any IDE, for example, the Eclipse terminal view. There is also a video about @@ -33,8 +33,8 @@ the Galasa command line tool that is available to watch on YouTube. Watch t To upgrade to a Galasa version that uses the CLI when your previous Galasa version was using Eclipse, complete the following steps: 1. Check that you have the software that you need installed by viewing the [CLI prerequisites](../docs/cli-command-reference/cli-prereqs) topic. -2. Complete the steps outlined in the [Installing the Galasa CLI](../docs/cli-command-reference/installing-cli-tool) topic to download and install the correct Galasa CLI binary file for your machine architecture. -3. Check that you have an OBR project for your test code. If not, you can create a project that uses the names that you want by using the `galasactl project create` command, and copying your test code into the correct places. For more information about the `galasactl project create` command, see the [Creating a Galasa project using the command line](../docs/writing-own-tests/setting-up-galasa-project) topic. +2. Complete the steps outlined in the [Installing the Galasa CLI online](../docs/cli-command-reference/installing-cli-tool) topic to download and install the correct Galasa CLI binary file for your machine architecture. +3. Check that you have an OBR project for your test code. If not, you can create a project that uses the names that you want by using the `galasactl project create` command, and copying your test code into the correct places. For more information about the `galasactl project create` command, see the [Creating a Galasa project](../docs/writing-own-tests/setting-up-galasa-project) topic. If you encounter any difficulties, reach out for help in our Galasa Slack workspace in the `#galasa-users` channel. @@ -81,4 +81,6 @@ To run a clean Maven install, run the ```mvn clean install ``` command from the To run a clean Gradle install, run the ```gradle clean build``` command from the command line. -If you are still having issues, you can force a full rebuild by deleting your *.m2* repository and creating a new build against your test projects and Managers by running a clean install. \ No newline at end of file +If you are still having issues, you can force a full rebuild by deleting your *.m2* repository and creating a new build against your test projects and Managers by running a clean install. + +You can also post a question in our Galasa Slack workspace. \ No newline at end of file diff --git a/src/markdown-pages/docs/writing-own-tests/binding-tests.md b/src/markdown-pages/docs/writing-own-tests/binding-tests.md index a3a1da4c..2cd70f6c 100644 --- a/src/markdown-pages/docs/writing-own-tests/binding-tests.md +++ b/src/markdown-pages/docs/writing-own-tests/binding-tests.md @@ -31,7 +31,7 @@ The test declares that a z/OS image is required for the test to run and that thi When the z/OS Manager reads the code, it creates a z/OS image by using the *imageTag* attribute to ascertain which set of properties from the `cps.properties` or `overrides.properties` file that it needs to load to create that image. -In this example, the following properties are associated with the *SIMBANK* z/OS image in the `overrides.properties` file, as described in the [Running the SimBank tests using the CLI](../../docs/running-simbank-tests-cli) documentation: +In this example, the following properties are associated with the *SIMBANK* z/OS image in the `overrides.properties` file, as described in the [Running the SimBank tests using the CLI](../cli-command-reference/running-simbank-tests-cli) documentation: ``` zos.image.SIMBANK.ipv4.hostname=127.0.0.1 zos.image.SIMBANK.telnet.port=2023 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 9870dbe1..eeba8ead 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 @@ -4,7 +4,7 @@ title: "Creating a Galasa project using the command line" --- -You can quickly and easily create a project structure to accommodate your own independent Galasa 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 quickly and easily create a project structure to accommodate your own independent Galasa tests in your local storage by using the Galasa command line interface (Galasa CLI) that is provided with Galasa. Use the following information 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. diff --git a/src/markdown-pages/docs/writing-own-tests/test-streams.md b/src/markdown-pages/docs/writing-own-tests/test-streams.md index d56f480f..c6b8d9b1 100644 --- a/src/markdown-pages/docs/writing-own-tests/test-streams.md +++ b/src/markdown-pages/docs/writing-own-tests/test-streams.md @@ -7,7 +7,7 @@ Galasa's ecosystem organises tests into _streams_. Test streams give you more op You can have as few or as many test streams as you wish. -A stream is a group of tests that you wish to run in automation represented by a single OBR (OSGi Bundle Repository) and its equivalent test catalog. Galasa uses an OBR to locate your tests in a Maven repository, along with all of the Managers that a test project requires. A test catalog is generated directly from the test source, is always up to date, and is what you would specify in the [Galasa CLI](/docs/cli-command-reference/cli-command-reference) to select tests to run in automation. +A stream is a group of tests that you wish to run in automation represented by a single OBR (OSGi Bundle Repository) and its equivalent test catalog. Galasa uses an OBR to locate your tests in a Maven repository, along with all of the Managers that a test project requires. A test catalog is generated directly from the test source, is always up to date, and is what you would specify in the Galasa CLI to select tests to run in automation. There are many ways to organise test streams: From 2f1989277571dd267051ec9f880391d9da2b41fa Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Wed, 13 Mar 2024 15:38:51 +0000 Subject: [PATCH 20/22] add reminder --- .../running-simbank-tests-cli-offline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md index 1db98a7b..a392fe0a 100644 --- a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md @@ -55,7 +55,7 @@ Remember to initialise your local environment by running the `galasactl local in You are now ready to run a local Galasa test offline with just the contents of the zipped distribution. -1. Open a terminal and run the SimBankIVT test locally by using the following command: +1. Open a terminal and run the SimBankIVT test locally by using the following example command, remembering to update the `--localMaven` flag value to the location of the `maven` directory that is provided as part of the _isolated.zip_ file that you downloaded: On Mac or Unix: ``` galasactl runs submit local --log - \ @@ -68,7 +68,7 @@ galasactl runs submit local --log - ` --obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr ` --class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven ``` -Note the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. +Note that the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. 1. The `SimBankIVT` test class runs, and the terminal displays its progress through to completion, with an Exit code of `0`. 1. View the results of the test runs in your terminal. You can also view results in the `run.log` file in the result archive store (RAS). 3270 terminal interactions can be viewed in the `artifacts` directory in the RAS. Find out more in the [Viewing test results locally](viewing-test-results-cli) documentation. From 005d7a538b920a9f5dbba3147d1036d4100da7b1 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 14 Mar 2024 11:20:10 +0000 Subject: [PATCH 21/22] review comment updates --- .../running-simbank-tests-cli-offline.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md index a392fe0a..1539a7ba 100644 --- a/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md +++ b/src/markdown-pages/docs/cli-command-reference/running-simbank-tests-cli-offline.md @@ -48,7 +48,7 @@ In order to run the Galasa SimBanks tests you need to add some configuration inf ## Running the SimBank IVT test class by using the CLI -The SimBank tests are located in the `maven` directory of the `isolated.zip` downloadable file. complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.32.0`. +The SimBank tests are located in the `maven` directory of the `isolated.zip` downloadable file. Complete the following steps to run the SimBankIVT test that is provided with Galasa. The following example uses SimBank OBR version `0.25.0`. Remember to initialise your local environment by running the `galasactl local init` command and to start the SimPlatform server by running the `run-simplatform.sh` script, as described in the `Launching SimBank` section in the [Exploring Galasa SimBank using the CLI offline](simbank-cli-offline) documentation. @@ -60,26 +60,29 @@ On Mac or Unix: ``` galasactl runs submit local --log - \ --obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr \ ---class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT \ +--localMaven file:////Users/youruserid/Downloads/isolated/maven ``` On Windows (Powershell): ``` galasactl runs submit local --log - ` --obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr ` ---class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT --localMaven file:////Users/youruserid/Downloads/isolated/maven +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.SimBankIVT ` +--localMaven file:////Users/youruserid/Downloads/isolated/maven ``` Note that the `--localMaven` flag refers to the `maven` directory inside the _isolated.zip_ as these are all the Maven artifacts that should be needed to run the test, including the `dev.galasa.simbank.obr` artifact which is passed to the `--obr` flag and the `SimBankIVT` test class which is passed to `class`. 1. The `SimBankIVT` test class runs, and the terminal displays its progress through to completion, with an Exit code of `0`. 1. View the results of the test runs in your terminal. You can also view results in the `run.log` file in the result archive store (RAS). 3270 terminal interactions can be viewed in the `artifacts` directory in the RAS. Find out more in the [Viewing test results locally](viewing-test-results-cli) documentation. -To run other SimBank tests, for example `BasicAccountCreditTest`, replace the test class name in the `--class` parameter. For example: +To run other SimBank tests, for example `BasicAccountCreditTest`, replace the test class name in the `--class` parameter. Remember to update the `--localMaven` flag value to the location of the `maven` directory as well. For example: On Mac or Unix: ``` galasactl runs submit local --log - \ --obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr \ ---class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest \ +--localMaven file:////Users/youruserid/Downloads/isolated/maven ``` On Windows (Powershell): @@ -87,7 +90,8 @@ On Windows (Powershell): ``` galasactl runs submit local --log - ` --obr mvn:dev.galasa/dev.galasa.simbank.obr/0.25.0/obr ` ---class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest +--class dev.galasa.simbank.tests/dev.galasa.simbank.tests.BasicAccountCreditTest ` +--localMaven file:////Users/youruserid/Downloads/isolated/maven ``` From 53854424e97654e4b47873548d1a5657e12bc4a5 Mon Sep 17 00:00:00 2001 From: Caroline McNamara Date: Thu, 14 Mar 2024 12:05:57 +0000 Subject: [PATCH 22/22] remove cmd --- .../docs/cli-command-reference/simbank-cli-offline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md index 2ef99c71..e3fc7976 100644 --- a/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md +++ b/src/markdown-pages/docs/cli-command-reference/simbank-cli-offline.md @@ -15,7 +15,7 @@ To start exploring the Galasa Simbank application and to run the sample SimBank 1. Start the Simplatform server by running the `run-simplatform.sh` script provided in the `isolated.zip`. 1. Navigate to the directory of the zipped distribution that you downloaded, for example, `~/Downloads/isolated`. A `run-simplatform.sh` script is available within the directory. This script starts the Simplatform server which is required to run the SimBank tests. - 1. Set execute permission on the script by running the `chmod +x run-simplatform.sh` command in the directory containing the `run-simplatform.sh` script. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `xattr -dr com.apple.quarantine run-simplatform.sh` command in the same directory. + 1. Set execute permission on the script by running the `chmod +x run-simplatform.sh` command in the directory containing the `run-simplatform.sh` script. 1. Run the script in server mode by using the following example command, remembering to set the `--location` flag to the location of the galasa-simplatform artefact in the `isolated.zip` file that you downloaded. For example, `~/Downloads/isolated/maven/dev/galasa`. ``` ./run-simplatform.sh --server --location ~/Downloads/isolated/maven/dev/galasa