Adding Transactions

The easiest way to add Transactions that describe the behavior of a Service is uploading files in a supported format. The Transaction Repository supports HTTP(s) stateless transactions. SOAP over HTTP(s) Transactions are supported as long as you provide the required headers.

You can also manually add and edit Transactions.

In a Transaction, you provide criteria by which a request matches URLs, headers, query parameters, cookies, credentials, or request body, and then a response that the virtual service returns when a match is detected. The Request criteria can be a fully formed request, like a valid GET call, or a regular expression that would return a match for multiple potential requests. For more information about matching and strategies for creating requests, see Request Matching Examples.

The following file formats are supported:

  • Swagger 2.0 (JSON and YAML)
  • Swagger 3.0/Open API (JSON and YAML)
    Note: You can import multiple Swagger files in a zip file, as long as the main file in the zip is called index.json or index.yaml.
  • HAR files
  • RR Pairs
    Note: Upload RR pairs as a zip file with one or more pairs. File formats must follow the name-req and name-rsp format, where the name string is the same across pairs. For example: login-req.txt and login-rsp.txt.
  • WSDL (WSDL or zip for multiple files)
    Note: You can import multiple WSDL files in a zip format, as long as the main file in the zip is called index.wsdl.
  • Exported Transactions JSON file, created from the export operation from the Service drop-down list. For more information, see Export Service with all Transactions.
  • JSON file created from the BlazeMeter Proxy Recorder.
  • WireMock and Mocklab definitions in JSON format


Add Transactions from a File

You can add Transactions from a variety of sources. You can edit those Transactions after you import them to tune the matching criteria. For more information about the Request and Response fields, see Adding Transactions Manually.

Tags make Transactions easier to identify, especially within a large Service. You can provide tag definitions to apply the defined tags to all imported Transactions. Or you can define tags at the Transaction level after import.

Follow these steps:

  1. Log into your BlazeMeter account and click the Service Virtualization tab.
  2. Click Asset Catalog.
  3. Drag your file into the upload area, or click the area to browse for the file you want. This file should contain all of the Transactions that you want to use for your virtual service.
    dragging and dropping files into the upload area
    Note: If you want to upload multiple Swagger files using a zip file, the main file in the zip file must be named index.json or index.yaml for the upload to work.
    The Import Transactions dialog opens.
    importing transactions
  4. Select the Service that you want to add these Transactions to.
    To create a new Service:
    1. Click Select Service.
    2. Enter the name for your new Service and click Add Service.
  5. If you want to assign one or more tags to these Transactions, type the tag name(s) in the Tags field and press Enter.
    To enter multiple tags, press Enter after each tag name.
  6. Click Import.
    The Transactions are added to the transaction repository as part of the selected service.
    transaction import results


Edit Transactions

When you import files into the transaction repository, the Transactions in the file are imported exactly as they appear in the file. You will often want or need to make those Transactions more useful by updating the URL to broaden the matching criteria, or duplicate the Transaction to add a similar Transaction that was not available in the file.

Follow these steps:

  1. In the main menu, navigate to the Service Virtualization tab and click Virtual Services.
  2. Click the Open Details button to expand a virtual service.
    viewing virtual service details
    You can see a list of transactions in your catalog and in the particular virtual service.
  3. Click the Edit Transaction button next to the transaction that you want to edit. You can edit the transaction in your catalog, as well as in this virtual service.
    edit transactions button
  4. (Optional) If you want to preserve the existing Transaction, you can clone it. See Clone Transactions.
  5. Update Name, Service, and Description as needed.
  6. If you want to assign one or more tags to these transactions, type the tag name(s) in the Tags field and press Enter.
    To enter multiple tags, press Enter after each tag name.
  7. In the Request Matcher tab, make changes to the existing request data.
    For example, you can change a direct URL into a regular expression that will match multiple similar requests. Or you can add parameters or other additional matching criteria to a request.
    See Request Matching Examples for more information about modifying request data.
  8. Click Save.
    The updated Transaction is saved and available for adding into a virtual service or Template.


Clone Transactions

Follow these steps:

  1. Log into your BlazeMeter account and click the Service Virtualization tab.
  2. Click the Asset Catalog tab.
  3. Click the Transactions tab.
  4. In the Actions column, click the Clone Transactions button.
    clone transactions
    A duplicate of the Transaction is created.

You can expand the new Transaction and make any required edits there.


Add Transactions Manually

You can manually add Transactions to the repository to account for Transactions that might not be represented in a file or specification. Cloning a similar Transaction is the simplest way to add a new Transaction without importing, but you can create a Transaction from scratch if a good reference point is not available.

