fix(uiVeri5): update documentation for more explicit deprecation notes (#2568)

* use strings.Join() for string slice

* add explanaiton to script passing in extensions

* add note about groovy templating

* remove single quotes from seleniumAddress default

* updated documentation

Co-authored-by: Oliver Nocon <33484802+OliverNocon@users.noreply.github.com>

cmd/uiVeri5ExecuteTests.go

@@ -43,7 +43,7 @@ func runUIVeri5(config *uiVeri5ExecuteTestsOptions, command command.ExecRunner)
 		return errors.Errorf("parameter testOptions no longer supported, please use runOptions parameter instead.")
 	}
 	if err := command.RunExecutable(config.RunCommand, config.RunOptions...); err != nil {
-		return errors.Wrapf(err, "failed to execute run command: %v %v", config.RunCommand, config.RunOptions)
+		return errors.Wrapf(err, "failed to execute run command: %v %v", config.RunCommand, strings.Join(config.RunOptions, " "))
 	}
 	return nil
 }

cmd/uiVeri5ExecuteTests_generated.go

@@ -80,7 +80,7 @@ func UiVeri5ExecuteTestsCommand() *cobra.Command {
 func addUiVeri5ExecuteTestsFlags(cmd *cobra.Command, stepConfig *uiVeri5ExecuteTestsOptions) {
 	cmd.Flags().StringVar(&stepConfig.InstallCommand, "installCommand", `npm install @ui5/uiveri5 --global --quiet`, "The command that is executed to install the uiveri5 test tool.")
 	cmd.Flags().StringVar(&stepConfig.RunCommand, "runCommand", `/home/node/.npm-global/bin/uiveri5`, "The command that is executed to start the tests.")
-	cmd.Flags().StringSliceVar(&stepConfig.RunOptions, "runOptions", []string{`--seleniumAddress='http://localhost:4444/wd/hub'`}, "Options to append to the runCommand, last parameter has to be path to conf.js (default if missing: ./conf.js).")
+	cmd.Flags().StringSliceVar(&stepConfig.RunOptions, "runOptions", []string{`--seleniumAddress=http://localhost:4444/wd/hub`}, "Options to append to the runCommand, last parameter has to be path to conf.js (default if missing: ./conf.js).")
 	cmd.Flags().StringVar(&stepConfig.TestOptions, "testOptions", os.Getenv("PIPER_testOptions"), "Deprecated and will result in an error if set. Please use runOptions instead.")
 	cmd.Flags().StringVar(&stepConfig.TestServerURL, "testServerUrl", os.Getenv("PIPER_testServerUrl"), "URL pointing to the deployment.")
 

cmd/uiVeri5ExecuteTests_test.go

@@ -41,7 +41,7 @@ func TestRunUIVeri5(t *testing.T) {
 	})
 
 	t.Run("error case run command", func(t *testing.T) {
-		wantError := "failed to execute run command: fail uiveri5 [testParam]: error case"
+		wantError := "failed to execute run command: fail uiveri5 testParam: error case"
 
 		opts := &uiVeri5ExecuteTestsOptions{InstallCommand: "npm install ui5/uiveri5", RunCommand: "fail uiveri5", RunOptions: []string{"testParam"}}
 

documentation/docs/extensibility.md

@@ -32,7 +32,7 @@ For this, you need to know the technical identifiers for stage names.
 The centrally maintained pipeline checks if such a file exists and if it does, executes it.
 A parameter of type `Map` that contains the following keys is passed to the extension:
 
-* `script`: Defines the global script environment of the `Jenkinsfile` run. This makes sure that the correct configuration environment can be passed to project "Piper" steps and allows access to the `commonPipelineEnvironment`, for example.
+* `script`: Defines the global script environment of the `Jenkinsfile` run. This makes sure that the correct configuration environment can be passed to project "Piper" steps and allows access to the `commonPipelineEnvironment`, for example. When calling a piper step in an extension, the script object has to be passed using `script: params.script`.
 * `originalStage`: Allows you to execute the "original" stage at any place in your script. If omitting a call to `originalStage()`, only your code is executed.
 * `stageName`: Name of the current stage
 * `config`: Configuration of the stage and general config (including all defaults)

documentation/docs/steps/uiVeri5ExecuteTests.md

@@ -1,5 +1,8 @@
 # ${docGenStepName}
 
+!!! warning "Deprecation notice"
+    Details of changes after the step migrated to a golang based step can be found [below](#exceptions).
+
 ## ${docGenDescription}
 
 ## Prerequisites
@@ -12,12 +15,21 @@
 
 ## Exceptions
 
-The parameter `testOptions` is deprecated and is replaced by `runOptions`.
+The parameter `testOptions` is deprecated and is replaced by array type parameter `runOptions`. Groovy templating for this parameter is deprecated and no longer supported.
 
-Using the `runOptions` parameter the 'seleniumAddress' for uiveri5 can be set. For jenkins on kubernetes the host is 'localhost', in other environments, e.g. native jenkins installations, the host can be set to 'selenium'.
+Using the `runOptions` parameter the 'seleniumAddress' for uiveri5 can be set.
+The former groovy implementation included a default for seleniumAddress in the runCommand. Since this is not possible with the golang-based implementation, the seleniumAddress has to be added to the runOptions. For jenkins on kubernetes the host is 'localhost', in other environments, e.g. native jenkins installations, the host can be set to 'selenium'.
+
+```yaml
+runOptions: ["--seleniumAddress=http://localhost:4444/wd/hub", ..... ]
+```
+
+The parameter `failOnError` is no longer supported on the step due to strategic reasons of pipeline resilience. To achieve the former behaviour with `failOnError: false` configured, the step can be wrapped using try/catch in your custom pipeline script.
+
+The `installCommand` does not support queueing shell commands using `&&` and `|` operator any longer.
 
 If you see an error like `fatal: Not a git repository (or any parent up to mount point /home/jenkins)` it is likely that your test description cannot be found.<br />
-Please make sure to point parameter `runOptions` to your `conf.js` file like `runOptions: ['./path/to/my/tests/conf.js']`
+Please make sure to point parameter `runOptions` to your `conf.js` file like `runOptions: [...., './path/to/my/tests/conf.js']`
 
 ## Examples
 

resources/metadata/uiVeri5ExecuteTests.yaml

@@ -36,7 +36,7 @@ spec:
       - name: runOptions
         type: "[]string"
         description: "Options to append to the runCommand, last parameter has to be path to conf.js (default if missing: ./conf.js)."
-        default: ["--seleniumAddress='http://localhost:4444/wd/hub'"]
+        default: ["--seleniumAddress=http://localhost:4444/wd/hub"]
         scope:
           - PARAMETERS
           - STAGES