https://github.com/turbobasic/jenkinslibrary
Boilerplate project for development of Jenkins shared library and pipelines. It addresses poorly documented nuances of setting up Gradle project and build environment required for running Unit tests, adding correct versions of Jenkins plugins to dependencies etc.
https://github.com/turbobasic/jenkinslibrary
jenkins jenkins-pipeline-unit junit5 pipeline-as-code spock-framework unit-testing
Last synced: 4 months ago
JSON representation
Boilerplate project for development of Jenkins shared library and pipelines. It addresses poorly documented nuances of setting up Gradle project and build environment required for running Unit tests, adding correct versions of Jenkins plugins to dependencies etc.
- Host: GitHub
- URL: https://github.com/turbobasic/jenkinslibrary
- Owner: turboBasic
- License: mit
- Created: 2023-12-23T05:19:38.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-18T09:08:43.000Z (over 1 year ago)
- Last Synced: 2025-01-22T16:33:14.883Z (9 months ago)
- Topics: jenkins, jenkins-pipeline-unit, junit5, pipeline-as-code, spock-framework, unit-testing
- Language: Groovy
- Homepage:
- Size: 111 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# JenkinsLibrary
Boilerplate project for development of Jenkins shared library and pipelines.
JenkinsLibrary aims to help developers to easily start new project with Jenkins Shared library and pipelines.
It addresses poorly documented nuances of setting up Gradle project and build environment required for
running Unit and Integration tests, adding correct versions of Jenkins plugins to dependencies etc.
Important feature of JenkinsLibrary is that it keeps both Shared library and pipelines which use it inside the same
project which makes development and testing significantly simpler comparing with the setup where library and pipelines
are kept in separate projects. Still, if you prefer to use JenkinsLibrary as a separate project for library classes
only and reuse it in multiple projects with pipeline-only code, it allows you to do so without any modifications.
JenkinsLibrary uses [JenkinsPipelineUnit](https://github.com/jenkinsci/JenkinsPipelineUnit) library for
mocking pipeline steps and variables, but on top of it adds [Spock](https://github.com/spockframework/spock) v2
framework which allows to use more precise and self-explanatory syntax of describing test cases.
## Table of Contents
1. [Usage](#usage)
1. [Setting up in JetBrains IDEA](#setting-up-project-in-jetbrains-idea)
1. [Development environment](#development-environment)
1. [Directory structure](#directory-structure)
1. [Contributing](#contributing)
## Usage
### Build and test commands
- `./dev all-test`: build project and execute Integration and Unit tests.
- `./dev integration-test`: build project and execute Integration tests.
- `./dev test`: build project and execute Unit tests.
If you provide arguments after `./dev test` command, they are appended to `gradle clean test` command-line and
resulting command is executed
- `./dev test --tests "pipelines.admin.**"`: build project and execute all tests in `pipelines.admin` package
- `./dev test --tests "pipelines.admin.**" --tests org.example.FooSpec`: build project and execute all tests in
`pipelines.admin` package and tests for class `org.example.FooSpec`
- `./dev test -Dpipeline.stack.write=true`: build project, execute tests and update
[call stack files](test/resources/callStacks/README.md)
### Other commands
- `./dev docker [--push]`: only build Docker image. If `--push` switch is provided, Docker image is pushed to Docker Hub
- `./dev help`: display this help about commands
- `./dev lint`: lint project with MegaLinter
- `./dev lint-commits`: lint feature branch commits using [Conventional commit linter](https://commitlint.js.org/#/)
- `./dev sh`: create development environment and enter shell session inside it. Inside development environment you can
use Gradle to execute any advanced commands
## Setting up project in JetBrains IDEA
Execute `./gradlew openIdea` in the project. When IDEA opens the project click *Skip* if it proposes to import Gradle
project
## Development environment
The development environment invoked by `./dev sh` command is very compact so in most situation you are
fine to use your native environment for building and executing tests. All you need is to have Java 11
and Gradle 8 available in the PATH.
Recommended way of usage is the `./dev` wrapper (see [Usage](#usage))
but if you would like to use native environment you can use [SDKMan](https://sdkman.io) for installing
and switching versions of tools from JVM stack.
## Directory structure
Project follows the directory structure of
[Jenkins Shared Library](https://www.jenkins.io/doc/book/pipeline/shared-libraries/#directory-structure)
project. On top of that, `test` and other directories have been added for keeping files related to
additional features. Most directories have detailed Readme files with the description and other
important information about their contents and naming conventions:
- `pipelines`: [Jenkins pipelines](pipelines/README.md)
- `resources`: [Production resources directory](resources/README.md)
- `src`: Production source code for Jenkins Shared Library classes. Subdirectories here
follow conventional Groovy/Java package layout
- `test`: Unit-tests' source code. Subdirectories here follow conventional Groovy/Java
package layout
- `test/pipelines`: [Tests for jenkins pipelines](test/pipelines/README.md). Structure of this directory follows
the structure of `pipelines` directory
- `test/resources`: [Test resources directory](test/resources/README.md)
- `test/resources/callStacks`: [Call stack dumps directory](test/resources/callStacks/README.md). This directory
contains expected call stack dumps for the pipeline tests
- `testIntegration`: Integration tests' source code
- `testIntegration/resources`: [Resources directory](testIntegration/resources/README.md) for Integration tests
- `vars`: Custom steps aka _Global vars_ in Jenkins Shared library
## Contributing
See [How to contribute](CONTRIBUTING.md) document