This chapter provides guidelines and information on testing services using the Oracle Service Bus Test Console, including a section that describes how to undeploy the Test Console in production environments.
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 use the Test Console in clustered environments. However, Oracle does not recommend deploying the Test Console in production environments.
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
This chapter contains the following topics:
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. 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. Also, in a cluster, make sure all managed nodes are running.
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.
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.
You can test the following types of proxy services:
WSDL Web service
Any Soap Service
Any XML Service
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 framework in production systems. For information on untargeting the Test Console, see Section 40.11, "Undeploying the Test Console."
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. 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.
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 runtime path.
Figure 40-2 illustrates an indirect call. 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 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.
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.
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 Runtime Uses the Transport Settings in the Test Console.".
You can test the following types of business services:
WSDL Web service
Transport Typed 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.
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.
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.
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 (through 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.
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. To view values, click the + sign.
(Deleted variables)—The names of all deleted variables.
(Changed variables)—The names of all variables for which the value changed. To view the new value, click 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
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
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)
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:
Start the Oracle Service Bus Examples domain and load the samples data.
Log in to the Oracle Service Bus Administration Console, then select Resource Browser and locate the
LoanGateway3 proxy service.
Click the Launch Test Console icon for the
LoanGateway3 proxy service. The
LoanGateway3 page appears. The Direct Call and the Include Tracing options are selected.
Edit the test XML provided to send the following test message, illustrated in Example 40-1.
Scroll to the bottom of the results page to view the tracing results in the Invocation Trace panel, shown in Figure 40-4.
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 the + sign associated with the variable name.
$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.
You can test the following resources:
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.
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.
<?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>
<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.
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."
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.
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.
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.
You must disable the pop-up blockers in your browser for the XQuery testing to work. 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."
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. An operation might 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.
|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.
|Supported Token TypesFoot 1||Description||Comments|
The service only accepts WSS user name tokens
You must specify a user name and password in the Security panel.
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.
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.
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.
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.
The service accepts X.509 or SAML tokens
You must specify one of the following:
UNT, X.509, SAML
The service accepts UNT, X.509 or SAML tokens
You must specify one of the following:
Footnote 1 From the Identity Assertion inside the request policy.
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.
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.
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.
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.
When testing services that use the MQ transport, message text might appear garbled depending on the character set being used. The test console writes messages in the UTF-8 character format. If the MQ connection's coded character set identifier (CCSID) is configured to a value other than 1208 (UTF-8), the text appears garbled in the console. To avoid this, override the CCSID by defining a User Header named characterSet on the Transport panel of the Test Console. Set the value of the header to 1208.
For information about specific headers and metadata and how they are handled by the test framework, see Section 33.4, "Understanding How the Runtime Uses the Transport Settings in the Test Console.".
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, email, 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.
Oracle recommends that you not use the test framework in production systems. For example, testing proxy services with the direct call option bypasses some important security steps, including access control.
When you create an Oracle Service Bus domain, the Configuration Wizard, by default, includes the "ALSB Test Framework" (Test Console) as a target on the Admin Server and any Managed Servers. The following section describe different options for undeploying the Test Console:
To untarget the Test Console in the Oracle Fusion Middleware Configuration Wizard before a domain is created:
When creating an Oracle Service Bus domain with the Configuration Wizard, select optional configuration for Deployments and Services.
In the related wizard pages that follow, for each server, deselect the ALSB Test Framework application.
When the wizard creates the domain, the Test Console (OSB_ORACLE_HOME\lib\sbTestFwk.ear) is not deployed.
To undeploy the Test Console when an Oracle Service Bus domain is running, do the following:
Start the Oracle WebLogic Server Administration Console and log in.
In the left navigation area, under Domain Structure, click Deployments. The Summary of Deployments page is displayed.
In the Deployments table, click the "ALSB Test Framework." The Settings page for the ALSB Test Framework is displayed.
Click the Targets tab.
Select the Component check box to select all the test framework resources, and click Change Targets.
On the Target Deployments page, deselect the AdminServer and all Managed Servers.
Click Yes. A message is displayed indicating that the settings have been successfully updated.
If an Oracle Service Bus domain is not running, you can use the WebLogic Scripting Tool (WLST) to untarget the Test Console from the Oracle Service Bus domain. For more information about WLST, see Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
To untarget the Test Console ("ALSB Test Framework"), complete the following steps:
If you have not already set up your environment to use WLST, see "Main Steps for Using WLST" in "Using the WebLogic Scripting Tool" in Oracle Fusion Middleware Oracle WebLogic Scripting Tool.
Invoke WLST Offline.
To read the domain that was created using the Configuration Wizard execute:
To untarget the ALSB Test Framework application, execute:
wls:/offline/base_domain>unassign("AppDeployment", "ALSB Test Framework", "Target", "AdminServer", "ManagedServer_1", "ManagedServer_2")
Include the names of all managed servers in the command.
To update the domain execute:
To close the domain execute:
Exit from the WLST command prompt execute: