Using the Test Console

The Oracle Service Bus Test Console is a browser-based test environment you use validate and test the design of your system. It is an extension of the Oracle Service Bus Console. (The Test Console is also available in Workshop for WebLogic.) You configure the object of your test (proxy service, business service, XQuery, XSLT, or MFL resource), execute the test, and view the results in the test console. In some cases, you can trace through the code and examine the state of the message at specific trace points. Design time testing helps isolate design problems before you deploy a configuration to a production environment.

The test console can test specific parts of your system in isolation and it can test your system as a unit. You can do testing in clustered environments. However, in a clustered domain, you cannot use the test console to test any configured business service or proxy service which routes to a business service.

For detailed procedural information, see Test Console in Using the Oracle Service Bus Console and Using the Oracle Service Bus Debugger in the Using the Oracle Service Bus Plug-ins for Workshop for WebLogic.

Features

Prerequisites

You must have Oracle Service Bus running and you must have activated the session that contains the resource you want to test.
You must disable the pop-up blockers in your browser for the XQuery testing to work. Note that if you have toolbars in the Internet Explorer browser, this may mean disabling pop-up blockers from under the Options menu as well as for all toolbars that are configured to block them. XQuery testing is done only in the design time environment (in an active session).
If you want the test console to generate and send SAML tokens to a proxy service, you must configure the proxy service to require SAML tokens and to be a relying party. For more information on creating a SAML relying party, see Create a SAML Relying Party in WebLogic Server Administration Console Online Help.

Note:

When creating a SAML relying party:

Only WSS/Sender-Vouches and WSS/Holder-of-Key SAML profiles are applicable to a proxy service.
When you are configuring the relying party, for the target URL value provide the URI of the proxy service. You can view the URI of the proxy service by clicking on the proxy service name in the Oracle Service Bus Console Project Explorer module. The URI displays in the Endpoint URI row of the Transport Configuration table.

Testing Proxy Services

Direct Calls

A direct call is used to test a proxy service that is collocated in the Oracle Service Bus domain. Using the direct call option, messages are sent directly to the proxy service, bypassing the transport layer. When you employ the direct call option, tracing is turned on by default, allowing you to diagnose and troubleshoot a message flow in the test console. By default, testing of proxy services is done using the direct call option.

When you use the direct call option to test a proxy service, the configuration data you input to the test console must be that which is expected by the proxy service from the client that invokes it. In other words, the test console plays the role of the client invoking the proxy service. Also, when you do direct call testing, you bypass the monitoring framework for the message.

Figure 6-1 illustrates a direct call. Note that the message bypasses the transport layer; it is delivered directly to the proxy service (P1).

A direct call strategy is best suited for testing the internal message flow logic of proxy services. Your test data should simulate the expected message state at the time it is dispatched. Use this test approach in conjunction with setting custom (inbound) transport headers in the test console Transport panel to accurately simulate the service call.

Indirect Calls

When you test a proxy service with an indirect call (that is, when the direct call option is not selected), the message is sent to the proxy service through the transport layer. The transport layer performs manipulation of message headers or metadata as part of the test. The effect is to invoke a proxy service to proxy service run-time path.

Figure 6-2 illustrates an indirect call. Note that the message is first processed through the transport layer and is subsequently delivered to the proxy service (P1).

Oracle recommends this testing strategy when testing a proxy service to proxy service interface when both services run in the same JVM. Use this test approach in conjunction with setting custom (outbound) transport headers in the test console Transport panel to accurately simulate the service call. For more information on transport settings, see Test Console Transport Settings.

Using an indirect call, the configuration data you input to the test is the data being sent from a proxy service, for example, from a route node or a service callout action of another proxy service. In the indirect call scenario, the test console plays the role of the proxy service that routes to, or makes a callout to, another service.

HTTP Requests

When you test proxy services, the test console never sends a HTTP request over the network, therefore, transport-level access control is not applied. Transport-level access control is achieved through the Web application layer—therefore, even in the case that an indirect call is made through the Oracle Service Bus Console transport layer, an HTTP request is not sent over the network and transport-level access control is not applied. For information about message processing in the transport layer, see Architecture Overview in Oracle Service Bus Concepts and Architecture.

