Migrating from 1.5.x to 2.0
Global changes
Gatling requires at least JDK7u6
As targeting newer JDKs provides bug fixes, speed improvements and opens opportunities for optimization, Gatling now requires at least a JDK7u6 (released almost two years ago already).
Scala 2.10
Gatling is built with Scala 2.10. If you’re using Scala IDE, make sure you’re using a version compatible with Scala 2.10.
Gatling is now available on Maven Central
Gatling releases are now available on Maven Central, and snapshots are deployed on each successful build by Travis CI to Sonatype’s snapshots repository.
If you were using Gatling with its Maven plugin, you no longer need to add the Excilys repository in your pom.xml
.
Package and GroupId changes
Gatling’s artifacts groupId and package are now io.gatling
.
You’ll have to:
- Update your build scripts to change the groupId of Gatling’s dependencies from
com.excilys.ebi.gatling
toio.gatling
- Update your simulations to replace the
com.excilys.ebi.gatling
part in the imports byio.gatling
Simulation
Necessary imports
akka.util.duration
classes have been ported to thescala.concurrent.duration
package. Simply replaceimport akka.util.duration._
byimport scala.concurrent.duration._
.import bootstrap._
andimport assertions._
are now unnecessary and have to be removed.import com.excilys.ebi.gatling.http.Headers.Names._
is now unnecessary, headers names are now directly available fromHeaderNames
.import com.excilys.ebi.gatling.http.Headers.Values._
is now unnecessary, headers values are now directly available fromHeaderValues
.
Protocols setup
Protocols are no longer configured by scenario and are now configured by simulation, using the protocols
method.
A 1.4.x-1.5.x setUp
like this one:
setUp(scn.(...).protocolConfig(httpProtocol))
would now be with Gatling 2.0:
setUp(scn.(...)).protocols(httpProtocol)
Assertions setup
The assertThat
method has been removed, assertions are now configured using assertions
in the same fashion as protocols are, e.g.:
setup(scn.(...).protocolConfig(httpProtocol))
assertThat(global.responseTime.max.lessThan(1000))
becomes:
setup(scn.(...))
.protocols(httpProtocol)
.assertions(global.responseTime.max.lessThan(1000))
New Injection DSL
The users
, ramp
and delay
methods to configure the injection profile for your scenario have been removed in favor of a full-blown dedicated DSL.
Injection steps are now configured using the inject
method available on your configured scenario.
Migrating users
// With Gatling 1.5.X
setUp(scn.users(10)...)
// With Gatling 2.0
setUp(scn.inject(atOnceUsers(10))...
Migrating ramp
// With Gatling 1.5.X
setUp(scn.users(10).ramp(30)...)
// With Gatling 2.0
setUp(scn.inject(rampUsers(10) over (30 seconds))...
Migrating delay
// With Gatling 1.5.X
setUp(scn.users(10).delay(5)...)
// With Gatling 2.0
setUp(scn.inject(nothingFor(5 seconds), atOnceUsers(10))...
For more information on the new Injection DSL, please consult the Injection DSL reference documentation.
Core
Checks
whatever
has been renamed to optional
.
Structure Elements
- The first parameter of
foreach
is now anExpression
(e.g. a Gatling EL string), not the name of the attribute to loop over.
For example, if you have a list
attribute in the user’s session holding a list of values:
.foreach("list", "elem") {
...
}
becomes:
.foreach("${list}", "elem") {
...
}
- In
asLongAs
,exitASAP
now defaults to true. For more information on the change of behaviour it introduces, see asLongAs documentation.
Session
Session has been under major refactoring:
session.get("foobar")
becomessession("foobar")
session.getTypedAttribute[T]("foobar")
becomessession("foobar").as[T]
session.getAttributeAsOption[T]("foobar")
becomessession("foobar").asOption[T]
session.setAttribute("foobar", 1234)
becomessession.set("foobar", 1234)
session.setAttributes(Map("foo" -> 1, "bar" -> 2)
becomessession.setAll("foo" -> 1, "bar" -> 2)
session.removeAttribute("foobar")
becomessession.remove("foobar")
session.isAttributeDefined("foobar")
becomessession.contains("foobar")
HTTP
Protocol
HTTP protocol bootstrapper, httpProtocol
, has been renamed to http
.
Query parameters
Removed
Versions of queryParam
and multivaluedQueryParam
that took no other parameters than the key (resolving the value from the session, using the key’s name to find the attribute with the same name) have been removed.
Modified
multivaluedQueryParam
can now resolve the values directly from the session, using Gatling’s EL.
Form parameters (for POST requests)
Renamed
Methods for adding form parameters to the request have been renamed:
param
=>formParam
multiValuedParam
=>multivaluedFormParam
Removed
Versions of queryParam
and multivaluedQueryParam
that took no other parameters than the key (resolving the value from the session, using the key’s name to find the attribute with the same name) have been removed.
Modified
multivaluedFormParam
can now resolve the values directly from the session, using Gatling’s EL.
Request bodies
- Scalate templates support has been dropped. ElFileBody (see below) is the best suited to replace your existing Scalate templates.
- The API for setting request bodies on request has changed.
Instead of having several methods like
body
,fileBody
andbyteArrayBody
, there is a now a single method,body(...)
in which you set the type of body to send.
Migrating .body(body)
.body(body)
has been replaced by .body(StringBody(body))
.
http("my post request")
.post("http://www.example.org")
.body("Look Ma, I'm a request body !")
becomes:
http("my post request")
.post("http://www.example.org")
.body(StringBody("Look Ma, I'm a request body !"))
Migrating .fileBody(filePath)
.fileBody(filePath)
has been replaced by .body(RawFileBody(filePath))
.
http("my post request")
.post("http://www.example.org")
.fileBody("my_upload.xslx")
becomes:
http("my post request")
.post("http://www.example.org")
.body(FileBody("my_upload.xslx"))
Migrating .fileBody(filePath, values)
.fileBody(filePath, values)
has been replaced by .body(ElFileBody(filePath))
.
values
are now directly resolved from the virtual user’s session’s content.
http("my post request")
.post("http://www.example.org")
.fileBody("my_template.txt", Map("userName" -> "user123"))
becomes:
http("my post request")
.post("http://www.example.org")
.body(ElFileBody("my template.txt"))
If my template.txt
contains:
Hi, my name is ${userName}
and the virtual user’s session has an attribute userName
set to user123
,
Then the effectively sent request body would be:
Hi, my name is user123
Migrating .byteArrayBody(byteArray)
.byteArrayBody(byteArray)
has been replaced by .body(ByteArrayBody(bytes))
.
http("my post request")
.post("http://www.example.org")
.byteArrayBody(Array(1, 2, 3, 4))
becomes:
http("my post request")
.post("http://www.example.org")
.body(ByteArrayBody(Array(1, 2, 3, 4)))
For more information, see the Request bodies reference section.
Misc
ExtendedResponse
has been renamed intoResponse
.requestInfoExtractor
andresponseInfoExtractor
have been merged into a singleextraInfoExtractor
, which takes aExtraInfo => List[Any]
function.
For more information on extraInfoExtractor
, please refer to its documentation.
Logs
simulation.log
has been redesigned.
If you wrote your own specific simulation.log
parser, you’ll need to migrate it to the new structure.
Recorder
Until now, when setting up the Recorder, you had to setup two ports for the Recorder’s local proxy: one for HTTP, one for HTTPS. This is not needed anymore, as the Recorder handles itself the switch to an HTTPS connection if necessary, and only a single port needs to be specified.
Maven Plugin
The <includes>...</includes>
and <excludes>...</excludes>
configuration options have been removed.
Should you want to select a specific simulation to run, you can use the <simulationClass>...</simulationClass>
config option to do so.
For more information, see the Maven plugin documentation.