40 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 Administration Console. (The Test Console is also available in Eclipse.) 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.

You can access the Test Console from:

• The Project Explorer

• The Resource Browser

• The XQuery Editor

• Eclipse, using the Run As and Debug As options

For detailed procedural information, see Chapter 33, "Test Console" and "Using the Oracle Service Bus Debugger" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

This chapter contains the following topics:

• Section 40.1, "Prerequisites"

• Section 40.2, "Testing Proxy Services"

• Section 40.3, "Testing Business Services"

• Section 40.4, "Recommended Approaches to Testing Proxy and Business Services"

• Section 40.5, "Tracing Proxy Services Using the Test Console"

• Section 40.6, "Testing Resources"

• Section 40.7, "Performing XQuery Testing"

• Section 40.8, "Testing Services With Web Service Security"

• Section 40.9, "Test Console Transport Settings"

• Section 40.10, "About Security and Transports"

40.1 Prerequisites

To use the Test Console:

• 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 receive an error saying the Test Console service is not running, try setting the Admin server listen address to a specific valid address, such as localhost. In the Oracle WebLogic Server Console, go to Environment > Servers > admin_server_name > Configuration > General to set the Listen Address.

• 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 1.1 Relying Party" in the Oracle Fusion Middleware Oracle 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 Administration Console Project Explorer module. The URI displays in the Endpoint URI row of the Transport Configuration table.

40.2 Testing Proxy Services

You can test the following types of proxy services:

• WSDL Web service

• Messaging Service

• Any Soap Service

• Any XML Service

40.2.1 Direct Calls

Caution:

Testing proxy services with the direct call option enabled bypasses some important security steps, including access control. Oracle recommends that you not use the test service in production systems.

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 40-1 illustrates a direct call. Note that the message bypasses the transport layer; it is delivered directly to the proxy service (P1).

Figure 40-1 Direct Call to Test a Proxy Service

Description of "Figure 40-1 Direct Call to Test a Proxy Service"

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.

40.2.2 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 40-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).

Figure 40-2 Indirect Call to Test a Proxy Service

Description of "Figure 40-2 Indirect Call to Test a Proxy Service"

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 Section 40.9, "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.

Note:

Using an indirect call to a request/response MQ proxy service will not work.

In addition, the Test Console does not display the response from an indirect call to an MQ or JMS request/response proxy service using a correlation based on a messageID. When you test an MQ or JMS request/response proxy service with an indirect call, the response is retained in the response queue, and not displayed in the Test Console.

For more information, see "MQ Transport" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

40.2.3 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 Administration 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 the Oracle Fusion Middleware Concepts and Architecture for Oracle Service Bus.

For information about transport settings, see Section 33.4, "Understanding How the Run Time Uses the Transport Settings in the Test Console.".

40.3 Testing Business Services

You can test the following types of business services:

• WSDL Web service

• Transport Typed Service

• Messaging Service

• Any Soap Service

• Any XML Service

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.

Tip:

Ensure that the user name and password that you specify in the Test Console exists in the local Oracle Service Bus domain even if the business service being tested is in a remote domain. The test service performs a local authentication before invoking any proxy or business service.

40.4 Recommended Approaches to Testing Proxy and Business Services

In the scenario depicted in Figure 40-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.

Figure 40-3 Test Scenario Example

Description of "Figure 40-3 Test Scenario Example"

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 40-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 40-3, interface 1 refers to XQuery expression tests.

• Test proxy service to business service (interface 2 in Figure 40-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 40-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 40-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.

40.5 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:

• The trace for service invocations on the request path

• The trace for the routed service

• The trace for the service invocations on the response path

• Changes made to the message context between the entry point of the route node (on the request path) and the exit point (on the response path)

40.5.1 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.

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

1. Start the Oracle Service Bus Examples domain and load the samples data.

2. Log in to the Oracle Service Bus Administration Console, then select Resource Browser and locate the LoanGateway3 proxy service.

3. 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.

4. Edit the test XML provided to send the following test message, illustrated in Example 40-1.

   Example 40-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>
   

5. Click Execute.

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

Figure 40-4 Invocation Trace for LoanGateway3 Proxy Service

Description of "Figure 40-4 Invocation Trace for LoanGateway3 Proxy Service"

The trace indicates the following:

• 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 Example 40-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 Administration Console. Then run the test again and view the results.

40.6 Testing Resources

You can test the following resources:

• Section 40.6.1, "MFL"

• Section 40.6.2, "XSLT"

• Section 40.6.3, "XQuery"

40.6.1 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:

• XML to binary—There is one required input (XML) and one output (binary).

• binary to XML—There is one required input (binary) and one output (XML).

Each transformation accepts only one input and provides a single output.

40.6.1.1 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.

Example 40-2 shows an example MFL file.

Example 40-2 Contents of an MFL File

<?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 Example 40-2 is shown in Example 40-3.

Example 40-3 Test Console XML Input

<StockPrices>
    <PriceQuote>
        <StockSymbol>StockSymbol_31</StockSymbol>
        <StockPrice>StockPrice_17</StockPrice>
    </PriceQuote>
</StockPrices>

In the Test Console, click Execute to run the test. Example 40-4 shows the resulting test data, the stock symbol and stock price in binary format.

Example 40-4 MFL Test Console Results

00000000:53 74 6F 63 6B 53 79 6D 62 6F 6C 5F 33 31 3A 53 StockSymbol_31:S
00000010:74 6F 63 6B 50 72 69 63 65 5F 31 37 7C .. .. .. StockPrice_17|...

40.6.2 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.

For more information, see Section 33.2.2, "Testing XSLT Transformations."

40.6.3 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:

• Simple/primitive type—String, int, float, and so on.

• XML nodes

• Untyped

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.

Figure 40-5 shows an XQuery with three variables: int, XML, and undefined type.

Figure 40-5 Input to the XQuery Test

Description of "Figure 40-5 Input to the XQuery Test"

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 Section 33.2.3, "Testing XQuery Transformations."

You can also test an XQuery expression from the XQuery Editor.

40.7 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 Section 33.2.3, "Testing XQuery Transformations."

40.8 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 the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus. 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 Section 33.1.2, "Configuring Proxy Services Test Data" and Section 33.1.6, "Configuring Business Services Test Data."

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.

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 40-1 and Table 40-2 describe security scenarios.

Table 40-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 Certificate Lookup and Validation Framework" in Oracle Fusion Middleware Securing Oracle WebLogic Server.

Table 40-2 Identity Policy Scenarios (Assuming that the Policy has an Identity Assertion)

Supported Token TypesFoot 1	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

^Footnote 1  From the Identity Assertion inside the request policy.

40.8.1 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.

  Note:

  After executing a test in the Test Console, the envelope generated with WSS is not always a valid envelope—the results page in the Test Console includes white spaces for improved readability. That is, the secured SOAP message is displayed with extra white spaces. Because white spaces can affect the semantics of the document, this SOAP message cannot always be used as the literal data. For example, digital signatures are white-space sensitive and can become invalid.

40.9 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.

Figure 40-6 shows the Transport panel for a WSDL-based proxy service.

Figure 40-6 Transport Panel in the Test Console

Description of "Figure 40-6 Transport Panel in the Test Console"

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 40-6, 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 Chapter 37, "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.

For information about specific headers and metadata and how they are handled by the test framework, see Section 33.4, "Understanding How the Run Time Uses the Transport Settings in the Test Console.".

40.10 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.