diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0c4837fd..e89696d7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -249,6 +249,14 @@ jobs: run: ./gradlew --info libertyPackage working-directory: package-jar + - name: Publish with Gradle + if: ${{ github.ref == 'refs/heads/staging' || github.ref == 'refs/heads/next' }} + run: ./gradlew --info publish + working-directory: package-jar + env: + ORG_GRADLE_PROJECT_galasaNexusUsername: ${{ secrets.NEXUS_USERNAME }} + ORG_GRADLE_PROJECT_galasaNexusPassword: ${{ secrets.NEXUS_PASSWORD }} + - name: Upload JAR uses: actions/upload-artifact@v3 with: diff --git a/README.md b/README.md index 468e64bf..a6568036 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,13 @@ This repository contains the source for the Galasa test automation system homepage. If you are interested in the development of Galasa, take a look at the documentation and feel free to post a question in our Galasa Slack workspace. Register to join first if you're not yet a member. + +We have the following available Slack channels: + +- `#galasa-dev` - for developers of Galasa code or Galasa extensions +- `#galasa-users` - for users comments, and for making announcements +- `#galasa-tsc` - for technical steering committee discussions on longer term over-arching issues relating to Galasa + You can raise new ideas / features / bugs etc. as issues on [GitHub](https://github.com/galasa-dev/projectmanagement). ## Getting started diff --git a/gatsby-config.js b/gatsby-config.js index da8660fc..a53a0d0e 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -7,7 +7,7 @@ const consts = { githubRepoName: "galasa.dev", githubOrgName: "galasa-dev", twitterUrl: "", - slackUrl: "https://join.slack.com/t/galasa/shared_invite/zt-ele2ic8x-VepEO1o13t4Jtb3ZuM4RUA", + slackUrl: "https://openmainframeproject.slack.com/signup#/domain-signup", algolia: { appId: "0CBS2VLS6S", apiKey: "46b619eff7e9e3900835e17fc7aa880b", diff --git a/src/data/nav.yaml b/src/data/nav.yaml index bb90aa03..ca470d05 100644 --- a/src/data/nav.yaml +++ b/src/data/nav.yaml @@ -47,6 +47,8 @@ path: /docs/cli-command-reference/cli-runs-submit-local - title: Debugging a test locally path: /docs/cli-command-reference/cli-runs-local-debug + - title: Exploring Galasa SimBank using the CLI + path: /docs/cli-command-reference/simbank-cli - title: Running the SimBank tests using the CLI path: /docs/running-simbank-tests-cli - title: Viewing test results locally @@ -58,7 +60,7 @@ path: /docs/getting-started/installing-online - title: Installing the Galasa plug-in offline path: /docs/getting-started/installing-offline - - title: Exploring Galasa SimBank + - 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 @@ -101,6 +103,9 @@ path: /docs/ecosystem/installing/k8s - title: Test streams path: /docs/writing-own-tests/test-streams + - title: Managing integrated test runs + path: /docs/ecosystem/cps + - title: Selecting tests to run in the Ecosystem path: /docs/cli-command-reference/ecosystem-cli-runs-prepare - title: Running tests in the Ecosystem diff --git a/src/markdown-pages/docs/blogs/galasa-blog-template.md b/src/markdown-pages/docs/blogs/galasa-blog-template.md index a243074d..f6da06fc 100644 --- a/src/markdown-pages/docs/blogs/galasa-blog-template.md +++ b/src/markdown-pages/docs/blogs/galasa-blog-template.md @@ -42,7 +42,13 @@ Find out more about [describe and link to relevant content inside galasa.dev](/d Find out more about describe and link to content outside of galasa.dev -Got a question or a new idea? Join our Galasa Slack workspace where we discuss new features and provide support for each other. Register to join first if you're not yet a member. +Got a question or a new idea? Join our Galasa Slack workspace where we discuss new features and provide support for each other. Register to join first if you're not yet a member. + +We have the following available Slack channels: + +- `#galasa-dev` - for developers of Galasa code or Galasa extensions +- `#galasa-users` - for users comments, and for making announcements +- `#galasa-tsc` - for technical steering committee discussions on longer term over-arching issues relating to Galasa Want to start contributing? Check out the [Contributing to Galasa guidelines](https://github.com/galasa-dev/projectmanagement/blob/main/contributing.md) to propose fixes, add new features or improve the software and documentation. diff --git a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md index c12421cc..274a3504 100644 --- a/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md +++ b/src/markdown-pages/docs/cli-command-reference/cli-command-reference.md @@ -4,7 +4,21 @@ 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 tool (Galasa CLI) to interact with Galasa to complete tasks, for example, to create Galasa projects, submit tests to an ecosystem, view test results and download test artifacts. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. + +If you are installing Galasa for using in the command-line, you can use the Galasa command line interface tool (Galasa CLI) to interact with Galasa to complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. + +Read on to understand more about the prerequisites that you need to install so that you can start using the Galasa CLI. + + +## Prerequisites + +| Software | Description | +| :---- | :-------- | +| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | +| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.8.x and later. | +| 3270 emulator | Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to explore Galasa Simbank, a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.| + + ## Next steps 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 1848b38e..fbab3005 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 @@ -3,16 +3,10 @@ path: "/docs/cli-command-reference/installing-cli-tool" title: "Installing the Galasa CLI" --- -This section provides details about prerequisite software requirements and information about how to download and install the Galasa command line interface tool (Galasa CLI) on your local machine. -## Prerequisites +This section provides details about how to download and install the Galasa command line interface tool (Galasa CLI) on your local machine and tells you a little bit about getting started with the Galasa CLI commands. -| Software | Description | -| :---- | :-------- | -| Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | -| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle 6.x releases. | -| 3270 emulator | Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to explore Galasa Simbank, a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.| ## Downloading the Galasa CLI @@ -21,14 +15,14 @@ To install Galasa for using in the command-line you first need to download the b The following versions of the Galasa CLI are available to download for different operating systems and machine architectures: -| Operating system | Download | -| :---- | :-------- | -| MacOSX | galasactl-darwin-x86_64 | -| MacOSX | galasactl-darwin-arm64 | -| Linux 64-bit x86 | galasactl-linux-x86_64 | -| Linux arm64 | galasactl-linux-arm64 | -| zLinux | galasactl-linux-s390x | -| Windows | galasactl-windows-x86_64.exe | +| 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 | ## Installing the Galasa CLI @@ -41,7 +35,7 @@ On Mac or Unix: 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 `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command. +5. If you are using a Mac, you can set permission to open the Galasa CLI tool by running the `sudo spctl --add 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. @@ -135,6 +129,38 @@ export PATH="/opt/homebrew/opt/gradle@6/bin:$PATH" gradle --version | grep "Gradle" | cut -f2 -d' ' ``` +## About Galasa CLI commands + +Galasa CLI commands start with `galasactl`. Example commands are provided for running on Mac or Unix, and Windows Powershell. The Windows Powershell uses the backtick (`) for line continuation characters. If you are using Windows command-shell, the line continuation character is the caret (^). + +You can view the Galasa CLI command syntax, including parameter descriptions, in the cli repository in GitHub. + + +## Known limitations + +Go programs can sometimes struggle to resolve DNS names, especially when a working over a virtual private network (VPN). In such situations, you might notice that a bootstrap file cannot be found with galasactl, but can be found by a desktop browser, or curl command. In such situations you can manually add the host detail to the `/etc/hosts` file, to avoid DNS being involved in the resolution mechanism. + + +## Getting help + +Once you have installed the Galasa CLI, you can use the following command to get more information about the command and command options, including default values. + +``` +galasactl --help +``` + +Use the `--log` option to send logging information to a file. Any folder that is referenced must exist. Existing files are overwritten. Specify `-` to log to `stderr`. The default is no logging. + +``` +galasactl --log +``` + +## Errors + +You can view a list of error messages that can be generated by the galasactl tool in the Galasa cli repository in GitHub. + + + ## Next steps Read the [Initialising your local environment](/docs/initialising-home-folder) documentation to help you to set up some basic file structures and files in your home folder so that you can start using Galasa. diff --git a/src/markdown-pages/docs/cli-command-reference/simbank-cli.md b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md new file mode 100644 index 00000000..83a15152 --- /dev/null +++ b/src/markdown-pages/docs/cli-command-reference/simbank-cli.md @@ -0,0 +1,116 @@ +--- +path: "/docs/cli-command-reference/simbank-cli" +title: "Exploring Galasa SimBank using the CLI" +--- +Distributed with Galasa, SimBank is a component that simulates a mainframe application. It sits above another component called SimPlatform. 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 +SimBank applications and a set of sample SimBank tests are located in the Galasa simplatform repository in GitHub. +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. Clone the Galasa `simplatform` repository on your machine by running the following command in a terminal in the directory on your local machine in which you want to clone the repository files: + ``` + git clone https://github.com/galasa-dev/simplatform.git + ``` +1. Run the `./build-locally.sh` script to build the code. +1. Run the `./run-locally.sh --server` script to start the simbank server inside a local JVM. +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. + +4. The SimBank process has been launched, and is listening on port *2023* for Telnet connections, on port *2080* for web services connections and on port *2027* for Derby SQL connections. Neither web services or Derby connections are explored further in this section. + +## Manually exploring the SimBank application +When you launch SimBank, its banking application listens on port 2023 for incoming client Telnet connections, offering an opportunity to first connect to it manually to review and understand the (simulated) transactions it supports, before subjecting it to Galasa's provided tests. + +### Logging in to the simulated application +1. With the *Galasa SimBank* component still running, configure your 3270 terminal emulator to access port *2023* of *localhost* (or IP address 127.0.0.1 if the *localhost* alias has not been set up) via the Telnet protocol. No SSL configuration is required. +1. Connect to the listening Telnet service with your 3270 emulator and review the logon screen: + + ![SimBank logon screen](../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](../running-simbank-tests) in the side-menu. \ No newline at end of file diff --git a/src/markdown-pages/docs/community.md b/src/markdown-pages/docs/community.md index 3b8beac3..cf16ac1e 100644 --- a/src/markdown-pages/docs/community.md +++ b/src/markdown-pages/docs/community.md @@ -5,10 +5,18 @@ title: "Get involved" Galasa thrives on users’ collaboration, contributions and creativity and we invite you to share your skills and ideas at all levels. -Join our Galasa Slack workspace where we discuss new features and provide support for each other. Register to join first if you're not yet a member. - Check out the [Contributing to Galasa guidelines](https://github.com/galasa-dev/projectmanagement/blob/main/contributing.md) to propose fixes, add new features or improve the software and documentation. +Join our Galasa Slack workspace where we discuss new features and provide support for each other. Register to join first if you're not yet a member. + +We have the following available Slack channels: + +- `#galasa-dev` - for developers of Galasa code or Galasa extensions +- `#galasa-users` - for users comments, and for making announcements +- `#galasa-tsc` - for technical steering committee discussions on longer term over-arching issues relating to Galasa + + + diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md index 64a31561..f6003e32 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md @@ -96,21 +96,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.29.0, run the following command: +To upgrade the Galasa Ecosystem to use a newer version of Galasa, for example version 0.30.0, run the following command: On Mac or Unix: ``` helm upgrade galasa/ecosystem --reuse-values \ ---set galasaVersion=0.29.0 --wait +--set galasaVersion=0.30.0 --wait ``` On Windows (Powershell): ``` helm upgrade galasa/ecosystem --reuse-values ` ---set galasaVersion=0.29.0 --wait +--set galasaVersion=0.30.0 --wait ``` where:
diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md index 68c0e1d7..3d6496d2 100644 --- a/src/markdown-pages/docs/ecosystem/ecosystem-installing.md +++ b/src/markdown-pages/docs/ecosystem/ecosystem-installing.md @@ -39,7 +39,7 @@ The following server is not required by the ecosystem but is automatically deplo | ----------- | ----------- |----------- | | SimPlatform| Provides an instance of SimBank so that IVTs and demonstration pipelines can be run |2023, 2027, 2080, 2040 | -To use SimPlatform, you need to have access to Maven Central. Chat to us on our Galasa Slack workspace if you need help with this. +To use SimPlatform, you need to have access to Maven Central. Chat to us on our Galasa Slack workspace if you need help with this. ## Installing the Galasa Ecosystem on the Docker engine @@ -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.29.0 +version: 0.30.0 engineController: - controllerVersion: 0.29.0 - engineVersion: 0.29.0 + controllerVersion: 0.30.0 + engineVersion: 0.30.0 simplatform: version: 0.15.0 ``` diff --git a/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md new file mode 100644 index 00000000..28f4f5f8 --- /dev/null +++ b/src/markdown-pages/docs/ecosystem/ecosystem-manage-cps.md @@ -0,0 +1,165 @@ +--- +path: "/docs/ecosystem/cps" +title: "Managing integrated test runs" +--- + +[Retrieving properties](#retrieving)
+[Setting properties](#setting)
+[Deleting properties](#deleting)
+ + +Integration testing can be complicated. Tests often require configuration parameters to bind to a specific test environment. Galasa Managers require configuration so that systems under test can be contacted. Credentials for systems need to be supplied to tests and Managers to enable connections. The organisation of these parameters must be centralised if tests are to be run in automation. + +To address these challenges, Galasa uses a Configuration Property Store (CPS) as part of the core Galasa framework. The CPS holds all the configuration values, so that the Galasa framework, Ecosystem, Managers, and individual tests can use the CPS to retrieve configuration information. + +A video - The Galasa Configuration Property Store - is available on the Galasa YouTube channel. Watch the video to find out more about the features of the Galasa CPS, and to see a demonstration on how to manipulate CPS property values by using the Galasa command line tool. + +## Simplifying test configuration with the CPS + +When running Galasa tests locally, using the command line tool or Eclipse, the CPS is stored in the flat file `{GALASA_HOME}/cps.properties`. + +When running tests in the Galasa Ecosystem, where tests are run on a Kubernetes cluster, a REST service hosts the storage of the CPS properties in a central location. A centralised CPS means that configuration information can be supplied to all automated tests running in a Galasa Ecosystem, allowing multiple tests to run using the same shared configuration information. + +You can set, retrieve and delete properties that are held in the CPS by using the `galasasctl properties` commands. The ability to manage these properties directly makes it easier for testers to set parameters and credentials on the Ecosystem for tests to read and use at runtime. System administrators can use the CLI to set Ecosystem-wide configuration properties after Ecosystem installation. + + +## About the Configuration Properties Store + +The CPS is a key-value pair store. Properties in the CPS are dot-separated values with lower and upper-case segments that define, for example, endpoint, port, and repository properties. These properties control how a Galasa test runs. It is the CPS and the configuration properties that enable tests to run against multiple environments, without changing the code inside the test. + +Naming conventions are used to maintain order in the properties which are stored in the CPS. If a property in the CPS consists of a prefix, suffix, and a variable infix, then the prefix and suffix are lower-case, and the infix part of the property name is upper-case, to indicate that it is variable in nature. This convention allows the CPS to group names together and for easy searching and lookup by tests, Managers and users alike. Properties can be searched by using the prefix, suffix and a list of possible infixes. + +Namespaces are used to group properties together within the CPS. Namespaces help to restrict the values that can be drawn from the CPS. For example, test cases draw values only from the `test` namespace. The Galasa framework draws values from the `framework` namespace, for example, the location of the Credentials Store and the Dynamic Status Store. Managers also provide their own configuration properties, for example, the configuration properties of the Docker Manager are held in the `docker` namespace. The `--namespace` flag is mandatory for all `galasasctl properties` commands. + + +## Managing CPS properties + +Use the `galasasctl properties get`, `galasasctl properties set`, and `galasasctl properties delete` commands to dynamically manage CPS properties. These Galasa CLI commands make it easy to ensure that the appropriate properties and credentials are installed in the Ecosystem for automated tests to query and use. + +The example commands that are provided in the following sections assume that the `GALASA_BOOTSTRAP` environment variable is set, so the `--bootstrap` flag is not required in the command. + +## Retrieving properties from a namespace + +Use the `galasactl properties get` command to read CPS properties and values from a specified namespace in the Galasa Ecosystem to verify that the properties exist and are set correctly. You can filter the properties that are returned by using the property name (to return a single property), or by using the prefix, suffix, and infix flags to return a subset of properties that match the provided criteria. + + + +### Retrieve all properties from a namespace + +To retrieve all properties that are stored in the `framework` namespace, use the following command:

+`galasactl properties get --namespace framework` + + +### Retrieve a single property from a namespace + +To retrieve a specific property from the `framework` namespace, specify the property name in the command by using the `-–name` flag. For example, to retrive the credentials store property use the following command: + +```galasactl properties get --namespace framework --name credentials.store``` + + +*Note:* The `-–name` flag cannot be used in conjunction with the `-–prefix`, `--suffix`, or `-–infix` flags. + +### Retrieve a subset of properties in a namespace + +To filter the properties that are returned, without specifying the property name, use the `–-prefix`, `–-suffix`, and ``--infix`` flags. You can specify more than one `--infix` value by using a comma separated list. For example, to return properties in the `docker` namespace that start with `engine`, end with `hostname`, and contain `LOCAL` or `REMOTE` use the following command: + + +On Mac and Unix: + +``` +galasactl properties get \ +--namespace docker --prefix engine --suffix hostname --infix LOCAL,REMOTE +``` + +On Windows (Powershell): + +``` +galasactl properties get ` +--namespace docker --prefix engine --suffix hostname --infix LOCAL,REMOTE +``` + + +The `--prefix`, `--suffix` and `-–infix` flags can be used together or separately to retrieve all properties that match the provided criteria. + + +For a complete list of supported parameters see the galasactl properties get documentation in the cli repository. + + +### Returned properties + + +Properties are returned in summary format. For example: + +``` +namespace name value +docker engine.LOCAL.hostname 127.0.0.1 +docker engine.REMOTE.hostname 103.67.89.6 + +Total: 2 +``` + + +## Setting properties in a namespace + +You can update a property and its value in a namespace by using the `galasactl properties set` command. If the property does not exist in that namespace, the command creates the property. You must provide the namespace, the name of the property, and the value of the property in the command in the following example format: + +```galasactl properties set --namespace namespace --name name --value value``` + +where: + + - `namespace` is the namespace in which the property is stored + - `name` is the name of the property + - `value` is the property value + +A success message is displayed when the property is updated or created. + +For a complete list of supported parameters see the galasactl properties set documentation in the cli repository. + +### Examples of setting properties in a namespace + +The [WebAppIntegrationTest](../running-simbank-tests/web-app-integration-test) documentation is designed to help you to understand how to set the properties that enable a local test to run in a Galasa Ecosystem. + +For example, the following CPS properties are set for the Docker Manager when running the `WebAppIntegrationTest` locally: + +``` +docker.dse.engine.PRIMARY=LOCAL +docker.default.engines=LOCAL +docker.engine.LOCAL.hostname=127.0.0.1 +docker.engine.LOCAL.port=2375 +docker.engine.LOCAL.max.slots=10 +``` + +The first component, `docker` indicates the namespace. The upper-case components are used to show which part of the property is dynamic, while the lower case is used to define the static parts. + +You can use the `galasactl properties set` command to update these properties so that the test can run in the Ecosystem. To use a remote server as a Docker Engine, simply change the default engine from LOCAL to REMOTE and specify the appropriate connection details. No change is required to the test code, only to the CPS properties file. + +For example, to change the value of the properties in the `docker` namespace, use the following example commands: + +``` +galasactl properties set --namespace docker --name dse.engine.PRIMARY --value REMOTE +galasactl properties set --namespace docker --name default.engines --value REMOTE +galasactl properties set --namespace docker --name engine.REMOTE.hostname --value 103.67.89.6 +galasactl properties set --namespace docker --name engine.REMOTE.port --value 2987 +galasactl properties set --namespace docker --name engine.REMOTE.max.slots --value 20 +``` + + +## Deleting properties from a namespace + +You can delete a property and its associated value in a namespace by using the `galasactl properties delete` command. You must provide the namespace and the name of the property that you want to delete. For example: + +```galasactl properties delete --namespace namespace --name name``` + +where: + + - `namespace` is the namespace that contains the property to delete + - `name` is the name of the property you want to delete + + + +A success message is displayed when the property is deleted. + +For a complete list of supported parameters see the galasactl properties delete documentation in the cli repository. + + + diff --git a/src/markdown-pages/docs/first-steps/installing-offline.md b/src/markdown-pages/docs/first-steps/installing-offline.md index 98757de4..fc97c61e 100644 --- a/src/markdown-pages/docs/first-steps/installing-offline.md +++ b/src/markdown-pages/docs/first-steps/installing-offline.md @@ -3,10 +3,9 @@ path: "/docs/getting-started/installing-offline" title: "Installing the Galasa plug-in offline" --- -The Galasa _isolated.zip_ file is available from the https://resources.galasa.dev/ site and can be downloaded and extracted to a directory of your choice. The zip file contains three directories (eclipse, maven and javadoc), an `isolated.tar` file and a `docs.jar` file. +The 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 four directories (galasactl, eclipse, maven, and javadoc), an `isolated.tar` file and a `docs.jar` file. -The `eclipse` directory contains the Galasa plug-in, and the `maven` directory contains dependencies that are required for building Galasa tests. The `javadoc`` - directory contains the Javadoc API documentation for the Galasa Managers. +The `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 `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. @@ -29,7 +28,7 @@ Depending on how you use Galasa, there are several software prerequisites, some | Software | Description | | :---- | :-------- | | Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | -| Gradle | Required to install the zipped distribution. You can also build Galasa projects using Gradle (or you can use Maven to build projects if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.8.x and later. If you are using Eclipse, you do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | +| Gradle | Required to install the zipped distribution. You can also build Galasa projects using Gradle (or you can use Maven to build projects if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.9.x. If you are using Eclipse, you do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration.| | Eclipse | Required. Provides the ability to interact with and use Galasa. See [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | | Docker | Required if using the Docker image. If you want to deploy the Docker image that is provided in the zip file, you will need to have Docker installed. | | Maven | Optional (as Gradle is required). You can use Maven rather than Gradle to build Galasa projects. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. | diff --git a/src/markdown-pages/docs/first-steps/installing-online.md b/src/markdown-pages/docs/first-steps/installing-online.md index 5350e448..ae64350a 100644 --- a/src/markdown-pages/docs/first-steps/installing-online.md +++ b/src/markdown-pages/docs/first-steps/installing-online.md @@ -19,7 +19,7 @@ Depending on how you plan to use Galasa, there are several software prerequisite | :---- | :-------- | | Java JDK | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. | | Eclipse | Required. Provides the ability to interact with and use Galasa. See the [Getting started using Eclipse](/docs/getting-started) documentation for more information about installation requirements. | -| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. If you are using Eclipse, you do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. All Galasa versions are compatible with Gradle releases 6.8.x and later.| +| Maven or Gradle | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. If you are using Eclipse, you do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. All Galasa versions are compatible with Gradle releases 6.9.x.| | 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.| diff --git a/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md index 1e3a5eac..3735f183 100644 --- a/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md +++ b/src/markdown-pages/docs/first-steps/setting-up-galasa-project-eclipse.md @@ -26,7 +26,6 @@ The Gradle project structure looks somewhat different to the Maven structure bec The `build.gradle` files declare any dependencies that the test code has, and specify the Maven co-ordinates to use when publishing to a Maven repository. The `bnd.bnd` files define the OSGi Bundles for the test projects and any Managers in the project and the `settings.gradle` file tells Gradle where to look for the dependencies and plug-ins that are required to build the project. -All Galasa versions are compatible with Gradle releases 6.8.x and later. ## Before you start diff --git a/src/markdown-pages/docs/first-steps/simbank.md b/src/markdown-pages/docs/first-steps/simbank.md index f21ff63e..0117a3b1 100644 --- a/src/markdown-pages/docs/first-steps/simbank.md +++ b/src/markdown-pages/docs/first-steps/simbank.md @@ -57,7 +57,7 @@ When you launch SimBank, its banking application listens on port 2023 for incomi 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](../first-steps/simbank-banktest.png) + ![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 @@ -65,12 +65,12 @@ When you launch SimBank, its banking application listens on port 2023 for incomi 6. Press PF1: - ![CICS home screen](../first-steps/simbank-cics.png) + ![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](../first-steps/simbank-mainmenu.png) + ![Main banking menu](simbank-mainmenu.png) As you have been progressing through this process, Eclipse has been logging selected events to its console: @@ -88,7 +88,7 @@ This is an example of log output that can be useful when running tests. 1. Press TAB until the cursor is in the `Account Number` field, enter `123456789` and press ENTER. The account details are populated and it is apparent that account number 123456789 is 56.72 in credit. - ![Account balance](../first-steps/simbank-balance.png) + ![Account balance](simbank-balance.png) 1. Press PF3 to return to the account menu screen. @@ -98,7 +98,7 @@ This is an example of log output that can be useful when running tests. 1. Press TAB until the cursor is in the `Transfer to Account Number` field and enter `987654321`. 1. Press TAB until the cursor is in the `Transfer Amount` field and enter `1` - ![Inter-account transfer](../first-steps/simbank-transfer.png) + ![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: diff --git a/src/markdown-pages/docs/galasa-hub.md b/src/markdown-pages/docs/galasa-hub.md index 8af44637..c28c1e8f 100644 --- a/src/markdown-pages/docs/galasa-hub.md +++ b/src/markdown-pages/docs/galasa-hub.md @@ -5,6 +5,13 @@ title: "Galasa Blogs" Stay up-to-date with all things Galasa with blogs, podcasts and videos from fellow Galasians. +## Video: The Galasa Configuration Property Store +Integration testing can be complicated. Tests often require configuration parameters to bind to a specific test environment. Galasa Managers require configuration so that systems under test can be contacted. This information needs to stored in a single, central repository that is shareable to the Galasa framework, Ecosystem, Managers and tests. Find out how Galasa solves these challenges by its use of the Configuration Property Store (CPS). Watch the video to understand the features of the Galasa CPS, and see a demonstration on manipulating the values in a CPS by using the Galasa command line (Galasa CLI). Use the information to help you to simplify your test configuration, set Ecosystem-wide configuration properties, and set parameters and credentials on the Ecosystem for tests to read and use at runtime.
+ +**Author: Mike Cobbett, Savaas Kyriacou, October 25 2023**
+*Source: YouTube*

+ + Watch the video ## Press release: Open Mainframe Project Welcomes Galasa into its Ecosystem The Open Mainframe Project, an open-source initiative that enables collaboration across the mainframe community to develop shared tool sets and resources, today welcomed Galasa, a project that offers developers the ability to test applications at scale regardless of platform, into its ecosystem.
@@ -55,7 +62,7 @@ Galasa's open source automation framework enables mainframe developers to automa **Author: Matthew Cousens, & Will Yates, April 9, 2021**
*Source: IBM Developer*

- + Watch the video ## Redpaper: Integration testing for Hybrid Cloud Applications using Galasa diff --git a/src/markdown-pages/docs/manager-groups/zos-manager-group.md b/src/markdown-pages/docs/manager-groups/zos-manager-group.md index 4e6f47e8..ecd71d4e 100644 --- a/src/markdown-pages/docs/manager-groups/zos-manager-group.md +++ b/src/markdown-pages/docs/manager-groups/zos-manager-group.md @@ -5,7 +5,7 @@ title: "z/OS Managers" Name | Description | | :-------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **[RSE API Manager](/docs/managers/rse-api-manager)**
![alpha](../../../images/alpha.svg) | Provides tests and Managers with access to RSE API functions. | +| **[RSE API Manager](/docs/managers/rse-api-manager)**
![alpha](../../../images/alpha.svg) | Provides tests and Galasa Managers with access to RSE API functions. | | **[z/OS 3270 Manager](/docs/managers/zos3270terminal-manager)**
![beta](../../../images/beta.svg) | Provides tests and Managers with a 3270 client. | | **[z/OS Batch z/OS MF Manager](/docs/managers/z-os-batch-z-os-mf-manager)**
![beta](../../../images/beta.svg) | Provides the default implementation of the z/OS Batch Manager using z/OS MF. Can only be used via the z/OS Batch Manager interface. | | **[z/OS Batch RSE API Manager](/docs/managers/z-os-batch-rse-api-manager)**
![alpha](../../../images/alpha.svg) | Provides an implementation of the z/OS Batch Manager using the RSE API. Can only be used via the z/OS Batch Manager interface. | diff --git a/src/markdown-pages/docs/support.md b/src/markdown-pages/docs/support.md index 003bc013..e4052f60 100644 --- a/src/markdown-pages/docs/support.md +++ b/src/markdown-pages/docs/support.md @@ -6,11 +6,17 @@ title: "Support" If you find any problems whilst you’re using Galasa, get in touch and get the help you need: - Search our project management repository on GitHub; perhaps someone has already had a similar issue and solved it. -- Post a question in our Galasa Slack workspace. Register to join first if you're not yet a member. - If you have an error message or java stack trace exception, feel free to raise an issue in the project management repository and the Galasa community will get back to you as soon as possible. +- Post a question in our Galasa Slack workspace. Register to join first if you're not yet a member. We have the following available Slack channels: + + - `#galasa-dev` - for developers of Galasa code or Galasa extensions + - `#galasa-users` - for users comments, and for making announcements + - `#galasa-tsc` - for technical steering committee discussions on longer term over-arching issues relating to Galasa + + If your issue requires a code change, the community will do their best to respond and fix the problem as soon as they can. Depending on the severity of the issue, the fix might be scheduled for a future release of Galasa. Alternatively, the fix might be back ported to the current release. Naturally this is always a community decision and your input is just as important. If you want to have a go at fixing the defect yourself, let us know and we will help you to try and fix the issue. -We are open to suggestions about more formal support, come and talk to us - we would love to hear from you. \ No newline at end of file +We are open to suggestions about more formal support, come and talk to us - we would love to hear from you. diff --git a/src/markdown-pages/highlights.md b/src/markdown-pages/highlights.md index cf2f184e..799ed50b 100644 --- a/src/markdown-pages/highlights.md +++ b/src/markdown-pages/highlights.md @@ -7,14 +7,34 @@ title: "Highlights" 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. -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. +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. + +We have the following available Slack channels: + +- `#galasa-dev` - for developers of Galasa code or Galasa extensions +- `#galasa-users` - for users comments, and for making announcements +- `#galasa-tsc` - for technical steering committee discussions on longer term over-arching issues relating to Galasa 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.29.0 - Release Highlights +## 0.30.0 - Release Highlights + +- You can now read, update, and delete CPS properties by using the CLI, removing the need to directly access the etcd server or use the REST service. The `galasactl properties set` command makes it easy to set parameters and credentials in the Ecosystem for tests to read and use at runtime. Use the `galasactl properties get` command to read CPS properties and the `galasactl properties delete` to remove CPS properties from a namespace in the Ecosystem. +- The following REST API endpoints will be deprecated in the next release (0.31.0) as these are replaced by new endpoints delivered in this release:

+ /cps/namespace/{namespace}/property/{property}
+ /cps/namespace/{namespace}/prefix/{prefix}/suffix/{suffix}
+ /cps/namespace/{namespace}
+ /cps/namespace
+- The `--requestor` parameter is removed from the `galasactl runs submit local` and `galasactl runs submit` commands. The `--requestor` parameter is always set to the current user id, removing the ability to artifically set who is running the test. +- Various documentation updates and enhancements. + + +
+0.29.0 - Release Highlights - Upgrade of 'bouncy castle' crypto libraries to remove a security vulnerability. +
0.28.0 - Release Highlights diff --git a/src/pages/index.js b/src/pages/index.js index bdb69415..d7cec8fe 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -126,7 +126,7 @@ const IndexPage = () => ( Learn more