NAV Navbar
shell

Eggplant Performance Studio REST API

Many of the actions that you can perform in the Eggplant Performance Studio user interface (UI) can also be automated by using the REST API. This ability could be useful if you run performance tests on a regular basis and want to automate the process. For example, you could use the REST API to integrate Eggplant Performance into a continuous integration (CI) environment.

Starting the REST Server

The path to the REST server is as follows:

<location_where_you_installed_eggPlant Performance>\TestControllerServer\bin\testControllerServer.exe

For example:

C:\Program Files (x86)\eggPlant Performance\TestControllerServer\bin\testControllerServer.exe

You can specify a different port by using the -p command line option.

testControllerServer.exe -p 8888

The REST server is a standalone web server that listens for HTTP requests on a specified port.

To start the REST server, run testControllerServer.exe from the command line. By default, the REST server listens for requests on port 5001. You can specify a different port by using the -p command line option.

Version

Get Eggplant Performance version

curl "http://localhost:5001/studio/api/1.0/version"

The above command returns JSON structured like this:

{
  "version": "8.0.0.154"
}

Use this method to get the version number for the running instance of Eggplant Performance.

HTTP Request

GET /studio/api/1.0/version

Response JSON

Property Type Description
version string The version number

Workspaces

List workspaces

curl "http://localhost:5001/studio/api/1.0"

The above command returns JSON structured like this:

{
  "workspaces": {
    "My First Workspace": "/studio/api/1.0/My%20First%20Workspace",
    "My Second Workspace": "/studio/api/1.0/My%20Second%20Workspace"
  }
}

Use this method to list all the workspaces available in Eggplant Performance Studio.

HTTP Request

GET /studio/api/1.0

Response JSON

Property Type Description
workspaces object Keys are workspace names, values are URLs

Create a workspace

curl "http://localhost:5001/studio/api/1.0/create_workspace"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Workspace", "location": "C:/My Workspace"}'

The example POST data:

{
  "name": "My Workspace",
  "location": "C:/My Workspace"
}

The above command returns JSON structured like this:

{
  "My Workspace": "/studio/api/1.0/My%20Workspace"
}

Use this method to create a new Eggplant Performance workspace with the specified name.

The folder specified as the location will become the workspace folder, containing the workspace files. It is recommended to specify a folder which doesn't yet exist - it will be created if necessary.

If a workspace with the specified name already exists, this method will have no effect.

HTTP Request

POST /studio/api/1.0/create_workspace

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New workspace name
location string Path to new folder, in which the workspace will be created

Response HTTP status code

HTTP status code Meaning
200 OK A workspace with the specified name already exists
201 Created The new workspace was created successfully

Response JSON

Property Type Description
workspace name string A URL representing the newly-created workspace

Check access to workspace

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/check_access"

The above command returns JSON structured like this:

{
  "message": "Workspace My Workspace accessed successfully"
}

Alternately, if the workspace is locked:

{
  "error": "Failed to open workspace My Workspace. It may already be in use by another instance of eggplant Performance."
}

Use this method to check whether the specified workspace is in use by another instance of Eggplant Performance.

If Eggplant Performance Studio is running and has the workspace open, the workspace will be locked. In that case, many of the other REST methods will not work until Eggplant Performance Studio is closed, or has switched to another workspace.

HTTP Request

GET /studio/api/1.0/<workspace>/check_access

Response JSON

Property Type Description
message string A success message - only present if the workspace is accessible
error string A failure message - only present if the workspace is not accessible

Projects

List projects

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects"

The above command returns JSON structured like this:

{
  "projects": {
    "My Project": "/studio/api/1.0/My%20Workspace/projects/My%20Project"
  }
}

Use this method to list all the projects available in the specified workspace.

HTTP Request

GET /studio/api/1.0/<workspace>/projects

Response JSON

Property Type Description
projects object Keys are project names, values are URLs

Create a project

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/create_project"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Project"}'

The example POST data:

{
  "name": "My Project",
}

The above command returns JSON structured like this:

{
  "My Project": "/studio/api/1.0/My%20Workspace/projects/My%20Project"
}

Use this method to create a new Eggplant Performance project with the specified name, in the specified workspace.

HTTP Request

POST /studio/api/1.0/<workspace>/create_project

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New project name

Response HTTP status code

HTTP status code Meaning
200 OK A project with the specified name already exists
201 Created The new project was created successfully

Response JSON

Property Type Description
project name string A URL representing the newly-created project

Rebuild scripts

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/rebuild"
  -H "Content-Type: application/json"
  --data-binary $'{}'

The above command returns JSON structured like this:

