- [Developer Guide](#developer-guide) - [Forking and Cloning](#forking-and-cloning) - [Jenkins Pipelines and Shared Libraries](#jenkins-pipelines-and-shared-libraries) - [Install Prerequisites](#install-prerequisites-1) - [Java](#java) - [Run Tests](#run-tests-1) - [Regression Tests](#regression-tests) # Developer Guide ## Forking and Cloning Fork this repository on GitHub, and clone locally with `git clone`. ## Jenkins Pipelines and Shared Libraries This project contains [Jenkins pipelines](jenkins) and [Jenkins shared libraries](src/jenkins) that execute the tools that build OpenSearch and OpenSearch Dashboards. ### Install Prerequisites #### Java Use Java 11 for Jenkins jobs CI. This means you must have a JDK 11 installed with the environment variable `JAVA_HOME` referencing the path to Java home for your JDK installation, e.g. `JAVA_HOME=/usr/lib/jvm/jdk-11`. Download Java 11 from [here](https://adoptium.net/releases.html?variant=openjdk11). ### Run Tests This project uses [JenkinsPipelineUnit](https://github.com/jenkinsci/JenkinsPipelineUnit) to unit test Jenkins pipelines and shared libraries. See [tests/jenkins](tests/jenkins). ``` $ ./gradlew test > Task :test BUILD SUCCESSFUL in 7s 3 actionable tasks: 1 executed, 2 up-to-date ``` #### Regression Tests Jenkins workflow regression tests typically output a .txt file into [tests/jenkins/jobs](tests/jenkins/jobs). For example, [TestHello.groovy](tests/jenkins/TestHello.groovy) executes [Hello_Jenkinsfile](tests/jenkins/jobs/Hello_Jenkinsfile) and outputs [Hello_Jenkinsfile.txt](tests/jenkins/jobs/Hello_Jenkinsfile.txt). If the job execution changes, the regression test will fail. - To update the recorded .txt file run `./gradlew test -info -Dpipeline.stack.write=true` or update its value in [gradle.properties](gradle.properties). - To run a specific test case, run `./gradlew test -info --tests=TestCaseClassName` #### Tests for jenkins libraries ##### Lib Tester Each jenkins library should have a lib tester associated with it. Eg: [SignArtifactsLibTester](tests/jenkins/lib-testers/SignArtifactsLibTester.groovy) - Library tester should extend [LibFunctionTester.groovy](tests/jenkins/LibFunctionTester.groovy) - implement `void configure(helper, bindings)` method which sets up all the variables used in the library - Note: This will not include the variables set using function arguments - implement `void libFunctionName()`. This function will contain the name of function. - implement `void parameterInvariantsAssertions()`. This function will contain assertions verifying the type and accepted values for the function parameters - implement `void expectedParametersMatcher()`. This function will match args called in the job to expected values from the test ##### Library Test Case Each jenkins library should have a test case associated with it. Eg: [TestSignArtifacts](tests/jenkins/TestSignArtifacts.groovy) <br> - Jenkins' library test should extend [BuildPipelineTest.groovy](tests/jenkins/BuildPipelineTest.groovy) - Create a dummy job such as [Hello_Jenkinsfile](tests/jenkins/jobs/Hello_Jenkinsfile) to call and test the function and output [Hello_Jenkinsfile.txt](tests/jenkins/jobs/Hello_Jenkinsfile.txt)