Testing Business Services

When testing business services, the messages are always routed through the transport layer. The direct call option is not available. The configuration data that you provide to the test console to test the service is that which represents the state of the message that is expected to be sent to that business service—for example, from a route node or a service callout action of a proxy service. The test console functions in the role of the caller proxy service when you use it to test a business service.

Recommended Approaches to Testing Proxy and Business Services

In the scenario depicted in Figure 6-3, a client invokes the proxy service (P1). The message flow invokes business service B1, then proxy service P2, then proxy service P3 before returning a message to the client. Interfaces are identified by number.

There are many valid test strategies for this scenario. Oracle recommends the following:

Complete the testing of interfaces other than the client interface to a given proxy service before you test the client call. In the sample scenario illustrated in Figure 6-3, this means that you complete the testing of interfaces 1 through 4 first, then test interface 5. In this way, the message flow logic for the proxy service (P1) can be iteratively changed and tested (via interface 5) knowing that the other interfaces to the proxy service function correctly.
Validate and test all the XQuery expressions in a message flow prior to a system test. In Figure 6-3, interface 1 refers to XQuery expression tests.
Test proxy service to business service (interface 2 in Figure 6-3) using a indirect call. In other words, route the messages through the transport layer.
Test proxy service to proxy service (interfaces 3 and 4 in Figure 6-3) using an indirect call. In other words, disable the direct call option, which means that during testing, the messages are routed through the transport layer.
Make your final system test simulate the client invoking the proxy service P1. This test is represented by interface 5 in Figure 6-3. Test interface 5 with a direct call. In this way, during the testing, the messages bypass the transport layer. By default, tracing is enabled with a direct call.
Save the message state after executing successful interface tests to facilitate future troubleshooting efforts on the system. Testing interface 5 is in fact a test of the complete system. Knowing that all other interfaces in the system work correctly helps narrow the troubleshooting effort when system errors arise.

Tracing Proxy Services Using the Test Console

Tracing the message through a proxy service involves examining the message context and outbound communications at various points in the message flow. The points at which the messages are examined are predefined by Oracle Service Bus. Oracle Service Bus defines tracing for stages, error handlers, and route nodes.

For each stage, the trace includes the changes that occur to the message context and all the services invoked during the stage execution. The following information is provided by the trace:

(New variables)—The names of all new variables and their values. View values by clicking on the + sign.
(Deleted variables)—The names of all deleted variables.
(Changed variables)—The names of all variables for which the value changed. View the new value by clicking on the + sign.
Publish—Every publish call is listed. For each publish call, the trace includes the name of the service invoked, and the value of the outbound, header, body, and attachment variables.
Service callout—Every service callout is listed. For each service callout, the trace includes the name of the service that is invoked, the value of the outbound variable, the value of the header, body, and attachment variables for both the request and response messages.

The trace contains similar information for route nodes as for stages. In the case of route nodes, the trace contains the following categories of information:

Example: Testing and Tracing a Proxy Service

The following example scenario uses one of the proxy services in the Oracle Service Bus Examples domain as a basis of instruction, the loanGateway3 proxy service associated with the Validating a Loan Application example. For more information on how to start the Examples domain and run the examples, see Oracle Service Bus Samples.

The message flow for loanGateway3 is represented in Figure 6-4. The figure is annotated with the configuration for the validate loan application stage and route node.

To test this proxy service in the Oracle Service Bus Examples domain using the test console, complete the following procedure:

Start the Oracle Service Bus Examples domain and load the samples data, as described in Oracle Service Bus Samples.
Log in to the Oracle Service Bus Console, then select Resource Browser and locate the LoanGateway3 proxy service.
Click the Launch Test Console icon for the LoanGateway3 proxy service. The Proxy Service Testing - LoanGateway3 page is displayed. Note that the Direct Call and the Include Tracing options are selected.
Edit the test XML provided to send the following test message, illustrated in Listing 6-1.

