From 6d7205377cdb039bf3c01c8994158b311c68852a Mon Sep 17 00:00:00 2001 From: Christopher Fenner Date: Wed, 13 Mar 2019 12:01:05 +0100 Subject: [PATCH] generate karma docs (#555) --- documentation/docs/steps/karmaExecuteTests.md | 72 ++----------------- vars/karmaExecuteTests.groovy | 54 +++++++++++--- 2 files changed, 49 insertions(+), 77 deletions(-) diff --git a/documentation/docs/steps/karmaExecuteTests.md b/documentation/docs/steps/karmaExecuteTests.md index 11015922a..ba7b16a55 100644 --- a/documentation/docs/steps/karmaExecuteTests.md +++ b/documentation/docs/steps/karmaExecuteTests.md @@ -2,82 +2,20 @@ ## Description -In this step the ([Karma test runner](http://karma-runner.github.io)) is executed. - -The step is using the `seleniumExecuteTest` step to spins up two containers in a Docker network: - -- a Selenium/Chrome container (`selenium/standalone-chrome`) -- a NodeJS container (`node:8-stretch`) - -In the Docker network, the containers can be referenced by the values provided in `dockerName` and `sidecarName`, the default values are `karma` and `selenium`. These values must be used in the `hostname` properties of the test configuration ([Karma](https://karma-runner.github.io/1.0/config/configuration-file.html) and [WebDriver](https://github.com/karma-runner/karma-webdriver-launcher#usage)). - -!!! note - In a Kubernetes environment, the containers both need to be referenced with `localhost`. +Content here is generated from corresponnding step, see `vars`. ## Prerequisites -- **running Karma tests** - have a NPM module with running tests executed with Karma -- **configured WebDriver** - have the [`karma-webdriver-launcher`](https://github.com/karma-runner/karma-webdriver-launcher) package installed and a custom, WebDriver-based browser configured in Karma +* **running Karma tests** - have a NPM module with running tests executed with Karma +* **configured WebDriver** - have the [`karma-webdriver-launcher`](https://github.com/karma-runner/karma-webdriver-launcher) package installed and a custom, WebDriver-based browser configured in Karma ## Parameters -| parameter | mandatory | default | possible values | -| ----------|-----------|---------|-----------------| -|script|yes||| -|containerPortMappings|no|`[node:8-stretch: [[containerPort: 9876, hostPort: 9876]]]`|| -|dockerEnvVars|no|`[ NO_PROXY: 'localhost,karma,$NO_PROXY', no_proxy: 'localhost,karma,$no_proxy']`|| -|dockerImage|no|`node:8-stretch`|| -|dockerName|no|`karma`|| -|dockerWorkspace|no|`/home/node`|| -|failOnError|no||| -|installCommand|no|`npm install --quiet`|| -|modules|no|`['.']`|| -|runCommand|no|`npm run karma`|| -|sidecarEnvVars|no|`[ NO_PROXY: 'localhost,selenium,$NO_PROXY', no_proxy: 'localhost,selenium,$no_proxy']`|| -|sidecarImage|no||| -|sidecarName|no||| -|sidecarVolumeBind|no||| -|stashContent|no|`['buildDescriptor', 'tests']`|| - -- `script` - defines the global script environment of the Jenkinsfile run. Typically `this` is passed to this parameter. This allows the function to access the [`commonPipelineEnvironment`](commonPipelineEnvironment.md) for storing the measured duration. -- `containerPortMappings` - see step [dockerExecute](dockerExecute.md) -- `dockerEnvVars` - see step [dockerExecute](dockerExecute.md) -- `dockerImage` - see step [dockerExecute](dockerExecute.md) -- `dockerName` - see step [dockerExecute](dockerExecute.md) -- `dockerWorkspace` - see step [dockerExecute](dockerExecute.md) -- `failOnError` - see step [seleniumExecuteTests](seleniumExecuteTests.md) -- `installCommand` - the command that is executed to install dependencies -- `modules` - define the paths of the modules to execute tests on -- `runCommand` - the command that is executed to start the tests -- `sidecarEnvVars` - see step [dockerExecute](dockerExecute.md) -- `sidecarImage` - see step [dockerExecute](dockerExecute.md) -- `sidecarName` - see step [dockerExecute](dockerExecute.md) -- `sidecarVolumeBind` - see step [dockerExecute](dockerExecute.md) -- `stashContent` - pass specific stashed that should be considered for the tests +Content here is generated from corresponnding step, see `vars`. ## Step configuration -We recommend to define values of step parameters via [config.yml file](../configuration.md). - -In following sections the configuration is possible: - -| parameter | general | step | stage | -| ----------|---------|------|-------| -|script|||| -|containerPortMappings|X|X|X| -|dockerEnvVars|X|X|X| -|dockerImage|X|X|X| -|dockerName|X|X|X| -|dockerWorkspace|X|X|X| -|failOnError|X|X|X| -|installCommand|X|X|X| -|modules|X|X|X| -|runCommand|X|X|X| -|sidecarEnvVars|X|X|X| -|sidecarImage|X|X|X| -|sidecarName|X|X|X| -|sidecarVolumeBind|X|X|X| -|stashContent|X|X|X| +Content here is generated from corresponnding step, see `vars`. ## Side effects diff --git a/vars/karmaExecuteTests.groovy b/vars/karmaExecuteTests.groovy index e12b00f47..19432aa5d 100644 --- a/vars/karmaExecuteTests.groovy +++ b/vars/karmaExecuteTests.groovy @@ -1,6 +1,7 @@ import static com.sap.piper.Prerequisites.checkScript import com.sap.piper.ConfigurationHelper +import com.sap.piper.GenerateDocumentation import com.sap.piper.GitUtils import com.sap.piper.Utils @@ -9,34 +10,67 @@ import groovy.transform.Field @Field String STEP_NAME = getClass().getName() @Field Set GENERAL_CONFIG_KEYS = [ - /** port mappings required for containers. This will only take effect inside a Kubernetes pod, format [[containerPort: 1111, hostPort: 1111]] */ + /** + * Map which defines per docker image the port mappings, e.g. `containerPortMappings: ['selenium/standalone-chrome': [[name: 'selPort', containerPort: 4444, hostPort: 4444]]]`. + */ 'containerPortMappings', - /** envVars to be set in the execution container if required */ + /** A map of environment variables to set in the container, e.g. [http_proxy:'proxy:8080']. */ 'dockerEnvVars', - /** Docker image for code execution */ + /** The name of the docker image that should be used. If empty, Docker is not used and the command is executed directly on the Jenkins system. */ 'dockerImage', - /** name of the Docker container. If not on Kubernetes pod, this will define the network-alias to the NPM container and is thus required for accessing the server, example http://karma:9876 (default). */ + /** + * Kubernetes only: + * Name of the container launching `dockerImage`. + * SideCar only: + * Name of the container in local network. + */ 'dockerName', - /** user home directory for Docker execution. This will only take effect inside a Kubernetes pod. */ + /** + * Kubernetes only: + * Specifies a dedicated user home directory for the container which will be passed as value for environment variable `HOME`. + */ 'dockerWorkspace', + /** + * With `failOnError` the behavior in case tests fail can be defined. + * @possibleValues `true`, `false` + */ 'failOnError', + /** The command that is executed to install the test tool. */ 'installCommand', + /** Define the paths of the modules to execute tests on. */ 'modules', + /** The command that is executed to start the tests. */ 'runCommand', - /** envVars to be set in Selenium container if required */ + /** A map of environment variables to set in the sidecar container, similar to `dockerEnvVars`. */ 'sidecarEnvVars', - /** image for Selenium execution which runs as sidecar to dockerImage */ + /** The name of the docker image of the sidecar container. If empty, no sidecar container is started. */ 'sidecarImage', - /** name of the Selenium container. If not on Kubernetes pod, this will define the network-alias to the Selenium container and is thus required for accessing the server, example http://selenium:4444 (default) */ + /** + * as `dockerName` for the sidecar container + */ 'sidecarName', - /** volume bind. This will not take effect in Kubernetes pod. */ + /** Volumes that should be mounted into the sidecar container. */ 'sidecarVolumeBind', - /** list of stash names which are required to be unstashed before test run */ + /** If specific stashes should be considered for the tests, their names need to be passed via the parameter `stashContent`. */ 'stashContent' ] @Field Set STEP_CONFIG_KEYS = GENERAL_CONFIG_KEYS @Field Set PARAMETER_KEYS = STEP_CONFIG_KEYS +/** + * In this step the ([Karma test runner](http://karma-runner.github.io)) is executed. + * + * The step is using the `seleniumExecuteTest` step to spin up two containers in a Docker network: + * + * * a Selenium/Chrome container (`selenium/standalone-chrome`) + * * a NodeJS container (`node:8-stretch`) + * + * In the Docker network, the containers can be referenced by the values provided in `dockerName` and `sidecarName`, the default values are `karma` and `selenium`. These values must be used in the `hostname` properties of the test configuration ([Karma](https://karma-runner.github.io/1.0/config/configuration-file.html) and [WebDriver](https://github.com/karma-runner/karma-webdriver-launcher#usage)). + * + * !!! note + * In a Kubernetes environment, the containers both need to be referenced with `localhost`. + */ +@GenerateDocumentation void call(Map parameters = [:]) { handlePipelineStepErrors(stepName: STEP_NAME, stepParameters: parameters) { final script = checkScript(this, parameters) ?: this