{
  "Java": {
    "output": [
      "Please wait while the workspace builds...",
      "Building My Workspace...",
      "",
      "Buildfile: C:\\My Workspace\\repository\\intel\\win32\\java\\build.xml",
      "",
      "clean:",
      "   [delete] Deleting directory C:\\My Workspace\\repository\\intel\\win32\\java\\build",
      "",
      "init:",
      "    [mkdir] Created dir: C:\\My Workspace\\repository\\intel\\win32\\java\\build",
      "",
      "compile:",
      "    [javac] Compiling 2 source files to C:\\My Workspace\\repository\\intel\\win32\\java\\build",
      "    [javac] Note: Some input files use unchecked or unsafe operations.",
      "    [javac] Note: Recompile with -Xlint:unchecked for details.",
      "",
      "jar:",
      "   [delete] Deleting: C:\\My Workspace\\repository\\upload\\My Workspace_java.jar",
      "      [jar] Building jar: C:\\My Workspace\\repository\\upload\\My Workspace_java.jar",
      "",
      "rebuild:",
      "",
      "BUILD SUCCESSFUL",
      "Total time: 2 seconds",
      "<span class='info'>----------- command completed - 10:09:31 8 Oct 2018 -----------</span>",
      "Please wait while the project builds...",
      "Building My Project...",
      "",
      "Buildfile: C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build.xml",
      "",
      "clean:",
      "   [delete] Deleting directory C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "",
      "init:",
      "    [mkdir] Created dir: C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "",
      "compile:",
      "    [javac] Compiling 2 source files to C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "    [javac] Note: Some input files use unchecked or unsafe operations.",
      "    [javac] Note: Recompile with -Xlint:unchecked for details.",
      "",
      "jar:",
      "   [delete] Deleting: C:\\My Workspace\\projects\\My Project\\repository\\upload\\My Project_java.jar",
      "      [jar] Building jar: C:\\My Workspace\\projects\\My Project\\repository\\upload\\My Project_java.jar",
      "",
      "rebuild:",
      "",
      "BUILD SUCCESSFUL",
      "Total time: 1 second",
      "<span class='info'>----------- command completed - 10:09:33 8 Oct 2018 -----------</span>"
    ],
    "success": true
  },
  "CSharp": {
    "output": [
      "Please wait while the workspace builds...",
      "Rebuilding My Workspace...",
      "",
      "Microsoft (R) Build Engine version 12.0.21005.1",
      "[Microsoft .NET Framework, version 4.0.30319.42000]",
      "Copyright (C) Microsoft Corporation. All rights reserved.",
      "",
      "Build started 08/10/2018 10:09:29.",
      "Project \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace.csproj\" on node 1 (rebuild target(s)).",
      "CoreClean:",
      "  Deleting file \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\My Workspace_cs4_5_1.dll\".",
      "  Deleting file \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\My Workspace_cs4_5_1.pdb\".",
      "  Deleting file \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\clrNativeWrapper.dll\".",
      "  Deleting file \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\clrWebBrowser.dll\".",
      "  Deleting file \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\fc_clr.dll\".",
      ...snip...
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrWebBrowser.xml\" to \"My Workspace\\Release\\clrWebBrowser.xml\".",
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\fc_clr.xml\" to \"My Workspace\\Release\\fc_clr.xml\".",
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrNativeWrapper.xml\" to \"My Workspace\\Release\\clrNativeWrapper.xml\".",
      "CopyFilesToOutputDirectory:",
      "  Copying file from \"obj\\Release\\My Workspace_cs4_5_1.dll\" to \"My Workspace\\Release\\My Workspace_cs4_5_1.dll\".",
      "  My Workspace -> C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\My Workspace_cs4_5_1.dll",
      "  Copying file from \"obj\\Release\\My Workspace_cs4_5_1.pdb\" to \"My Workspace\\Release\\My Workspace_cs4_5_1.pdb\".",
      "AfterBuild:",
      "  Copying file from \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\My Workspace_cs4_5_1.dll\" to \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\..\\..\\..\\upload\\My Workspace_cs4_5_1.dll\".",
      "  Copying file from \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace\\Release\\My Workspace_cs4_5_1.pdb\" to \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\..\\..\\..\\upload\\My Workspace_cs4_5_1.pdb\".",
      "Done Building Project \"C:\\My Workspace\\repository\\intel\\win32\\cs4_5_1\\My Workspace.csproj\" (rebuild target(s)).",
      "",
      "Build succeeded.",
      "    0 Warning(s)",
      "    0 Error(s)",
      "",
      "Time Elapsed 00:00:00.29",
      "<span class='info'>----------- command completed - 10:09:29 8 Oct 2018 -----------</span>",
      "Please wait while the project builds...",
      "Rebuilding My Project...",
      "",
      "Microsoft (R) Build Engine version 12.0.21005.1",
      "[Microsoft .NET Framework, version 4.0.30319.42000]",
      "Copyright (C) Microsoft Corporation. All rights reserved.",
      "",
      "Build started 08/10/2018 10:09:29.",
      "Project \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj\" on node 1 (rebuild target(s)).",
      "CoreClean:",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Project_cs4_5_1.dll\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Project_cs4_5_1.pdb\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\fc_clr.dll\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\fc_clr.xml\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\clrNativeWrapper.dll\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\clrWebBrowser.dll\".",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Workspace_cs4_5_1.dll\".",
      ...snip...
      "  Copying file from \"C:\\My Workspace\\repository\\upload\\My Workspace_cs4_5_1.pdb\" to \"My Project\\Release\\My Workspace_cs4_5_1.pdb\".",
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\fc_clr.xml\" to \"My Project\\Release\\fc_clr.xml\".",
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrWebBrowser.xml\" to \"My Project\\Release\\clrWebBrowser.xml\".",
      "  Copying file from \"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrNativeWrapper.xml\" to \"My Project\\Release\\clrNativeWrapper.xml\".",
      "CopyFilesToOutputDirectory:",
      "  Copying file from \"obj\\Release\\My Project_cs4_5_1.dll\" to \"My Project\\Release\\My Project_cs4_5_1.dll\".",
      "  My Project -> C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Project_cs4_5_1.dll",
      "  Copying file from \"obj\\Release\\My Project_cs4_5_1.pdb\" to \"My Project\\Release\\My Project_cs4_5_1.pdb\".",
      "AfterBuild:",
      "  Copying file from \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Project_cs4_5_1.dll\" to \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\..\\..\\..\\upload\\My Project_cs4_5_1.dll\".",
      "  Copying file from \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project\\Release\\My Project_cs4_5_1.pdb\" to \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\..\\..\\..\\upload\\My Project_cs4_5_1.pdb\".",
      "Done Building Project \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj\" (rebuild target(s)).",
      "",
      "Build succeeded.",
      "    0 Warning(s)",
      "    0 Error(s)",
      "",
      "Time Elapsed 00:00:00.30",
      "<span class='info'>----------- command completed - 10:09:29 8 Oct 2018 -----------</span>"
    ],
    "success": true
  }
}

Example output if the build is not successful:

{
  "Java": {
    "output": [
      "Please wait while the workspace builds...",
      "Building My Workspace...",
      "",
      "Buildfile: C:\\My Workspace\\repository\\intel\\win32\\java\\build.xml",
      "",
      ...snip...
      "",
      "BUILD SUCCESSFUL",
      "Total time: 1 second",
      "<span class='info'>----------- command completed - 10:20:55 8 Oct 2018 -----------</span>",
      "Please wait while the project builds...",
      "Building My Project...",
      "",
      "Buildfile: C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build.xml",
      "",
      "clean:",
      "   [delete] Deleting directory C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "",
      "init:",
      "    [mkdir] Created dir: C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "",
      "compile:",
      "    [javac] Compiling 2 source files to C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build",
      "    [javac] C:\\My Workspace\\projects\\My Project\\scripts\\java\\com\\testplant\\testing\\Login.java:28: error: cannot find symbol",
      "    [javac] \t\tstartTransactions(\"Login\");",
      "    [javac] \t\t^",
      "    [javac]   symbol:   method startTransactions(String)",
      "    [javac]   location: class Login",
      "    [javac] Note: Some input files use unchecked or unsafe operations.",
      "    [javac] Note: Recompile with -Xlint:unchecked for details.",
      "    [javac] 1 error",
      "",
      "BUILD FAILED",
      "C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\java\\build.xml:19: Compile failed; see the compiler error output for details.",
      "",
      "Total time: 1 second",
      "<span class='info'>----------- command completed - 10:20:57 8 Oct 2018 -----------</span>"
    ],
    "success": false
  },
  "CSharp": {
    "output": [
      "Please wait while the workspace builds...",
      "Rebuilding My Workspace...",
      "",
      "Microsoft (R) Build Engine version 12.0.21005.1",
      ...snip...
      "",
      "Build succeeded.",
      "    0 Warning(s)",
      "    0 Error(s)",
      "",
      "Time Elapsed 00:00:00.31",
      "<span class='info'>----------- command completed - 10:20:53 8 Oct 2018 -----------</span>",
      "Please wait while the project builds...",
      "Rebuilding My Project...",
      "",
      "Microsoft (R) Build Engine version 12.0.21005.1",
      "[Microsoft .NET Framework, version 4.0.30319.42000]",
      "Copyright (C) Microsoft Corporation. All rights reserved.",
      "",
      "Build started 08/10/2018 10:20:53.",
      "Project \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj\" on node 1 (rebuild target(s)).",
      "CoreClean:",
      "  Deleting file \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\obj\\Release\\My Project.csprojResolveAssemblyReference.cache\".",
      "GenerateTargetFrameworkMonikerAttribute:",
      "Skipping target \"GenerateTargetFrameworkMonikerAttribute\" because all output files are up-to-date with respect to the input files.",
      "CoreCompile:",
      "  C:\\Program Files (x86)\\MSBuild\\12.0\\bin\\amd64\\Csc.exe /noconfig /unsafe- /checked- /nowarn:1701,1702 /nostdlib+ /platform:AnyCPU /errorreport:prompt /warn:4 /baseaddress:285212672 /define:TRACE /highentropyva+ /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\Accessibility.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\AxInterop.WFICALib.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrNativeWrapper.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\clrWebBrowser.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\fcCitrix.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\fc_clr.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\Interop.WFICALib.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\mscorlib.dll\" /reference:\"C:\\My Workspace\\repository\\upload\\My Workspace_cs4_5_1.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\Newtonsoft.Json.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\OCR.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.ComponentModel.DataAnnotations.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Core.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Data.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Drawing.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Web.Services.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Windows.Forms.dll\" /reference:\"C:\\Program Files (x86)\\Reference Assemblies\\Microsoft\\Framework\\.NETFramework\\v4.5\\System.Xml.dll\" /reference:\"D:\\Program Files (x86)\\eggPlant Performance\\bin\\TestPlantSoap.dll\" /debug+ /debug:pdbonly /filealign:4096 /optimize+ /out:\"obj\\Release\\My Project_cs4_5_1.dll\" /subsystemversion:6.00 /target:library /warnaserror- /utf8output \"C:\\My Workspace\\projects\\My Project\\scripts\\clr\\com\\testplant\\testing\\Citrix_Login.cs\" \"C:\\Users\\Jonathan Gover\\AppData\\Local\\Temp\\.NETFramework,Version=v4.5.AssemblyAttributes.cs\"",
      "c:\\My Workspace\\projects\\My Project\\scripts\\clr\\com\\testplant\\testing\\Citrix_Login.cs(39,4): error CS0103: The name 'StartTransactions' does not exist in the current context [C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj]",
      "Done Building Project \"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj\" (rebuild target(s)) -- FAILED.",
      "",
      "Build FAILED.",
      "",
      "\"C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj\" (rebuild target) (1) ->",
      "(CoreCompile target) -> ",
      "  c:\\My Workspace\\projects\\My Project\\scripts\\clr\\com\\testplant\\testing\\Citrix_Login.cs(39,4): error CS0103: The name 'StartTransactions' does not exist in the current context [C:\\My Workspace\\projects\\My Project\\repository\\intel\\win32\\cs4_5_1\\My Project.csproj]",
      "",
      "    0 Warning(s)",
      "    1 Error(s)",
      "",
      "Time Elapsed 00:00:00.23",
      "<span class='info'>----------- command completed - 10:20:54 8 Oct 2018 -----------</span>"
    ],
    "success": false
  }
}

Use this method to rebuild all the scripts within the specified workspace and project.

Eggplant Performance scripts are written in compiled languages: Java, C# or C++. This means that if scripts are added or modified, a build must take place before a test can be run.

This method performs a build, rebuilding (which includes compiling) all scripts in the workspace and project.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/rebuild

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

The POST data has no properties, it should just be an empty JSON object: {}

Response JSON

Property Type Description
Java object Build output object - only present if Java scripts were built
C# object Build output object - only present if C# scripts were built
C++ object Build output object - only present if C++ scripts were built

The Build output objects:

Property Type Description
success boolean Whether the scripts built successfully, or contained errors
output array[string] The lines of log output from the build process

If success is false, you will be unable to run a test until any script problems have been diagnosed and fixed. The output lines may contain information to help you do that.

Injectors

Create a static injector family

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/create_static_injector_family"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Injector Family", "platform": "win", "runtime": "64", "port": "39001"}'

The example POST data:

{
  "name": "My Injector Family",
  "platform": "win",
  "runtime": "64",
  "port": "39001"
}

The above command returns JSON structured like this:

{
  "My Injector Family": "/studio/api/1.0/My%20Workspace/injector_families/My%20Injector%20Family"
}

Use this method to create a new injector family with the specified name.

The new injector family will be able to contain definitions of static injectors - that is, injector machines whose hostname/IP address does not change.

HTTP Request

POST /studio/api/1.0/<workspace>/create_static_injector_family

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New injector family name
platform string The OS which all injectors in this family are running - win, linux or osx (optional, default is win)
runtime string (Only if platform is win) The bit-ness of the windows OS - 32 or 64 (optional, default is 32)
port string The port which all injectors in this family will listen on (optional, default is 39000)