Listing 6-1 Test Message for LoanGateway3

<loanRequest xmlns:java=”java:normal.client”>
    <java:Name>Name_4</java:Name>
    <java:SSN>SSN_11</java:SSN>
    <java:Rate>4.9</java:Rate>
    <java:Amount>2500</java:Amount>
    <java:NumOfYear>20.5</java:NumOfYear>
    <java:Notes>Name_4</java:Notes>

</loanRequest>

Click Execute.

Scroll to the bottom of the results page to view the tracing results in the Invocation Trace panel, shown in Figure 6-5.

Figure 6-5 Invocation Trace for LoanGateway3 Proxy Service

Invocation Trace for LoanGateway3 Proxy Service

Compare the output in the trace with the nodes in the message flow shown in Figure 6-4.

Initial Message Context—Shows the variables initialized by the proxy service when it is invoked. To see the value of any variable, click on the + sign associated with the variable name.
Changed Variables—$header $body and $inbound changed as a result of the processing of the message through the validate loan application stage. These changes are seen at the end of the message flow.
The contents of the fault context variable ($fault) is shown as a result of the stage error handler handling the validation error. The non-integer value (20.5) you entered for the <java:NumOfYear> element in Listing 6-1 caused the validation error in this case.

You can test the proxy service using different input parameters or by changing the message flow in the Oracle Service Bus Console. Then run the test again and view the results.

Testing Resources

MFL

A Message Format Language (MFL) document is a specialized XML document used to describe the layout of binary data. MFL resources support the following transformations:

Example

The following example illustrates testing an MFL transformation. The test console generates a sample XML document from the MFL file. Execute the test using the XML input. A successful test results in the transformation of the message content of the input XML document to binary format.

<?xml version='1.0' encoding='windows-1252'?>
<!DOCTYPE MessageFormat SYSTEM 'mfl.dtd'>
  <MessageFormat name='StockPrices' version='2.01'>
   <StructFormat name='PriceQuote' repeat='*'>
    <FieldFormat name='StockSymbol' type='String' delim=':' codepage='windows-1252'/>
    <FieldFormat name='StockPrice' type='String' delim='|'codepage='windows-1252'/>
   </StructFormat>
  </MessageFormat>

The XML document generated by the test console to test the MFL file in the Listing 6-2 is shown in Listing 6-3.

In the test console, click Execute to run the test. Listing 6-4 shows the resulting test data, the stock symbol and stock price in binary format.

XSLT

Extensible Stylesheet Language Transformation (XSLT) describes XML-to-XML mappings in Oracle Service Bus. You can use XSL transformations when you edit XQuery expressions in the message flow of proxy services.

To test an XSLT resource, you must supply an input XML document. The test console returns the output XML document. You can create parameters in your document to assist with a transformation. XSLT parameters accept either primitive values or XML document values. You cannot identify the types of parameters from the XSL transformation. In the Input and Parameters panel of the XSLT Resource Testing page in the test console, you must provide the values to bind to the XSLT parameters defined in your document.

XQuery

XQuery uses the structure of XML to express queries across different kinds of data, whether physically stored in XML or viewed as XML.

An XQuery transformation can take multiple inputs and returns one output. The inputs expected by an XQuery transformation are variable values to bind to each of the XQuery external variables defined. The value of an XQuery input variable can be a primitive value (String, integer, date), an XML document, or a sequence of the previous types. The output value can be a primitive value (String, integer, date), an XML document, or a sequence of the previous types.

XQuery is a typed language—every external variable is given a type. The types can be categorized into the following groups:

In the test console, a single-line edit box is displayed if the expected type is a simple type. A multiple-line edit box is displayed if the expected data is XML. A combination input is used when the variable is not typed. The test console provides the following field in which you can declare the variable type: [] as XML. Input in the test console is rendered based on the type to make it easier to understand the type of data you must enter.

