Child pages
  • Matrix Groovy Execution Strategy Plugin
Skip to end of metadata
Go to start of metadata

Plugin Information

View Matrix Groovy Execution Strategy on the plugin site for more information.

A plugin to decide the execution order and valid combinations of matrix projects.This uses a user defined groovy script to arrange the order which will then be executed

Usage

This plugin makes use of an extension point in the matrix-project plugin to allow for other execution strategies for matrix projects. When installed, matrix projects will show a new drop-down to select an execution strategy. Without the plugin, the default (or classic) strategy is selected and not even displayed.

This plugin can also be used as a combination filter/touchstone to feed builds into the queue with more flexibility than the two stages supplied as standard. 

Return Value

New for release 1.0.6. You can now specify if you want to continue after a failure. If you return a List with two items in it, the second item can be a true|false value where true will continue execution even after a failure. The idea is that you can control whether to continue after a failure from within the script

return [result, true]  

The original functionality also works and will work as before

return result

will fail at the end of the current run as before.

Bindings

There are several variables available in the script

  • combinations
  • workspace
  • jenkins
  • execution
  • result
  • parameters
  • env
  • out

combinations

This is a List of a String map of all the matrix combinations
For example

[
    { axis1: "a", axis2: "x" },
    { axis1: "a", axis2: "y" },
    { axis1: "a", axis2: "z" },
    { axis1: "b", axis2: "x" },
    { axis1: "b", axis2: "y" },
    { axis1: "b", axis2: "z" }
]

workspace

A string of the workspace directory

jenkins

The Jenkins instance

execution 