Response HTTP status code

HTTP status code Meaning
200 OK An injector family with the specified name already exists
201 Created The new injector family was created successfully

Response JSON

Property Type Description
injector family name string A URL representing the newly-created injector family

Create a static injector

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/injector_families/My%20Injector%20Family/create_static_injector"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Injector", "host": "injector-01.eggplant.io"}'

The example POST data:

{
  "name": "My Injector",
  "host": "injector-01.eggplant.io"
}

The above command returns JSON structured like this:

{
  "My Injector": "/studio/api/1.0/My%20Workspace/injector_families/My%20Injector%20Family/My%20Injector"
}

Use this method to create a new injector in the specified injectorFamily.

An injector is a machine running the Eggplant Performance Injector software, which can be used to run virtual users during a performance test. This method adds an injector definition to the injector family, using the specified name and host.

HTTP Request

POST /studio/api/1.0/<workspace>/injector_families/<injectorFamily>/create_static_injector

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New injector name
host string Hostname or IP address of the injector machine

Response HTTP status code

HTTP status code Meaning
200 OK An injector with the specified name already exists in this injector family
201 Created The new injector was created successfully

Response JSON

Property Type Description
injector name string A URL representing the newly-created injector

Eggplant Functional Suites

Add an Eggplant Functional suite

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/add_eggplant_functional_suite"
  -H "Content-Type: application/json"
  --data-binary $'{"path": "C:/Suites/My Suite.suite"}'

The example POST data:

{
  "path": "C:/Suites/My Suite.suite"
}

The above command returns JSON structured like this:

{
  "message": "Eggplant Functional suite C:/Suites/My Suite.suite added to My Workspace"
}

Use this method to add an Eggplant Functional suite to the specified workspace.

The Eggplant Functional suite contains scripts which can be run by Eggplant Performance scripts - use the Generate an Eggplant Functional script method to generate the appropriate code.

HTTP Request

POST /studio/api/1.0/<workspace>/add_eggplant_functional_suite

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
path string The path of the Eggplant Functional suite folder

Response JSON

Property Type Description
message string A success message - only present if the suite was added or was already present
error string A failure message - only present if the suite was not added

Scripts

List scripts

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts"

The above command returns JSON structured like this:

{
  "Login": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Login",
  "Search": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Search",
}

Use this method to list all the scripts available in the specified project.

HTTP Request

GET /studio/api/1.0/<workspace>/projects/<project>/scripts

Response JSON

Property Type Description
script_name string A URL representing the script

Create a script

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/create_script"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "Login", "virtualUserType": "My Custom Java Web VU", "package": "com.testplant.testing"}'

The example POST data:

{
  "name": "Login",
  "virtualUserType": "My Custom Java Web VU",
  "package": "com.testplant.testing"
}

The above command returns JSON structured like this:

{
  "Login": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Login"
}

Use this method to create a script in the specified project.