In the test console, all three variables are listed in the Variables panel. By default, XML is selected for the untyped variable as it is the most typical case. You must configure these variables in the Variables panel. See Testing XQuery Transformations in Using the Oracle Service Bus Console.

Performing XQuery Testing

You must disable the pop-up blockers in your browser for the XQuery testing to work. Note that if you have toolbars in the Internet Explorer browser, you may need to disable pop-up blockers from under the browser Options menu as well as for all toolbars that are configured to block them.

When performing XQuery testing in the test console, use the Back button to execute a new test. However, if you want to execute a new test after making changes to the XQuery, you must close and re-open the test console for the changes to take effect. For detailed information, see Performing XQuery Testing in Using the Oracle Service Bus Console.

Testing Services With Web Service Security

The test console supports testing proxy services and business services protected with Web Service Security (WSS). A SOAP service is protected with WSS if it has WS-Policies with WS-Security assertions assigned to it. Specifically, a service operation is protected with WS-Security if its effective request or response WS-Policy includes WS-Security assertions. WS-Policies are assigned to a service by WS-PolicyAttachment. See “Attaching WS-Policy Statements to WSDL Documents” in Using Web Services Policy to Specify Inbound Message-Level Security in the Oracle Service Bus Security Guide. Note that an operation may have both a request policy and a response policy.

When an operation has a request or response WS-Policy, the message exchange between the test console and the service is protected by the mechanisms of WS-Security. According to the operation’s policy, the test service digitally signs or encrypts the message (more precisely, parts of the message) and includes any applicable security tokens. You specify the input to the digital signature and encryption operations is the clear-text SOAP envelope specified as described in “Configuring Proxy Service Test Data” and “Configuring Business Service Test Data” in Test Console in the Using the Oracle Service Bus Console.

Similarly, the service processes the response according to the operation’s response policy. The response may be encrypted or digitally signed. The test service then processes this response and decrypts the message or verifies the digital signature.

The test console (Security panel) displays fields used for testing services with WS-Security: Service Provider, Username, and Password.

If you specify a service key provider in the test console, all client-side PKI key-pair credentials required by WS-Security are retrieved from the service key provider. You use the user name and password fields when an operation’s request policy specifies an Identity assertion and user name Token is one of the supported token types. For more information, see Web Service Policy.

The Service Provider, Username, and Password fields are displayed whenever the operation has a request or response policy. Whether the values are required depends on the actual request and response policies.

Table 6-1 Digital Signature and Encryption Scenarios
Scenario	Is Service Key Provider Required?
The request policy has a Confidentiality assertion.	No. The test service encrypts the request with the service’s public key. When testing a proxy service, the test service automatically retrieves the public key from the encryption certificate assigned to the service key provider of the proxy service. When testing a business service, the encryption certificate is embedded in the WSDL of the business service. The test service automatically retrieves this WSDL from the WSDL repository and extracts the encryption certificate from the WSDL.
The response policy has a Confidentiality assertion.	Yes. In this scenario, the operation policy requires the client to send its certificate to the service. The service will use the public key from this certificate to encrypt the response to the client. A service key provider must be specified and must have an associated encryption credential. If both request and response encryption are supported, different credentials must be used.
The request policy has an Integrity assertion.	Yes. The client must sign the request. A service key provider must be specified and must have an associated digital signature credential. Furthermore, if this is a SAML holder-of-key integrity assertion, a user name and password is needed in addition to the service key provider.
The response policy has an Integrity assertion.	No. In this case, the policy specifies that the service must sign the response. The service signs the response with its private key. The test console simply verifies this signature. When testing a proxy service, this is the private key associated to the service key provider’s digital signature credential for the proxy service. When testing a business service, the service signing key-pair is configured in a product-specific way on the system hosting the service. In the case that the current security realm is configured to do a Certificate Lookup and Validation, then the certificate that maps to the service key provider must be registered and valid in the certificate lookup and validation framework. For more information on Certificate Lookup and Validation, see ''Configuring the Credential Lookup and Validation Framework” in Configuring WebLogic Security Providers in Securing WebLogic Server.

