(such as */.war, for any WAR file produced by the build job), or it can be much more precise
(such as gameoflife-web/target/gameoflife.war). Note that by default, Jenkins will copy the
directory structure along with the file you retrieve, so if the WAR file you are after is nested inside
the target directory of the gameoflife-web module, Jenkins will place it inside the gameoflife-
web/target directory in your current workspace. If this is not to your tastes, you can tick the “Flatten
directories” option to tell Jenkins to put all of the artifacts at the root of the directory you specify (or,
by default, in your project workspace).
In many cases, you will simply want to retrieve artifacts from the most recent successful build. However,
sometimes you may want more precision. The “Which builds” field lets you specify where to look for
artifacts in a number of other ways, including the latest saved build (builds which have been marked to
“keep forever”), the latest successful build, or even a specific build number.
If you have installed the Build Promotion plugin (see Section 10.7.3, “Build Promotions”), you can
also select the latest promoted artifact in a particular promotion process. To do this, choose “Specify by
permalink”, then choose the appropriate build promotion process. This is an excellent way of ensuring
a consistent and reliable build pipeline. For example, you can configure a build promotion process to
trigger a build that copies a generated WAR file from the latest promoted build and deploys it to a
particular server. This ensures that you deploy precisely the right binary file, even if other builds have
occurred since.
If you are copying artifacts from a multimodule Maven build job, Jenkins will, by default, copy all of
the artifacts from that build. However often times you are only interested in one specific artifact (such
as the WAR artifact in a web application, for example.
This plugin is particularly useful when you need to run functional or performance tests on your web
application. It is often a useful strategy to place these tests in a separate project, and not as part of your
main build process. This makes it easier to run these tests against different servers or run the subsets of
the tests in parallel, all the while using the same binary artifact to deploy and test.
For example, imagine that you have a default build job called gameoflife that generates a WAR file, and
you would like to deploy this WAR file to a local application server and run a series of functional tests.
Furthermore, you want to be able to do this in parallel on several distributed machines.
One way to do this would be to create a dedicated Maven project designed to run the functional tests
against an arbitrary server. Then, you would set up a build job to run these functional tests. This build
job would use the Copy Artifact plugin to retrieve the latest WAR file (or even the latest promoted WAR
file, for more precision), and deploy it to a local Tomcat instance using Cargo. This build job could
then be set up as a configurable (“matrix”) build job, and run in parallel on several machines, possibly
with extra configuration parameters to filter the tests run by each build. Each build run would then be
using its own copy of the original WAR file. An example of a configuration like this is illustrated in
Figure 10.40, “Running web tests against a copied WAR file”.