JarCastingArquillian Spacelift Gradle Plugin 
This Gradle plugin is able to prepare test environment and execute tests. Plugin is using Arquillian Spacelift project to execute external commands. Compatible with Gradle 2.
In order to enable the plugin, define:
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "gradle.plugin.org.arquillian.spacelift.gradle:arquillian-spacelift-gradle:1.0.0-alpha-17"
}
}
apply plugin: "org.arquillian.spacelift"
Alternatively, you can use incubating Gradle plugin DSL:
plugins {
id "org.arquillian.spacelift" version "1.0.0-alpha-17"
}
Spacelift Tasks
This plugin provides following tasks. You can get same info by running ./gradlew tasks:
- assemble
-
Installs all installations defined by profile
- check/test
-
Executes tests defined in profile. Depends on assemble.
- testreport
-
Gathers all test results in JUnit format from workspace and creates a combined report. Requires additional configuration in build.gradle file
- describe
-
Shows global configuration and available profiles and more
- cleanCache
-
Wipes cached installations and extracted installation artifacts for currently activated installations
- cleanWorkspace
-
Wipes Spacelift workspace directory
- cleanRepository
-
Wipes Maven repository used by Spacelift
- cleanAll
-
Executes all the clean tasks
DSL
Plugin uses following DSL structure:
spacelift {
workspace value
cacheDir value
killServers value
configuration {
item1 { }
}
tools {
tool1 { }
}
profiles {
profile1 { }
profile2(from:profile1) { }
}
installations {
installation1 { }
installation2(from:MyOwnInstallationType) { }
installation3(from:installation2) { }
}
tests {
test1 { }
}
}
- value
-
Value definition in accepted in following format. If it is defined in block, is is always lazy evaluated.
-
plain - such as false, "mydir", 'mydir' or "${project.rootDir}/mydir".
-
list - such as "foo", "bar" or [1, 2, 3]
-
block - such as { false } or { /* a lot of code */ }. Block does has access to properties of defining installation, profile, test or tool, whatever is relevant. It can also reference current project by using project property
-
map - a map with keys denoting operating system and value either in plain or block form, for instance [linux:"foo", windows: {"foo"}]. Following OS values are supported:
-
linux
-
windows
-
mac
-
solaris
NoteIf you are using a map, you need to use parenthesis around parameters
-
-
Spacelift configuration
Spacelift configuration can be modified by altering value of following properties:
-
workspace - a directory where you work, by default `pwd`/ws
-
installationsDir - a directory where installation files are cached, by default ~/.spacelift/cache
-
killServers - {true|false} whether to kill Server processes first
User configuration
You can specify any configuration for your job in configuration block in Spacelift DSL. Also, you can provide a configuration in a specific profile, if you do so, it might override values in global configuration block. That said, configuration is immutable in the script itself and the only way it can be changed is from command line.
configuration {
item1 {
type value
description value
converter value
defaultValue value
value value
}
...
}
A configuration item can have following values set:
- type
-
Type of the configuration item. This can be set to one of the built-in types or a custom one, but a converter needs to be provided. Built-in types: Boolean, Byte, Short, Integer, Long, CharSequence, String, Class, File. Default type is String.
- description
-
Description of the configuration item. This will be printed out when running the describe task.
- converter
-
An instance of a ConfigurationItemConverter that will be used to convert the input from commandline into the type defined as well as converting the type back into string output.
- defaultValue
-
Default value that will be used when this configuration item is not input from commandline.
- value
-
If set, the configuration item cannot be changed from the commandline and is basically read-only.
User tools
Tools allow you to define Spacelift bindings for external commands that should be available on local system. Tools can be inherited from previously defined tools.
toolName {
command value
allowedExitCodes value
interaction value
isDaemon value
environment value
}
A tool can have following values set:
- command
-
Command defines what will be executed. In case you provide string or list of strings, it will be transformed to Spacelift CommandBuilder. In case you are using block, you are supposed to return CommandBuilder. In case of map, you can use windows, linux, mac and solaris keys that will match the platform. The block will register a CommandTool you can retrieve by Spacelift.task('toolName') later on.
- allowedExitCode
-
Exit codes that command executing can return, by default 0
- interaction
-
Interaction with the command process, by default GradleSpaceliftDelegate.ECHO_OUTPUT
- isDaemon
-
By default false. If set to true, tool will spawn a process that will survive Gradle execution exit.
- environment
-
By default [:]. Properties to be added to process environment.
User profiles
Profiles consist of installations to be installed and tests to be executed. You can use -PprofileName to trigger specific profile, otherwise default profile is triggered. default profile is expected to be present. Note, you need define profileName quoted in case of default. Profiles can be inherited from previous created profiles.
profileName {
configuration { }
enabledInstallations 'installation1', 'installation2'
tests 'test1', 'test3', 'test27'
excludedTests 'test3'
}
Use the configuration block in profile to declare new configuration items or override those defined in the main configuration block.
You can exclude tests from execution by excludedTests on profile where you specify which tests you do not want to execute. By triggering the above profile, only test1 and test27 will be executed.
|
Note
|
You can also use * to enable all defined installations and or tests for profile. And you can also use value notion and construct a list of strings to match installation names. |
User installations
Installations provides a way how to bring additional tools to you test environment. Installation is automatically downloaded or fetched from local cache and extracted, based on current OS. Installations can be inherited from previously defined installations or you can define your own installation DSL by implementing Installation and point installation to its class.
installationName {
product value
version value
fileName value
remoteUrl value
home value
autoExtract value
isInstalled value
preconditions value
extractMapper { /* Any UncompressTool call(s) */ }
tools {
tool1 {
...
}
}
postActions {
}
}
otherInstallation(from:installationName) {
// reuses all values from installationName and then redefines home directory
home newValue
}
myInstallation(from:MyInstallationClass) {
// uses your own DSL, myBlock has to be a Closure typed property of MyInstallationClass
myBlock { }
}
Following DSL blocks are available for DefaultInstallation:
-
product - name of product, used for storing installation in installationsDir
-
version - version of product, used for storing installation in installationsDir
-
fileName - name of file as downloaded in workspace. Can be map, same keys as for tool
-
remoteUrl - URL where to download from. Can be map, same keys as for tool
-
home - name of dir in workspace where installation is extracted. Can be map, same keys as for tool
-
autoExtract - by default true, consider installation an archive and extract it to workspace directory
-
isInstalled - by default check for installation home existence, if evaluated to true, installation is skipped
-
preconditions - this closure is optional and when specified, it has to return boolean value. If evaluated to false, installation is skipped, if true, installation is performed.
-
extractMapper - optional calls on UncompressTool performed prior extraction happens. For instance, this removes first directory from extracted path and extracts archive to directory defined by home
extractMapper { toDir(home) cutdirs() } -
tools - allows to define tool(s) that will be available after installation is done, same syntax as tools block_
-
postActions - defines actions to be performed after installation is extracted
User tests
Tests define a block of commands to be executed in test Gradle task. If you provide dataProvider block, test execution (including before and after test phases) will iterate over data provided. Tests can inherit from previously defined tests or use your own DSL, same as Installation.
testName {
dataProvider {
// return an array here, allows to parametrize tests
}
beforeSuite {
// executed once prior all tests
}
beforeTest { value ->
// executed prior test
}
execute { value ->
// your commands here
}
afterTest { value ->
// executed after test
}
afterSuite {
// executed once prior all tests
}
}
Referencing DSL elements in Gradle
In case you need, you can reference them directly in the code by its name. For instance, to reference home of installation named selenium in your tests, you can use following syntax
installations {
selenium {
home "the-home"
}
}
tests {
testName {
execute {
assertThat selenium.home, is(notNullValue())
}
}
}
Direct reference can be used for any configuration item, installation, test, tool or profile. References are resolved in this order, in case there are two objects with different type and same name, further possible references are ignored and a warning is logged. It means it is safer to use unique names per all types.
|
Note
|
In case you need reference DSL object indirectly, for instance you have two objects with the same name or it is shaded by local variable, you can use indirect syntax in form project.spacelift.installations['installationName']. Similar call exists for configuration, tools, profiles and tests. |
Execution parameters
It is possible to modify what tests will be run and what installations will be installed. Apart from profile option, you can use:
-Pinstallations=comma,separated,values
-Ptests=comma,separated,values
This will ignore installations and tests defined by profile and instead will install comma, separated and value. If test task is executed, it will perform test execution for tests comma, separated and value.
If you need to reference profile, installations or tests from a Gradle script, these are exposed as:
-
project.selectedProfile
-
project.selectedInstallations
-
project.selectedTests
All represented by appropriate object.
Manual profile definitions
In cases you want to execute only a subset of installations or tests of given profile, you can combine activated profile with manual override of installations and or tests.
For instance, following call installs all installations from default profile but executes only myTestName test.
gradle -Pdefault -Ptests=myTestName test
Whereas this call completely ignores profile and installs myTestNameRequirement and then executes myTestName:
gradle -Pinstallations=myTestNameRequirement -Ptests=myTestName test
|
Note
|
If you want to skip tests or installations altogether, use following syntax gradle -Pinstallations= test |
Spacelift Tools and Task
You can benefit from following tools and tasks, either from Spacelift itself or provided by this plugin:
-
DownloadTool - downloads a file
-
UnzipTool - extracts a zip file
-
CommandTool - executes external command
-
AntExecutor - executes Ant command. Requires ant tool
-
MavenExecutor - executes Maven command. Requires mvn tool
-
JavaExecutor - executes Java command. Requires java tool
-
XmlFileLoader - loads xml from file into Node
-
XmlTextLoader - loads xml from text into Node
-
XmlUpdater - stores Node into file
-
ArquillianXmlUpdater - updates container and/or extension properties in arquillian.xml files
-
PomXmlUpdater - updates properties in pom.xml files
-
SettingsXmlUpdater - updates settings.xml with additional repositories, sets localRepository
-
KillJavas - kills running Java processes (Selenium, JBoss AS/WildFly containers) and processes occupying ports
-
StandaloneXmlUpdater - allows to add keystore/truststore configuration to standalone.xml
-
DomainXmlUpdater - allows to add keystore/truststore configuration to domain.xml
-
AndroidSdkUpdater - allows to fetch binaries for specific Android SDK target - you need to agree with Android SDK license first. Requires android tool.
-
AndroidSdkOptForStats - allows to opt out for stats - you need to agree with Android SDK license first
-
AndroidEmulatorStarter - starts Android emulator
-
AndroidEmulatorStopper - stops Android emulator
-
AVDCreator - creates Android Virtual Devices
-
CordovaExecutor - executes Cordova commands
-
RHELVersion - determines version of RHEL system
Release new version
Follow this process to release new version:
-
Update version to release version in build.gradle
-
Execute gradle publishPlugins to publish plugin in Gradle Plugin Repository. Note that your ~/.gradle/gradle.properties should contain API key according to https://plugins.gradle.org/docs/submit
-
Tag current commit via git tag
-
Bump version to next development version
