Creating a project

Creating a project is the first step to start working with IBM® DevOps Test Integrations and APIs (Test Integrations and APIs). A project contains the basic settings used by tests. You can also find different interactive guides on the Home page that provide you with information on the common tasks that you can accomplish in Test Integrations and APIs.
You must have installed Test Integrations and APIs. If you have any other IBM DevOps Test Virtualization Control Panel (Test Virtualization Control Panel) session that is running, you must ensure to close it.

After you launch Test Integrations and APIs, you must create a new project, provide a name for your project and save it on your local drive. The following instructions are applicable for the Windows™ OS.

  1. Launch the Integration Tester application from your desktop.
  2. Select Create Project and click OK.
  3. Enter a name for the project in the Project Name field.
  4. Click Browse and select a location to save the project.

    If you do not browse and select a location, the project is saved in the default location, which is your home directory. For example, the default location is C:\Users\USER_ADMIN as shown in the following image.

    Image of the new project window.

  5. Click Finish.

    When you create or open a project, the Test Integrations and APIs Home page is displayed. The Home page contains several interactive guides that walk you through some of the most common tasks that you can accomplish with Test Integrations and APIs. The Home page also contains links to some useful information resources.

The new project is created.

You must import the Swagger definition from Test Virtualization Control Panel. See Importing the Swagger definition of phonebook sample API from Test Virtualization Control Panel.

Importing the Swagger definition of phonebook sample API from Test Virtualization Control Panel

You must add a Swagger file to your project that defines a REST API as an external synchronization source. Therefore, you create a project to run a test in Test Integrations and APIs by importing a Swagger definition of an API.

You must have created a project as described in Creating a project. Your project must be open in Test Integrations and APIs.

You model a system under test against which you run tests. Test Virtualization Control Panel provides some sample APIs that you can use while working with Test Integrations and APIs. You can use one of these sample APIs as the system under test.

  1. Open Test Virtualization Control Panel by double-clicking the Image of the icon icon.
    Note:
    When Test Virtualization Control Panel starts, you can see an orange icon. You must wait for it to change to green. If the icon remains red, you must troubleshoot and fix the issue. For more information, see Starting and stopping DevOps Test Virtualization Control Panel.

    The Test Virtualization Control Panel Home page is displayed.


    Image of the Test Virtualization Control Panel Home page.

  2. Click the Examples icon.

    Under the REST examples section, you can see an example of a REST Phonebook described with a Swagger definition. This Phonebook API provides a RESTful interface through which HTTP clients can retrieve information about the phone book contacts, and update or delete them.

  3. Right-click Phonebook Swagger Definition and copy the URL, which is https://localhost:5443/RTCP/examples/phonebook/api/swagger.json.
  4. Return to the Test Integrations and APIs window and navigate to Architecture School > Logical View.
    The canvas on which you model the system is displayed.
    Image of the Logical View window.

  5. Paste the URL onto the canvas either by clicking Edit > Paste or by clicking the Paste icon in the toolbar.

    The Create a new Synchronization Source window is displayed.

    Image of the Synchronization Source window.

  6. Click Next.

You have successfully created the Swagger definition in Test Integrations and APIs. The service components and operations are created in the background.

You must create a test from the Swagger definition of the API. See Creating a test from the Swagger definition of the API.

Creating a test from the Swagger definition of the API

After you import a Swagger definition of an API into Test Integrations and APIs you can create a test and configure the operation and schema for the messages for the test, from the options available in the Swagger definition.

You must have imported the Swagger definition by following the steps in Importing the Swagger definition of phonebook sample API from Test Virtualization Control Panel.

  1. In the Generate Assets for Operations page of the Create a new Synchronization Source window, select the queryPhonebookTest check box under the Create Tests column as shown in the following image.
    This action creates a test for the GET examples/phonebook/api/ request based on the Swagger definition.

    Image of the Create a new Synchronization Source window.

  2. Click Next.
    The Create Test for Operation: queryPhonebook window displays the schema fields for the test to be created, including those that are optional as shown in the following image. The optional fields are displayed in grey, which means that the values can be supplied to the service operation but are not mandatory.

    Image of the Create Test for Operation: queryPhonebook window.

  3. Clear the Include optional schema fields check box.

    The test to be created will then request for all of the entries of the Phonebook.

  4. Click Next.

    The Summary page shows the number of items created. There are 13 items which include service components, operations, and the JSON Swagger schema that represents the service described in the Swagger file. You can view the logical structure of the Phonebook sample API and the schema of the Swagger definition in the Test Factory perspective and the Schema Library, respectively.

  5. Click Finish.

    The test opens in the Test Factory perspective, which is used to create and edit tests and stubs. In this perspective, you can view the logical structure of the Phonebook sample API in the left pane.

    To view the schema of the Swagger definition, open the Schema Library in the Architecture School perspective, and click JSON Schema in the left pane.

    To view the message to be sent and the reply expected, double-click the Send Request and Receive Reply actions in the test. These actions only contain the message structure defined in the Swagger file, but do not have any data yet.