The is the [OneOffExecutor]( http://javadoc.jenkins-ci.org/hudson/model/OneOffExecutor.html) running the setup for the matrix job

result

The script is expected to return a [TreeMap](http://groovy.codehaus.org/JN1035-Maps). This is passed in for use but does not have to be the one returned

 

{
  x: [
    { axis1: "a", axis2: "x" },
    { axis1: "b", axis2: "x" }
  ],
  y: [
    { axis1: "a", axis2: "y" },
    { axis1: "b", axis2: "y" }
  ]
}

Notice that axis2: 'z' has not been returned, so these combinations will not be executed.

The results will be placed onto the build queue in the order they are placed in the array, so in the above it will be ['a','x'] then ['b','x']. When they are completed then ['a','y'] and ['b','y']. The combinations can run in a different order if there are dependencies on nodes, for example. This is a good way to feed your combinations in a definite order.

parameters

This is a hash of any build parameters used, with the parameter name as the key

env

This is the environment variables used in the build. It is also aware of the envinject plugin and will use these if installed and defined for the project

out

This is bound to the output logger for the build and its main use is to allow println statements to appear in the build log. This will happen transparently for 

 println 'something for the log'

Execution

The entries in the TreeMap returned will be executed in sequence.
That is to say, the first list will be executed in parallel, then the second, and so on
A failure will stop the build on the next entry but the runs in flight will not be stopped.
If no script is specified, all combinations will be run in parallel in one go.

These will be run in alphabetical order of the keys.

Scripts

Location

The script can be in three locations

  • Added in directly
  • An absolute path available to the node running the job setting up the matrix (can be disabled in global config). This file is to exist on the master, even if running on a slave node.
  • A relative path in the workspace (can be disabled in global config)

Example

How to transform the example above

combinations.each{

             if(it.axis2 == 'z')
                   return

             result[it.axis2] = result[it.axis2] ?: []
             result[it.axis2] << it
}

[result, true]

Global Configuration

There is an option to disable scripts off the filesystem. This is useful if you want to secure scripts for non admin users. This option will change the job display section to only show a script option.

Release History

1.07

Fixed usage of script when using a fully qualified path. This script will reside on the master issue 15

1.06 (1.05 not released)

Added return list option to specify if a failure should continue the main build

return [ result, true]

Upgraded to use groovy 3.2.1

1.04

Added parameters binding

Added env binding

Added out binding

Try out all the above with this in your script

println '---------parameters--------'
parameters.each{ k,v ->
    println "${k}-->${v}"
}
println '-------------env--------------'
env.each{ k,v ->
    println "${k}-->${v}"
}
println '--------------------------------'
1.0.3

Bugfix to use a safer randomize method

1.0.2

Fixed to work with Matrix Build Listeners like Matrix Combination parameter

Added Script Security capability

Added global config option to disable using scripts off the filesystem - to complete script security

Please ask questions on github as I don't get notifications for this page 

12 Comments

  1. Wonderful plug-in!!!

    I have installed it, but do not see "this axis"(Matrix Groovy Execution...) under "Add Axis" of multi-configuration project. I see only "dynamic, label,slave and user-defined" Axis.am I missing anything?

    1. thanks for the support!
      It works by adding in a drop down of execution strategies (only visible when you have more than one available) . So it is not an axis as such but allows you to select your combinations at build time
      It is really waiting for the matrix-project 1.5 release as there is a cosmetic bug when swapping between strategies for the first time
      Please let me know how you get on with it

    2. thanks for the support!
      It works by adding in a drop down of execution strategies (only visible when you have more than one available) . So it is not an axis as such but allows you to select your combinations at build time
      It is really waiting for the matrix-project 1.5 release as there is a cosmetic bug when swapping between strategies for the first time
      Please let me know how you get on with it

  2. This plugin looks really useful, but I'm baffled by the instructions. It says there are several bindings/variables available in the script, but then proceeds to tell us nothing about what they are called. Apparently I can use a string of the workspace directory or a tree map or a list of strings. Hmmm... completely baffled.

    Or maybe I need to add a groovy script like the last example instead of just specifying a list/map. Where does the variable "combinations" come from?

    In the TreeMap example, are the x and y variables at the top level the same as the "x" and "y" strings in the axis options?

    1. Hi 

      Sorry for the delay, I must have missed the email

      I was planning for the future by passing additional parameters in to use. The combinations is a cross product (or map)  of all the possible combinations which can then be iterated to decide on the order, or ignored. this is defined in the outer scope and thanks to the magic of groovy closures is available in the script defined

      The result tree map is the order in which the sets will be run, So I am recycling the axis2 value but there is no reason to and the top level keys will be executed in alphabetical order.

      Yes the script at the end is the one to use in the script field, with a couple of user defined axis called axis1 and axis2

  3. Hi,

    the script usage is not quite clear. Can you give a simple example how to filter out values from a 3-dimension Axis matrix ?

    (Specifically I have a Slaves Axis, and I want to exclude all offline nodes from this Axis, I hope your plugin can resolve this...)

    Thanks!!

    1. Hi

      You need to do something like this - assuming a slave based axis called NODE and the earlier example

      def online = [:]
      
      //clearly master is online or we wouldn't be here
      online['master'] = true
      
      jenkins.slaves.each {
        if (! it.getComputer().isAcceptingTasks() || it.getComputer().isOffline() ) {
          online[it.name] = false
        } else {
          online[it.name] = true
        }
      }
      
      combinations.each {
          //so the node could be offline or we know nothing of
          //it as it has been deleted
          if(!online[it.NODE])
              return
      
          if(it.axis2 == 'z')
              return
      
          result[it.axis2] = result[it.axis2] ?: []
          result[it.axis2] << it
      }
      
      result
      

      Hope this helps!

      1. Tried your script, it did not filter out offline nodes from the Matrix axis.

        I'm having 3 axis (NODE * BROWSER * TEST_SUITE), so my script looks like this:

        def online = [:]
        online['master'] = true
        
        jenkins.slaves.each {
          if (! it.getComputer().isAcceptingTasks() || it.getComputer().isOffline() ) {
            online[it.name] = false
          } else {
            online[it.name] = true
          }
        }
        
        combinations.each {
            if(!online[it.NODE])
                return
        
            result[it.BROWSER] = result[it.BROWSER] ?: []
            result[it.BROWSER] << it
        
            result[it.TEST_SUITE] = result[it.TEST_SUITE] ?: []
            result[it.TEST_SUITE] << it
        }
        
        result
        

        Should I see the filtered Matrix after pressing "build with parameters" (before pressing the "build" button) ?

        1. Which parameters are you looking to pass in and which plugin are you using for the parameters? Do all your builds start together? I'll investigate further

          1. I'm passing many parameters and it all works fine but without filtering the axis. The 3 axis are:

            BROWSER  (2 browsers, IE or FIREFOX)

            TEST_SUITE (many xml file names)

            NODE (3 nodes)

            In addition I use the Matrix Combinations Plugin, so I can set a default combination matrix.

            1. Hi

              It seems to be incompatible with the Matrix Combinations plugin. I'll have to investigate that.

              Incidentally, you can drop the 

                  result[it.TEST_SUITE] = result[it.TEST_SUITE] ?: []
                  result[it.TEST_SUITE] << it

              part as the individual combinations only need to be in once

              1. Hi

                I fixed that and released version 1.0.2 - which should be available soon

                I also implemented ScriptSecurity in this release. I'll update this page when it goes live

                Thanks for the feedback

                Jeremy