Follow these steps:

  1. Log into your BlazeMeter account and click the Service Virtualization tab.
  2. Click Asset Catalog.
  3. Click the + button to Add Transaction.
    The Transaction details page opens.
    transactions request matcher
  4. Enter a name for the Transaction in the Name field.
  5. Select the Service you want to add this Transaction to from the Service drop-down.
    To create a new Service:
    1. Click Select Service.
    2. Enter the name for your new Service and click Add Service.
  6. If you want to assign one or more tags to these transactions, type the tag name(s) in the Tags field and press Enter.
    To enter multiple tags, press Enter after each tag name.
  7. Enter a Description for the Transaction.

In the Request Matcher tab:

  1. Select the type of Transaction you want to add.
    The following transaction types are supported:
    • GET
    • POST
    • PUT
    • DELETE
    • PATCH
    • OPTIONS
    • TRACE
    • HEAD
    • CONNECT
    • ANY
  2. Select the proper option on the right of the URL field:
    • Select Equals if you are entering a specific URL in the field that you only want to match when that specific request URL is received.
    • Select Matches regex if you are entering a URL with regular expression elements that you want to match when the request URL fulfills the regex matching criteria.
  3. Enter the URL or regular expression in the URL field.
    If you are editing an imported Transaction, you can change the URL to a regular expression to make the Transaction match against a broader set of requests. For help with URL matching, see Request Matching Examples.
  4. Click Add in each of the following tabs to add the details of your Transaction if you want to match against any of these entities in your request:
    For detailed help and examples, see Request Matching Examples.
    • Headers
      As a best practice, avoid using the "host" header in any request matching criteria, as it can adversely affect transaction matching.
    • Query Parameters
    • Cookies
    • Credentials
    • Body

      • equals

      • equals (case insensitive)

      • contains text

      • matches regex

      • does not match regex

      • is absent

      • equals to XML

      • equals to JSON

      • matches XPath

      • matches XPath from CDATA

      • matches JSON Path

      • WSDL Schema Validation

In the Response tab:

  1. Select the Status Code that the transaction will return with the response when a match occurs.

    virtual service response tab

  2. (Optional) Click the Plus to add one or more Conditional Status Codes. The previously selected default status code will become the Fallback Status Code, verify and adjust it if necessary.

    • Conditional Status Code
      Select a status code that will be returned only when a given condition occurs.

    • Expression
      Enter a parameter upon which the condition depends.

    • Operator

      Select a comparison operator for the condition:

      • equals
      • equals (case insensitive)
      • contains text
      • matches regex
      • does not match regex
      • equals to JSON
      • matches JSON Path
      • equals to XML
      • matches XPath
      • matches XPath from CDATA
      • greater than
      • less than

    • Value
      Enter the comparison value.

    virtual service response tab

  3. Enter the full response body in the Body field.
  4. (Optional) Add Response Headers. Use the Edit Wizard to define dynamic response values.
  5. (Optional) Provide Proxy URL values.
  6. (Optional) Specify a Think Time to simulate realistic delays. For more information, see Simulating Irregular Response Latencies (Think Time).
  7. (Optional) Under Redirect to Live System, define the URL of your Live System Endpoint. All requests that match this transaction are conditionally redirected to the specified live system. For more information about use cases, see Live System Endpoint.
  8. (Optional) Under SSL Authentication, Select an SSL Authentication:

    • No Authentication

    • 1-way SSL

    • 2-way SSL


    Select an existing Keystore or upload a new one. Provide the Keystore Password and the password used to access individual keys in the keystore.
    (Optional) To define how to identify during SSL/TLS communication using an alias for a private key entry defined in your keystore, select the Alias and provide an Alias Password.
  9. Click Save.
    The Transaction is added to the transaction repository.



Request Matching Examples

Adding or editing the requests in your Transactions to match against the appropriate range of potential requests that you might use for testing helps make your virtual services powerful and efficient.

This topic includes guidance and examples for entering matching criteria for each one of the request matcher inputs:

URL

The URL is the primary request URL. You can format the URL in a variety of ways for matching purposes, including:

  • A complete request URL that will only match when the virtual service receives that exact request. Use the Equals setting for this type of request. Any parameters must be entered in the Query Parameters section.
  • A partial request URL with regular expression text that will return a match for any request that matches the expression criteria. Use the Matches regex setting for this type of request.
  • A complete request URL that serves as the root of a request with parameters or other information that you include in the other matching fields. For example, you can include a root URL, and then enter parameter matching criteria in the Query Parameters section that uses regular expressions.

Examples:

The following URL returns a direct match of the AWS S3 API GET request for an object named report.json:
request matcher example for an object

This URL returns a match for a petstore API GET request that includes the string 'dog' in its path:

request matcher example for a string match

Matches:

  • https://petstore.blazemeter.com/api/pets/dogs
  • https://petstore.blazemeter.com/api/pets/animals/dog
  • https://petstore.blazemeter.com/api/pets/animals/dogs/small