You have configured a test based on the Swagger definition.

You must run the test. See Running the test.

Running the test

You can run the test that you created based on the imported Swagger definition and verify the test result.

You must have created the test following the steps in Creating a test from the Swagger definition of the API.

If any action editor (of the Send Request or Receive Reply action) is open, you must close it.

  1. Open the test in the test editor in the Test Factory perspective.
  2. In the toolbar, click the Run icon or press F5.

    This action runs the test in the Test Lab perspective.

When your run the test, the test attempts to verify the response it receives from the API against the structure and data values that are contained in the test. Because you created the test by importing a Swagger definition, and Swagger definitions only contain message structure and not the actual data, the test has nothing to verify the response. Hence, the test fails.

You can modify the test based on the response received. See Modifying the test by basing it on the response data.

Modifying the test by basing it on the response data

You must take data values from the response that the test received when you ran the test. You must modify the test to use those values and verify the response received.

You must have run the test by following the steps in Running the test.

  1. Click any line in the test console that includes the phrase: Assertion Failed.

    Image of the console log window.

    This action opens a window in which you can compare the expected message (on the left) with the actual message that was received (on the right).

    image of the Window to compare messages.

    The test contains the structure of the message which was loaded from the Swagger definition, but does not contain any data against which the HTTP response can be verified. The panel at the bottom shows a list of the assertion failures.

  2. Click Overwrite expected message.

    This action replaces the expected message with the actual message received. Overwriting the expected message is just one of the several options to modify tests from an actual received message.

    More options, including those to make the verification more flexible and tolerant of variation, are described in Viewing message differences to repair validation errors.

  3. To save the changes and run the test again, click Close and Re-run.

The test finishes successfully.

You can view messages and actions. Viewing messages and actions.

Viewing messages and actions

After running tests successfully, you can view requests and responses messages and their associated actions of send and receive, respectively. You can use the action editor to view the messages at a later time without running the tests again.

You must have run the tests successfully by following the steps in Modifying the test by basing it on the response data.

You can view the messages received by the test and also view the messages that the test sends to the API being tested.

  1. To view the message that was received by the test when it ran, click the line that contains the Receive Reply: phrase.
  2. To view the message that the test sent to the API being tested, click the Send Request: phrase.

    Image of the Console log.

  3. Right-click the line that contains the Receive Reply: phrase and click Open Action.

    This action opens the Test Factory perspective, and the test and action editors. You can then view the data that was saved in the Receive Reply: action. This data was used to validate the response received from the API when the test was run.

    You can similarly view the data for the Send Request: action. You can see the data that was used in the request sent by the test to the API.

  4. Close the test and action editors.

You have viewed the data that was exchanged in the test with the API under test. You can return to this action editor through the test editor in the Test Factory perspective at a later time without having run the test first.

You can create additional tests for the queryPhonebook operation, run the tests, and then view the messages by completing the following steps:
  • Open the Test Factory perspective.
  • In the tree on the left, right-click the queryPhonebook operation, and click New > Tests > Test using MEP.

    This action creates a new test for the operation and automatically creates request and response actions by using the information of the Message Exchange Pattern of the operation which was imported from the Swagger definition.

You must create stubs (virtual services) that can substitute the dependencies of your system under test. See Creating and running a stub.

To run tests as part of continuous integration or continuous delivery pipeline, see Running tests by using an Ant task.

To make the test more flexible in the number of entries it can receive and what data those entries can contain, you can use repeating elements and data sources. For details, see Repeating elements in messages.