Table 6-2 Identity Policy Scenarios (Assuming that the Policy has an Identity Assertion)
Supported Token Types¹	Description	Comments
UNT	The service only accepts WSS user name tokens	You must specify a user name and password in the Security panel.
X.509	The service only accepts WSS X.509 tokens	You must specify a service key provider in the Security panel and the service key provider must have an associated WSS X.509 credential.
SAML	The service only accepts WSS SAML tokens	You must specify a user name and password in the Security panel or a user name and password in the Transport panel. If both are specified, the one from the Security panel is used as the identity in the SAML token.
UNT, X.509	The service accepts UNT or X.509 tokens	You must specify a user name and password in the Security panel or a service key provider in the Security panel with an associated WSS X.509 credential. If both are specified, only a UNT token is generated.
UNT, SAML	The service accepts UNT or SAML tokens	You must specify a user name and password in the Security panel or a user name and password in the Transport panel. If both are specified, only a UNT token is sent.
X.509, SAML	The service accepts X.509 or SAML tokens	You must specify one of the following: user name and password in the Security panel user name and password in the Transport panel service key provider with an associated WSS X.509 credential
UNT, X.509, SAML	The service accepts UNT, X.509 or SAML tokens	You must specify one of the following: user name and password in the Security panel user name and password in the Transport panel service key provider with an associated WSS X.509 credential

¹ From the Identity Assertion inside the request policy.

Limitations for Services and Policies

The following limitations exist for testing proxy services with SAML policies and business services with SAML holder-of-key policies:

Testing proxy services with inbound SAML policies is not supported.
Testing business services with a SAML holder-of-key policy is a special case. The SAML holder-of-key scenario can be configured in two ways:

as an integrity policy (this is the recommended approach)
as an identity policy

In both cases, you must specify a user name and password—the SAML assertion will be on behalf of this user. If SAML holder-of-key is configured as an integrity policy, you must also specify a service key provider. The service key provider must have a digital signature credential assigned to it. This case is special because this is the only case where a user name and password must be specified even if there is not an identity policy.

Test Console Transport Settings

You use the Transport panel in the test console to specify the metadata and transport headers for messages in your test system.

By setting the metadata and the transport headers in the message flow of a proxy service, you influence the actions of the outbound transport. You can test the metadata, the message, and the headers so that you can view the pipeline output. The fields that are displayed in the Transport panel when testing a proxy service represent those headers and metadata that are available in the pipeline. The test console cannot filter the fields it displays depending on the proxy service. The same set of transport parameters are displayed for every HTTP-based request.

The Username and Password fields are used to implement basic authentication for the user that is running the proxy service. The Username and Password fields are not specifically transport related.

Metadata fields are located below the Username and Password fields and above the transport header fields. The fields displayed are based on the transport type of the service. Certain fields are pre-populated depending on the operation selection algorithm you selected for the service when you defined it.

For example, in the Transport panel displayed in Figure 6-8, the SOAPAction header field is populated with “http://example.orgprocessLoanApp”. This value comes from the service definition (the selection algorithm selected for this proxy service was SOAPAction Header). For more information about the selection algorithms, see Modeling Message Flow in Oracle Service Bus.

Specify the values in the Transport panel fields according to whether the message will be processed through the transport layer (for example, if you are testing the service using a direct call), or not (an indirect call).

When testing a proxy service with a direct call, the test data must represent the message as if it had been processed through the transport layer. That is, the test data should represent the message in the state expected at the point it leaves the transport layer and enters the service. When testing a proxy or business service using an indirect call, the test data represents the data that is sent from a route node or a service callout. The test message is processed through the transport layer.

About Security and Transports

When using the test console to test HTTP business services with BASIC authentication, the test console authenticates the user name and password from the service account of the business service. Similarly, when testing JMS, e-mail, or FTP business services that require authentication, the test console authenticates the service account associated with the business service.
When you test proxy services, the test console never sends a HTTP request over the network. Therefore, transport-level access control is not applied.

User Guide