The type of script created is determined by the virtualUserType parameter, which also determines the script language (Java, C# or C++).

The created script will be empty apart from the necessary template code provided by the virtual user type.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/create_script

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New script name
virtualUserType string The name of the virtual user type that will be able to run this script
package string The package (or namespace, for C# or C++ scripts) the new script will be in (optional, default matches the virtual user type)

Response HTTP status code

HTTP status code Meaning
200 OK A script with the specified name already exists
201 Created The new script was created successfully

Response JSON

Property Type Description
script name string A URL representing the newly-created script

Upload a script

It's highly recommended to write script code in a file and then upload it:

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Search"
  -H "Content-Type: text/plain"
  --data-binary @./Search.java

The above command returns JSON structured like this:

{
  "Search": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Search"
}

Use this method to overwrite the contents of the specified Eggplant Performance script with the POST data body.

This POST request should be sent as ContentType: text/plain. The entire contents of the script file within the project folder will be replaced with the body of the POST request.

To check that the uploaded script code still compiles, use the Rebuild scripts method.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/scripts/<script>

The Content-Type header must be set to text/plain.

Response JSON

Property Type Description
script name string A URL representing the updated script

Generate an Eggplant Functional script

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/generate_functional_script"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "Search", "inputParameters": ["keyword1", "keyword2"], "outputParameter": "Search_Out"}'

The example POST data:

{
  "name": "Search",
  "inputParameters": [
    "keyword1",
    "keyword2"
  ],
  "outputParameter": "Search_Out"
}

The above command returns JSON structured like this:

{
  "Search": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Search"
}

The code generated inside the script looks like this:

public class Search extends com.facilita.fc.eggPlant.EggplantVirtualUserScript
{
  @Override
  public void pre() throws Exception
  {
    // ...snip...
  }

  @Override
  public void script() throws Exception
  {
    // Run the Eggplant Functional script
    EggplantReturnData returnData = RunWithNewResults("\"Search1\"", getString("keyword1"), getString("keyword2"));
    set("Search_Out", returnData.returnValue());
  }
}

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/generate_functional_script"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "Subfolder/Login"}'

The example POST data:

{
  "name": "Subfolder/Login"
}

The above command returns JSON structured like this:

{
  "Search": "/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Subfolder_Login"
}

The code generated inside the script looks like this:

public class Subfolder_Login extends com.facilita.fc.eggPlant.EggplantVirtualUserScript
{
  @Override
  public void pre() throws Exception
  {
    // ...snip...
  }

  @Override
  public void script() throws Exception
  {
    // Run the Eggplant Functional script
    RunWithNewResults("\"Subfolder/Login\"");
  }
}

Use this method to generate an Eggplant Functional script in the specified project.

This is similar to the Create a Script method, but the script type will derive from Eggplant Functional Java Virtual User, and the script will have code added to it to run a script from an Eggplant Functional suite. A custom virtual user type can be specified with the virtualUserType parameter.

The name parameter is used both to name the new Eggplant Performance script, and to specify which script to run from an Eggplant Functional suite - see the examples to the right.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/generate_functional_script

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New script name
virtualUserType string The name of the virtual user type that will be able to run this script (optional)
inputParameters array[string] A list of parameters to pass to RunWithNewResults - the keys specified here are used to retrieve values from the data dictionary that are then available within the script from the Eggplant Functional suite (optional)
outputParameter string If specified, the return value from the Eggplant Functional script will be stored in the data dictionary using this key (optional)

Response HTTP status code

HTTP status code Meaning
200 OK A script with the specified name already exists
201 Created The new script was created successfully

Response JSON

Property Type Description
script name string A URL representing the newly-created script

Get a script

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/scripts/Login"

The above command returns JSON structured like this:

{
  "name": "Login",
  "virtualUserType": "My Custom Java Web VU",
  "package": "com.testplant.testing"
}

Use this method to get information about the specified script.

The type of script is determined by the virtualUserType value, which also determines the script language (Java, C# or C++).

HTTP Request

GET /studio/api/1.0/<workspace>/projects/<project>/scripts/<script>

Response JSON

Property Type Description
name string Script name
virtualUserType string The name of the virtual user type that will run this script
package string The package (or namespace, for C# or C++ scripts) the script is in (optional, default matches the virtual user type)

Workflows

Create a workflow

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/create_workflow"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Workflow", "initialScripts": ["Login"], "repeatedScripts": ["Search"], "finalScripts": ["Logout"]}'

The example POST data:

{
  "name": "My Workflow",
  "initialScripts": ["Login"],
  "repeatedScripts": ["Search"],
  "finalScripts": ["Logout"]
}

The above command returns JSON structured like this:

{
  "My Workflow": "/studio/api/1.0/My%20Workspace/projects/My%20Project/workflows/My%20Workflow"
}

Use this method to create a workflow in the specified project.

Scripts are added by name to the initial, repeated and final sections of the workflow. All named scripts must already exist within the project (see List scripts), and they must all have the same virtual user type.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/create_workflow

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New workflow name
initialScripts array[string] Names of scripts added to the initial section
repeatedScripts array[string] Names of scripts added to the repeated section
finalScripts array[string] Names of scripts added to the final section

Response HTTP status code

HTTP status code Meaning
200 OK A workflow with the specified name already exists
201 Created The new workflow was created successfully

Response JSON

Property Type Description
workflow name string A URL representing the newly-created workflow

Tests

List tests

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/tests"

The above command returns JSON structured like this:

{
  "tests": {
    "Load and Functional Test": "/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/Load%20and%20Functional%20Test",
    "My Test": "/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/My%20Test",
    "Large Performance Test": "/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/Large%20Performance%20Test"
  }
}

Use this method to list all the tests available in the specified project.

HTTP Request

GET /studio/api/1.0/<workspace>/projects/<project>/tests

Response JSON

Property Type Description
tests object Keys are test names, values are URLs

Create a test

A simple example:

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/create_test"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Test", "groups": {"Group A": {"workflow": "My Workflow"}}}'

The example POST data:

{
  "name": "My Test",
  "groups": {
    "Group A": {
      "workflow": "My Workflow"
    }
  }
}

For more complicated test definitions, it might be better to write the JSON into a file and upload it

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/create_test"
  -H "Content-Type: application/json"
  --data-binary @'./test definition.json'

The example POST data (note that not all of these options would be used at the same time, this just shows example values):

{
  "name": "My Test",
  "groups": {
    "Group A": {
      "workflow": "My Workflow",

      "virtualUsers": 100,
      "injectors": ["My Injector"],
      "distributionPolicy": 0,

      "iterationPolicy": 1,
      "iterationCount": 20,
      "executionTime": 3600000,
      "maxFailedIterations": 5,
      "pauseAfterIteration": 5000,
      "usePacing": true,

      "rampupSteps": 5,
      "rampupStepDuration": 30000,
      "rampupIntervalMinimum": 1000,
      "rampupIntervalMaximum": 5000,
      "rampupTime": 20000,
      "startGroupAfter": 10000,
      "alternateRampUp": true,

      "nonParameterizedPauseMinimum": 1000,
      "nonParameterizedPauseMaximum": 5000,
      "parameterizedPausePolicy": 1,
      "parameterizedPauseMinimum": 1000,
      "parameterizedPauseMaximum": 5000,
      "pauseFactor": 120,

      "backgroundScriptAutomaticStopTimeout": 300000,

      "eggplantFunctionalMainSuite": "C:/Suites/My Suite.suite",
      "eggplantFunctionalDetailedLogProportion": 50,
      "eggplantFunctionalLoggingLevel": 1,
      "eggplantFunctionalVerboseMessages": true,
      "remoteWorkInterval": 0.7,
      "eggplantFunctionalRDPScreenWidth": 1920,
      "eggplantFunctionalRDPScreenHeight": 1080,

      "webLogProportion": 50,
      "webSaveAllResponses": true,
      "webIterationsToKeep": 5,
      "webTimeEveryHttpRequest": true,
      "webIncludeQueryDataInRequestLabel": true,
      "webAddDynaTraceHeaders": false,

      "webSubRequestThreadCount": 5,
      "webMaxConnectRetries": 5,
      "webMaxNetworkDisconnections": 5,
      "webConnectTimeout": 30,
      "webReceiveTimeout": 120,
      "webHTTPHandler": "winhttp",
      "cookieSupport": true,
    }
  },
  "maxInjectorFailures": 0,
  "enableDefaultDataWarnings": true,
  "stopCloudInjectors": 0,
  "stopEggplantFunctionalInstances": false,
  "startSharedDataServer": false,
}

The above command returns JSON structured like this:

{
  "My Test": "/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/My%20Test"
}

Use this method to create a test in the specified project, which can be run by Test Controller.

A test is comprised of one or more virtual user groups, each of which contains a number of virtual users which all run the same script or workflow.

There are a lot of configuration options for virtual user groups - if you are not familiar with the way Eggplant Performance tests are defined then you should open Eggplant Performance Studio and try creating some tests using the UI first. This will help you understand the different options.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/create_test

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New test name
groups object Keys are group names, values are virtual user group objects
makeValid boolean If true, group names will be modified to remove invalid characters. This is useful if the group names are auto-generated, for example
maxInjectorFailures integer How many injectors can fail to start before the test startup as a whole is cancelled (default is 0)
enableDefaultDataWarnings boolean Write a message to the VU Event Log when a default value is used, i.e. if the Virtual User's data dictionary does not contain a value for the specified key (default is true)
stopCloudInjectors integer 0 for Stopped, 1 for Rebooted, 2 for Left running (default is 0)
stopEggplantFunctionalInstances boolean Stop all Eggplant Functional instances at the start and end of each test run (default is false)
startSharedDataServer boolean Start Shared Data Server at the beginning of the test (default is false)

Virtual user group objects

The only required property is workflow - all others are optional.

Property Type Description
workflow string The name of a workflow or script in the specified project; this will be run by the virtual users in the group during the test (required)

Virtual Users options:

Property Type Description
virtualUsers integer The number of virtual users in the group
injectors array[string] A list of injector names - virtual users will be distributed across these
distributionPolicy integer 0 to split virtual users equally among injectors, 1 to split virtual users equally among injector families

Iterations options:

Property Type Description
iterationPolicy integer 0 for Iteration count, 1 for Execution time, 2 for Iterate forever
iterationCount integer Number of iterations to execute (if iterationPolicy is 0)
executionTime integer Time (in milliseconds) to keep executing iterations (if iterationPolicy is 1)
maxFailedIterations integer After this many failed iterations, the virtual user will terminate (default is 5)
pauseAfterIteration integer Time (in milliseconds) to pause after each iteration
usePacing boolean Use pacing

Ramp-up options:

Property Type Description
rampupSteps integer Number of steps (default is 1)
rampupStepDuration integer Step duration (in milliseconds)
rampupIntervalMinimum integer Lower bound of the time (in milliseconds) to wait between virtual users starting during ramp up
rampupIntervalMaximum integer Upper bound of the time (in milliseconds) to wait between virtual users startung during ramp up
rampupTime integer Total ramp up time (in milliseconds) for the step - do not specify this if using rampupIntervalMinimum and rampupIntervalMaximum
startGroupAfter integer Time (in milliseconds) to wait after the test has started before beginning to ramp up this group
alternateRampUp boolean true for Alternate ramp-up (round-robin), false for Sequential ramp-up (one injector after another)

Pauses options:

Property Type Description
nonParameterizedPauseMinimum integer Minimum time (in milliseconds) to randomly pause if pause() is called without parameters
nonParameterizedPauseMaximum integer Maximum time (in milliseconds) to randomly pause if pause() is called without parameters
parameterizedPausePolicy integer 0 for Use actual values in script, 1 for Replace with random values, 2 for Apply adjustments with random values
parameterizedPauseMinimum integer Minimum time (in milliseconds) to replace/adjust pauses if pause(ms) is called with parameters
parameterizedPauseMaximum integer Maximum time (in milliseconds) to replace/adjust pauses if pause(ms) is called with parameters
pauseFactor integer Scale all script pauses by this percentage (default is 100)

Background scripts options

Property Type Description
backgroundScriptAutomaticStopTimeout integer Automatic stop timeout (in milliseconds)

Eggplant Functional options

Property Type Description
eggplantFunctionalMainSuite string Path to the Eggplant Functional suite in which the Eggplant Functional scripts are located
eggplantFunctionalDetailedLogProportion integer Turn on detailed logging for one virtual user in every n (set to 0 to turn off, default is 100)
eggplantFunctionalLoggingLevel integer Eggplant Functional logging level (0 to 2)
eggplantFunctionalVerboseMessages boolean Turn on verbose event log messages
remoteWorkInterval float This value is the time (in seconds) that Eggplant Functional waits between commands sent to the SUT
eggplantFunctionalRDPScreenWidth integer The width of the screen resolution Eggplant Functional will use when connecting to the SUT via RDP
eggplantFunctionalRDPScreenHeight integer The height of the screen resolution Eggplant Functional will use when connecting to the SUT via RDP

Web logging options

Property Type Description
webLogProportion integer Turn on detailed logging for one virtual user in every n (set to 0 to turn off, default is 100)
webSaveAllResponses boolean true to save all HTTP responses, false to save only text responses
webIterationsToKeep integer Save detailed web log data for the last n iterations
webTimeEveryHttpRequest boolean Time every HTTP request
webIncludeQueryDataInRequestLabel boolean Include query data in request label
webAddDynaTraceHeaders boolean Add dynaTrace™ header to HTTP requests

Web options

Property Type Description
webSubRequestThreadCount integer The maximum number of threads that will be used to fetch sub-requests from the server
webMaxConnectRetries integer Max connect retries in case of network errors
webMaxNetworkDisconnections integer Max network disconnections before giving up
webConnectTimeout integer Connect timeout (in seconds)
webReceiveTimeout integer Receive timeout (in seconds)
webHTTPHandler string Connection handler - can be winhttp (default), wininet or internal
cookieSupport boolean Cookie support

Response HTTP status code

HTTP status code Meaning
200 OK A test with the specified name already exists
201 Created The new test was created successfully

Response JSON

Property Type Description
test name string A URL representing the newly-created test

Get a test

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/My%20Test"

The above command returns JSON structured like this:

{
  "name": "My Test",
  "groups": {
    "Group A": {
      "workflow": "My Workflow",

      "virtualUsers": 100,
      "injectors": ["My Injector"],
      "distributionPolicy": 0,

      "iterationPolicy": 1,
      "iterationCount": 20,
      "executionTime": 3600000,
      "maxFailedIterations": 5,
      "pauseAfterIteration": 5000,
      "usePacing": true,

      "rampupSteps": 5,
      "rampupStepDuration": 30000,
      "rampupIntervalMinimum": 1000,
      "rampupIntervalMaximum": 5000,
      "rampupTime": 20000,
      "startGroupAfter": 10000,
      "alternateRampUp": true,

      "nonParameterizedPauseMinimum": 1000,
      "nonParameterizedPauseMaximum": 5000,
      "parameterizedPausePolicy": 1,
      "parameterizedPauseMinimum": 1000,
      "parameterizedPauseMaximum": 5000,
      "pauseFactor": 120,

      "backgroundScriptAutomaticStopTimeout": 300000,

      "eggplantFunctionalMainSuite": "C:/Suites/My Suite.suite",
      "eggplantFunctionalDetailedLogProportion": 50,
      "eggplantFunctionalLoggingLevel": 1,
      "eggplantFunctionalVerboseMessages": true,
      "remoteWorkInterval": 0.7,
      "eggplantFunctionalRDPScreenWidth": 1920,
      "eggplantFunctionalRDPScreenHeight": 1080,

      "webLogProportion": 50,
      "webSaveAllResponses": true,
      "webIterationsToKeep": 5,
      "webTimeEveryHttpRequest": true,
      "webIncludeQueryDataInRequestLabel": true,
      "webAddDynaTraceHeaders": false,

      "webSubRequestThreadCount": 5,
      "webMaxConnectRetries": 5,
      "webMaxNetworkDisconnections": 5,
      "webConnectTimeout": 30,
      "webReceiveTimeout": 120,
      "webHTTPHandler": "winhttp",
      "cookieSupport": true,
    }
  },
  "maxInjectorFailures": 0,
  "enableDefaultDataWarnings": true,
  "stopCloudInjectors": 0,
  "stopEggplantFunctionalInstances": false,
  "startSharedDataServer": false,
}

Use this method to get information about the specified test.

A test is comprised of one or more virtual user groups, each of which contains a number of virtual users which all run the same script or workflow.

There are a lot of configuration options for virtual user groups - if you are not familiar with the way Eggplant Performance tests are defined then you should open Eggplant Performance Studio and try creating some tests using the UI first. This will help you understand the different options.

HTTP Request

GET /studio/api/1.0/<workspace>/projects/<project>/tests/<test>

Response JSON

Property Type Description
name string Test name
groups object Keys are group names, values are virtual user group objects
maxInjectorFailures integer How many injectors can fail to start before the test startup as a whole is cancelled (default is 0)
enableDefaultDataWarnings boolean Write a message to the VU Event Log when a default value is used, i.e. if the Virtual User's data dictionary does not contain a value for the specified key (default is true)
stopCloudInjectors integer 0 for Stopped, 1 for Rebooted, 2 for Left running (default is 0)
stopEggplantFunctionalInstances boolean Stop all Eggplant Functional instances at the start and end of each test run (default is false)
startSharedDataServer boolean Start Shared Data Server at the beginning of the test (default is false)

Virtual user group objects

Property Type Description
workflow string The name of a workflow or script in the specified project; this will be run by the virtual users in the group during the test (required)

Virtual Users options:

Property Type Description
virtualUsers integer The number of virtual users in the group
injectors array[string] A list of injector names - virtual users will be distributed across these
distributionPolicy integer 0 to split virtual users equally among injectors, 1 to split virtual users equally among injector families

Iterations options:

Property Type Description
iterationPolicy integer 0 for Iteration count, 1 for Execution time, 2 for Iterate forever
iterationCount integer Number of iterations to execute (if iterationPolicy is 0)
executionTime integer Time (in milliseconds) to keep executing iterations (if iterationPolicy is 1)
maxFailedIterations integer After this many failed iterations, the virtual user will terminate (default is 5)
pauseAfterIteration integer Time (in milliseconds) to pause after each iteration
usePacing boolean Use pacing

Ramp-up options:

Property Type Description
rampupSteps integer Number of steps (default is 1)
rampupStepDuration integer Step duration (in milliseconds)
rampupIntervalMinimum integer Lower bound of the time (in milliseconds) to wait between virtual users starting during ramp up
rampupIntervalMaximum integer Upper bound of the time (in milliseconds) to wait between virtual users startung during ramp up
rampupTime integer Total ramp up time (in milliseconds) for the step - do not specify this if using rampupIntervalMinimum and rampupIntervalMaximum
startGroupAfter integer Time (in milliseconds) to wait after the test has started before beginning to ramp up this group
alternateRampUp boolean true for Alternate ramp-up (round-robin), false for Sequential ramp-up (one injector after another)

Pauses options:

Property Type Description
nonParameterizedPauseMinimum integer Minimum time (in milliseconds) to randomly pause if pause() is called without parameters
nonParameterizedPauseMaximum integer Maximum time (in milliseconds) to randomly pause if pause() is called without parameters
parameterizedPausePolicy integer 0 for Use actual values in script, 1 for Replace with random values, 2 for Apply adjustments with random values
parameterizedPauseMinimum integer Minimum time (in milliseconds) to replace/adjust pauses if pause(ms) is called with parameters
parameterizedPauseMaximum integer Maximum time (in milliseconds) to replace/adjust pauses if pause(ms) is called with parameters
pauseFactor integer Scale all script pauses by this percentage (default is 100)

Background scripts options

Property Type Description
backgroundScriptAutomaticStopTimeout integer Automatic stop timeout (in milliseconds)

Eggplant Functional options

These fields may not be present in the response JSON if the test does not have any Eggplant Functional virtual users.

Property Type Description
eggplantFunctionalMainSuite string Path to the Eggplant Functional suite in which the Eggplant Functional scripts are located
eggplantFunctionalDetailedLogProportion integer Turn on detailed logging for one virtual user in every n (set to 0 to turn off, default is 100)
eggplantFunctionalLoggingLevel integer Eggplant Functional logging level (0 to 2)
eggplantFunctionalVerboseMessages boolean Turn on verbose event log messages
remoteWorkInterval float This value is the time (in seconds) that Eggplant Functional waits between commands sent to the SUT
eggplantFunctionalRDPScreenWidth integer The width of the screen resolution Eggplant Functional will use when connecting to the SUT via RDP
eggplantFunctionalRDPScreenHeight integer The height of the screen resolution Eggplant Functional will use when connecting to the SUT via RDP

Web logging options

These fields may not be present in the response JSON if the test does not have any Web virtual users.

Property Type Description
webLogProportion integer Turn on detailed logging for one virtual user in every n (set to 0 to turn off, default is 100)
webSaveAllResponses boolean true to save all HTTP responses, false to save only text responses
webIterationsToKeep integer Save detailed web log data for the last n iterations
webTimeEveryHttpRequest boolean Time every HTTP request
webIncludeQueryDataInRequestLabel boolean Include query data in request label
webAddDynaTraceHeaders boolean Add dynaTrace™ header to HTTP requests

Web options

These fields may not be present in the response JSON if the test does not have any Web virtual users.

Property Type Description
webSubRequestThreadCount integer The maximum number of threads that will be used to fetch sub-requests from the server
webMaxConnectRetries integer Max connect retries in case of network errors
webMaxNetworkDisconnections integer Max network disconnections before giving up
webConnectTimeout integer Connect timeout (in seconds)
webReceiveTimeout integer Receive timeout (in seconds)
webHTTPHandler string Connection handler - can be winhttp (default), wininet or internal
cookieSupport boolean Cookie support

Create a data binding

A simple example:

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/My%20Test/create_data_binding"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Dictionary Binding", "dataSource": "My Dictionary"}'

The example POST data:

{
  "name": "My Dictionary Binding",
  "dataSource": "My Dictionary"
}

For more complicated data bindings, it might be better to write the JSON into a file and upload it

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/tests/My%20Test/create_data_binding"
  -H "Content-Type: application/json"
  --data-binary @'./data binding.json'

The example POST data for a data table - single group (note that not all of these options would be used at the same time, this just shows example values)

{
  "name": "My Table Binding",
  "dataSource": "My Table",
  "isSingleGroup": true,

  "groupName": "Group B",
  "startAtRow": 5,
  "accessAllRows": false,
  "rowsPerVU": 10,
  "shareRowsBetweenVus": false,
  "rowVisitationPolicy": 4,
  "recycleRows": true,
  "randomizePolicy": 1,
  "seed": 12345,
  "advanceAutomatically": false
}

The example POST data for a data table - multiple groups

{
  "name": "My Table Binding",
  "dataSource": "My Table",
  "isSingleGroup": false,

  "isAvailableToAllGroups": false,
  "groupNames": ["Group A", "Group C"],
  "shareRowsBetweenVus": true
}

The above command returns JSON structured like this:

{}

Use this method to create a data binding from a dataSource to one or more virtual user groups in the specified test.

This enables virtual users to access data from the data source during a test run. There are different options for the different types of data source - tables and dictionaries.

There are a lot of configuration options for data bindings - if you are not familiar with the way Eggplant Performance tests are defined then you should open Eggplant Performance Studio and try creating some tests and data bindings using the UI first. This will help you understand the different options.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/tests/<test>/create_data_binding

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Required properties

Property Type Description
name string New data binding name (required)
dataSource string The name of an existing data source in the specified project (required)

Data dictionary

If the specified dataSource is a dictionary, use these properties:

Property Type Description
isAvailableToAllGroups boolean Whether virtual users in every group can access the keys/values in this dictionary (default is true)
groupNames array[string] If isAvailableToAllGroups is false, a list of names of virtual user groups which can access the keys/values in this dictionary

Data table (single group)

If the specified dataSource is a table, and the rows are to be divided among virtual users in a single group, use these properties:

Property Type Description
isSingleGroup boolean Set this to true
groupName string Name of the virtual user group
startAtRow integer Assign rows from this row onwards (default is 1)
accessAllRows boolean Allow each virtual user to access all rows in the table if true, otherwise use a fixed number of rows per virtual user
rowsPerVU integer If accessAllRows is false, set how many rows of data each virtual user will be able to access (one per iteration)
shareRowsBetweenVus boolean If accessAllRows is false, then if this is true, each row in the table can be used by more than one virtual user
rowVisitationPolicy integer 1 to visit rows in the order they appear in the table, 2 to randomly pick and remove rows, 4 to randomly pick and replace rows
recycleRows boolean If rowVisitationPolicy is 1, then if this is true, reuse rows if number of iterations is greater than number of rows
randomizePolicy integer If rowVisitationPolicy is 2 or 4, then set this to 1 to always start with the same random seed, or 2 to use a different random seed every time the test runs
seed integer If randomizePolicy is 1, the seed to initialise the random number generator when picking random rows (not the row number)
advanceAutomatically boolean If true, the virtual user will move to the next row at the end of each iteration

Data table (multiple groups)

If the specified dataSource is a table, and the rows are to be allocated one per virtual user across one or more groups, use these properties:

Property Type Description
isSingleGroup boolean Set this to false
isAvailableToAllGroups boolean Whether virtual users in every group can access the rows in this table (default is true)
groupNames array[string] If isAvailableToAllGroups is false, a list of names of virtual user groups which can access the rows in this table
shareRowsBetweenVus boolean If true, each row in the table can be used by more than one virtual user

Response JSON

A correct request will return 200 OK and an empty JSON object {}

Data Sources

Create a data source

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/create_data_source"
  -H "Content-Type: application/json"
  --data-binary $'{"name": "My Table", "type": "table"}'

The example POST data:

{
  "name": "My Table",
  "type": "table"
}

The above command returns JSON structured like this:

{
  "My Table": "/studio/api/1.0/My%20Workspace/projects/My%20Project/data_sources/My%20Table"
}

Use this method to create a data source (table or dictionary) in the specified project.

Data sources are initially created with no data - use the Upload a data source method to provide data.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/create_data_source

The POST data must be sent in JSON format, and the Content-Type header set to application/json.

Property Type Description
name string New data source name
type string Type of data source - table or dictionary

Response HTTP status code

HTTP status code Meaning
200 OK A data source with the specified name already exists
201 Created The new data source was created successfully

Response JSON

Property Type Description
data source name string A URL representing the newly-created data source

Upload a data source

It's highly recommended to write data in a file and then upload it:

curl "http://localhost:5001/studio/api/1.0/My%20Workspace/projects/My%20Project/data_sources/My%20Table"
  -H "Content-Type: text/plain"
  --data-binary @./data.csv

For a data table, the file should look like this:

key_1,key_2,key_3
value_A1,value_A2,value_A3
value_B1,value_B2,value_B3
value_C1,value_C2,value_C3

For a data dictionary, the file should look like this:

key_1=value_1
key_2=value_2
key_3=value_3

The above command returns JSON structured like this:

{
  "My Table": "/studio/api/1.0/My%20Workspace/projects/My%20Project/data_sources/My%20Table"
}

Use this method to overwrite the contents of the specified Eggplant Performance dataSource with the POST data body.

This POST request should be sent as ContentType: text/plain. The entire contents of the data source file (table or dictionary) within the project folder will be replaced with the body of the POST request.

HTTP Request

POST /studio/api/1.0/<workspace>/projects/<project>/data_sources/<dataSource>

The Content-Type header must be set to text/plain.

Response JSON

Property Type Description
data source name string A URL representing the updated data source
Generated at 12:19:24 on 13 Aug 2024 - 9.5.7.98
shell