Does Not Match:

  • https://petstore.blazemeter.com/api/pets/cats
  • https://petstore.blazemeter.com/api/pets/Dogs

The RegEx matches are case sensitive.

Headers

Use the Headers field to define all headers that must be present to return a match. The header value can be an exact value or a regular expression.

When you define multiple headers, all headers much be present for the request to match. If headers are optional, deselect their Required checkbox.

Example:

example that matches a header

This URL returns a match for a petstore GET request when an Accept header is included with the exact value of application/json.

As a best practice, avoid using the Host header in any request matching criteria, as it can adversely affect transaction matching.

Query Parameters

Use query parameters to define a range of parameters that will result in a match. You can include multiple parameters, and the parameters can be exact values or regular expressions.

When you define multiple parameters, all parameters much be present for the request to match. If parameters are optional, deselect their Required checkbox.

When you use an equals matcher with query parameters, the incoming value is decoded before the comparison is made. Therefore, if you are trying to match on a value that is encoded within a URL, like "http://notreal/?status=25%25%20full", use the decoded value in the matcher ("25% full") instead of the encoded value in the URL.

Example 1:

example request matcher for a query parameter matching a regular expression for any string

The example request in the screenshot matches any time when the URL matches the given URL and the search_criteria query parameter is present with any value, including an empty value. If the optional pet parameter is in the request, its value must match cat to match, but if pet is not part of the request, then the value cat is not considered.

Example 1 matches:

https://petstore.blazemeter.com/api/pets?search_criteria=brown

https://petstore.blazemeter.com/api/pets?search_criteria=white&pet=cat

https://petstore.blazemeter.com/api/pets?search_criteria

Example 1 does not match:

https://petstore.blazemeter.com/api/pets

https://petstore.blazemeter.com/api/pets?pet=dog

https://petstore.blazemeter.com/api/pets?search_criteria=white&pet=dog

https://petstore.blazemeter.com/api/pets?page=1

Example 2:

example request matcher for a query parameter matching a regular expression for one of two specific strings

The second example matches any request when the URL matches the URL and the search_criteria parameter contains the values white or black, defined through the standard regular expression (white|black).

Example 2 matches:

https://petstore.blazemeter.com/api/pets?search_criteria=black

https://petstore.blazemeter.com/api/pets?search_criteria=white

Example 2 does not match:

https://petstore.blazemeter.com/api/pets?search_criteria=brown

https://petstore.blazemeter.com/api/pets

Example 3:

example request matcher for a query parameter that must be absent

The third example matches a request that contains the values white or black in the search_criteria query parameter (defined as regular expression) and does not contain the query parameter store.

Example 3 matches:

https://petstore.blazemeter.com/api/pets?search_criteria=black

https://petstore.blazemeter.com/api/pets?search_criteria=white&page=1

Example 3 does not match:

https://petstore.blazemeter.com/api/pets?search_criteria=white&store=london

https://petstore.blazemeter.com/api/pets?store=london

https://petstore.blazemeter.com/api/pets?page=1

Cookies

Include cookies if the request needs to pass certain cookies to return a match.

Credentials

Include credentials if the request needs to include specific credentials to return a match.

Body

Include body text in the Body section if the request needs to include specific text in the request body to return a match. You can include multiple match conditions that are important to you without having to define the entire request body.

For example, you might include a match condition looking for an XPATH state, and a second match condition looking for a status code in the body. In this scenario, the entire request body doesn't have to match - only the XPATH state and status code that you specified. This is a more efficient method for defining the criteria that matter to you, because if you simply included the entire request body instead, any small deviation in the body content would cause the transaction to not match.

To match the content of XML or JSON documents semantically, while ignoring the format, use the Equals XML or Equals JSON matchers. These matchers ignore whitespace, formatting, and the order of fields.
To match JSON or XML fields that contain specific values, while the rest of the fields can have any value, use placeholders.

Examples:

  • Examples of JSON placeholders:

    The following JSON Body Matcher requires a string match for "name": "John", and accepts any content for the membership and email fields:

    {
      "name":        "John", 
      "membership": "${json-unit.any-string}", 
      "email":      "${json-unit.ignore-element}" 
    }
  • Examples of XML placeholders:

  • Examples how to add a WSDL schema file (xsd) for validation:

    • Either copy and paste the xsd into the text area.

    • Click the arrow and drag and drop the xsd file into the text area.

    • Click the arrow and upload the xsd file.

For more information, see How to Do Advanced Request Matching With BlazeMeter.

Nested Path Formats for Request Matchers

Transactions now support a new in-house format of XPath and JSONPath matchers. This format can be used to check if an element matching the XPath or JSONPath matches a specific value or to a Regex so you can use Regular Expressions together with XPath and JSONPath. The structure of this new format looks like:

[[ PATH, Function ]]

The only available functions supported right now are “equalTo” (to match a specific value) and “matching” (to evaluate against a Regex). Here are some examples of this format:

XPath:

  • [[ /company/employee/name/text(), equalTo(John) ]] - Finds an element named “John”
  • [[ /company/employee/name/text(), matching(.*)]] - Finds an element with any name

JsonPath:

  • [[ $.company.employee.name, equalTo(John) ]] - Finds an element named “John”
  • [[ $.company.employee.name, matching(.*)]] - Finds an element with any name

The XPath and JSONPath request wizards have been changed to generate paths as per this new in-house format.

Return a Response Collection from BlazeMeter Test Data

As a tester who is creating a "GET all" type request as a virtual service transaction, you need to return collections of data.

For example, you have mock data for five accounts. For a "GET account by id" transaction, and for five different IDs in the request, you expect five different responses. And for a transaction "GET all accounts", you expect it to return a collection of all five accounts.

Virtual services use a templating library that supports "with" and "for each" loop constructs.

To retrieve all users (all rows in a dataset):

{
"users" : 
    [ 
        ${#each (blazeData 'users') as |user|} 
	        { "id": ${user.id}, "firstname": ${user.firstname}, "lastname": ${user.lastname} } 
	    ${#unless @last}, ${/unless} 
	    ${/each} 
    ]
}

To retrieve all users with an offset and a limit:

${#with (blazeData 'users' 'skip $request.query.offset' 'limit $request.query.limit') as |dataset|} 
    ${#assign 'totalSize'}${blazeDataSize 'users'}${/assign} 
    {
    "users" : 
	    [ 
	        ${#each dataset as |user| } 
	            { "id": "${user.id}", "firstname": "${user.firstname}", "lastname": "${user.lastname}", } 
	            ${#unless @last}, ${/unless}
	        ${/each} 
	    ], 
    "pagination" : 
	    { 
	        "total_records": ${totalSize}, 
	        "current_page": ${math (math request.query.offset '/' request.query.limit) '+' 1}, 
	        "total_pages": ${math totalSize '/' request.query.limit}, 
	        "next_page": ${math (math request.query.offset '/' request.query.limit) '+' 2}, 
	        "prev_page": ${math request.query.offset '/' request.query.limit} 
	    }
    } 
${/with}

To show all possible parameters with a limit of 2 and id > 5

{
 "users" : 
        [ 
            ${#each (blazeData 'users' 'limit 2' 'where id > 5' 'skip 2' 'order by lastname desc') as |user|} 
                { "firstname": ${user.firstname}, "lastname": ${user.lastname}, }
                ${#unless @last}, ${/unless} 
            ${/each} 
        ]
}

Live System Endpoint

You cannot or do not want to virtualize 100% of the service, but only the endpoints that you are testing. BlazeMeter offers the possibility to redirect remaining requests to the live service. You can hard-code the name of the Live System endpoint or use dynamic variables in the endpoint definition.

You have two options:

On virtual service level, you can redirect all unmatched requests to the live system

  • If you select Redirect to live system in the No Matching Requests field, a new field Live System Endpoint appears. Enter the live URL.
    The field also supports custom parameters defined in the Configurations tab and in the Test Data pane.
    • The following example uses Configuration parameters:
      https://${config.server}:${config.port}
    • In the following example, $(config.host} is defined on the Configurations tab while ${path} and ${gvalue} are Test Data Parameters:
      https://${config.host}/${path}/${gvalue}


    From now on, all requests that are not matched by a transaction are forwarded to the endpoint specified.

On the Transaction level, you can redirect requests to the live system that match specific Transactions.

  • You can use the Request Matchers of Transactions as condition to redirect matching requests to the live system. In the Transaction editor, open the Response tab, and provide the URL of the Live System Endpoint on the Redirect to live system tab to enable this behavior. The field also accepts test data parameters.
  • If you enable Failover Mode and the live service fails, the transaction fails gracefully and returns the transaction response.
  • You can select an SSL Authentication:
    • No Authentication
    • 1-way SSL
    • 2-way SSL

    Select an existing Keystore or upload a new one. Provide the Keystore Password and the password used to access individual keys in the keystore.
    (Optional) To define how to identify during SSL/TLS communication using an alias for a private key entry defined in your keystore, select the Alias and provide an Alias Password.

Enter the URL in the following format:

http[s]://<HOST>[:<PORT>][/BASE_PATH]

Schema and host are required and everything else is optional.
Examples:

If the Live System Endpoint contains value https://live:5443/ser1, the incoming request with https://mock/ping will be forwarded to https://live:5443/ser1/ping .

If the Live System Endpoint contains value https://live:5443, the incoming request with https://mock/ping will be forwarded to https://live:5443/ping .

If needed, provide client certificates when calling live endpoints in virtual services, on transactions level, in webhooks and in HTTP processing actions. Every uploaded certificate is stored in the Certificate Store and can be reused later.