User Guide
|
 |
 |
|
 |
 |
Using the Test Console
The BEA AquaLogic Service Bus Test Console is a browser-based test environment used to validate and test the design of your system. It is an extension of the AquaLogic Service Bus Console. You can configure the object of your test (proxy service, business service, XQuery, XSLT, MFL resource), execute the test, and view the results in the console. In some instances 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.
The Test Console can be invoked to test any proxy service or business service and certain resources used by these services. You can also do in-line XQuery testing.
You can invoke the test console in a number of ways in the AquaLogic Service Bus Console, depending on what part of your process you want to test. You can invoke the test console from:
You can run and test a proxy service that makes a call to another proxy service or business service and vice versa. You can test the resources used by your services. When testing services you must be aware of the information that is passing from the test console to the service and vice versa.
Features
The test console supports the following features:
- Testing proxy services
- Testing business services
- Testing resources
- Testing in-line XQueries
- Tracing the message through the message flow (for proxy services only)
Prerequisites
- You must have AquaLogic 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 inline 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. Inline XQuery testing is done only in the design time environment (in an active session).
Testing Proxy Services
You must have activated a session to test a proxy service. You can test a proxy service from the Resource Browser or Project Explorer. You can test the following types of proxy services:
Direct Calls
A Direct Call is used to test a proxy service that is collocated in the AquaLogic 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.
The following figure illustrates a direct call. Note that the message bypasses the transport layer; it is delivered directly to the proxy service (P1).
Figure 4-1 Direct Call to Test a Proxy Service
A Direct Call strategy is best suited for testing proxy services' internal message flow logic. 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's Transport section 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 checked), 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 invocation run-time path.
The following figure 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 4-2 Indirect Call to Test a Proxy Service
This testing strategy is recommended 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's Transport panel to accurately simulate the service call. To learn more about the Transport settings in the test console, see Test Console Transport Settings.
Using the 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.
(This transport-level access control is achieved through the Web Application layer—in other words, even in the case that an indirect call is made through the AquaLogic Service Bus Console transport layer, an HTTP request is not sent over the network and this transport-level access control is not applied.) For information about the AquaLogic Service Bus Console architecture, see Overview in BEA AquaLogic Service Bus Concepts and Architecture.
For information about transport settings, see Understanding How the Run Time Uses the Transport Settings in the Test Console.
Testing Business Services
You must have activated a session to test services. You can test the following types of business services:
When testing business services, the messages are always routed through the transport layer. The Direct Calls 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 is in the role of the caller proxy service when you use it to test a business service.
Transport Security
When using the test console to test HTTP(S) business services with BASIC authentication, the test console authenticates with the username/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 with the service account associated with the business service.
Recommended Approaches to Testing Proxy and Business Services
In the scenario depicted in the following figure, 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 4-3 Test Scenario Example
There are many valid test strategies for this scenario. The following are recommended test strategies:
- It is recommended that you 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 the preceding figure, 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.
- It is recommended that all the XQuery expressions in a message flow be validated and tested prior to a system test. In the preceding figure, interface 1 refers to XQuery expression tests.
- Proxy service to business service (interface 2 in the preceding figure) is tested using a indirect call. In other words, the messages are routed through the transport layer.
- Proxy service to proxy service tests (Interfaces 3 and 4 in the preceding figure) are tested using an indirect call. In other words, disable the Direct Call option, which means that during the testing, the messages are routed through the transport layer.
- Your final system test simulates the client invoking the proxy service P1. This test is represented by interface 5 in the preceding figure.
Test interface 5 with a Direct Call. In this way, during the testing, the messages bypass the transport layer. Tracing is automatically enabled with a Direct Call.
- It is recommended that the message state be saved 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 and 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 AquaLogic Service Bus. AquaLogic 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 value (values can be seen by clicking +) - Deleted variables—
—the names of all deleted variables - Changed variables—
—the names of all variables for which the value changed. The new value is visible 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,bodyandattachmentvariables. - 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
outboundvariable, the value of theheader,body, andattachmentvariables 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)
Example: Testing and Tracing a Proxy Service
This example uses one of the proxy services in the example AquaLogic Service Bus domain as a basis of instruction.
To learn how to start the example domain and run the examples provided there, see BEA WebLogic Service Bus Samples. This example scenario uses the proxy service named loanGateway3, associated with the Validating a Loan Application example.
The message flow for loanGateway3 is represented in the following figure. The figure is annotated with the configuration for the validate loan application stage and the configuration for the route node.
Figure 4-4 Message Flow for Proxy Service (LoanGateway3)
To test this proxy service in the AquaLogic Service Bus examples domain using the test console, complete the following procedure:
- Start the AquaLogic Service Bus examples domain and load the samples data, as described see BEA WebLogic Service Bus Samples.
- Log in to the AquaLogic Service Bus Console, then select Project Explorer and locate the
LoanGateway3proxy service.
for the Listing 4-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>
Compare the output in the trace with the nodes in the message flow shown in Figure 4-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 + associated with the variable name.
- Changed Variables—
$bodyand$inboundchanged as a result of the processing of the message through thevalidateloanapplicationstage. These changes are seen at the end of the message flow. - The contents of the
faultcontext 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 4-1 caused the validation error in this case.) For more information about this loan application scenario, see Tutorial 3: Validating a Loan Application in BEA AquaLogic Service Bus Tutorials.
It is left as an exercise to the reader to test the service using different input parameters, or to change the behavior of the message flow in the AquaLogic Service Bus Console Project Explorer, and run the test again to view the results.
Testing Resources
You can test resources inside an active session or from outside a session. You can test the following 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:
- 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 only accepts one input and provides a single output.
The following example describes an XML input file to be tested in the test console. When you invoke the test console to test the MFL file, sample XML data is generated. Execute the test using the sample XML—in this case, a successful test results in the transformation of the message content of the input XML document in to binary format. The following Example section describes the MFL, the test XML, and the data resulting from the test.
Example
The following listing is an example MFL file.
Listing 4-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 input generated by the test console to test the MFL file in the Listing 4-2 is described in the following listing.
Listing 4-3 Test Console XML Input
<StockSymbol>StockSymbol_31</StockSymbol>
<StockPrice>StockPrice_17</StockPrice>
In the test console, click Execute to run the test—the result is the Stock symbol and the stockPrice in binary format as shown in the following listing.
Listing 4-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 .. .. .. tockPrice_17|...
XSLT
eXtensible Stylesheet Language Transformation (XSLT) describes XML-to-XML mappings in AquaLogic 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 displays the output XML document as a result of the test. 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 section 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 intelligently 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 primitive value (string, integer, date), an XML document, 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. This makes it easy to understand the type of data you must enter.
For example, the following figure shows an XQuery with three variables: int, XML, and undefined type.
Figure 4-6 Input to the XQuery Test
In the Test Console, all three variables are listed in the Variables section. By default, for the untyped variable XML is checked as it is the most usual case. You must configure these variables.
Figure 4-7 Configuring the XQuery Variables in the Test Console
You can also test an XQuery expression from the XQuery Editor.
Performing In-line XQuery Testing
You must disable the pop-up blockers in your browser for the inline 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's Options menu as well as for all toolbars that are configured to block them.
When performing in-line XQuery testing with the test console, you can use the Back button to return to the page from where you can execute a new test. But if you want to execute a new test after making changes to the in-line XQuery, you must close and re-open the test console for the changes to take effect.
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 the operation's effective request and/or response WS-Policy includes WS-Security assertions. WS-Policies are assigned to a service by a mechanism called WS-PolicyAttachment. See Web Services Policy Attachment. Note that an operation may have both a request policy and a response policy.
When an operation has a request WS-Policy 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 and/or encrypts the message (more precisely, parts of the message) and includes any applicable security tokens. The input to the digital signature and encryption operations is the clear-text SOAP envelope specified by the user as described in "Configuring Proxy Service Test Data" and "Configuring Business Service Test Data" in Test Console in the BEA AquaLogic Service Bus User Guide.
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 and/or verifies the digital signature.
The test console (Security panel) displays fields used for testing services with WS-Security: Service Provider, Username and Password.
Figure 4-8 Security Panel in Test Console
If you specify a proxy service provider in the test console, all client-side PKI key-pair credentials required by WS-Security are retrieved from the proxy service provider. For more information, see Proxy Service Providers. You use the username and password fields when an operation's request policy specifies an Identity assertion and Username 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.
The following table describes the different scenarios.
Table 4-1 Digital Signature and Encryption Scenarios
|
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 proxy service 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. |
|
|
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 proxy service provider must be specified and must have an associated encryption credential. If both request and response encryption are supported, different credentials must be used. For more information, see Client Request and Proxy Service Response and About Outbound Web Services Security. |
|
|
Yes. The client must sign the request. A proxy service provider must be specified and must have an associated digital signature credential. Furthermore, if this is a SAML holder-of-key integrity assertion, a username and password is needed in addition to the proxy service provider. |
|
|
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 proxy service 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 Certificate Lookup and Validation, then the certificate that maps to the proxy service provider must be registered 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 4-2 Identity Policy Scenarios. It is Assumed the Policy has an Identity Assertion
|
Supported Token Types1 | ||
|---|---|---|
|
The user must specify a username and password in the security section. |
||
|
The user must specify a proxy service provider in the security section and the proxy service provider must have an associated WSS X.509 credential. |
||
|
The user must specify a username and password in the security section or a username and password in the transport section. If both are specified, the one from the security section is used as the identity in the SAML token. |
||
|
The user must specify a username and password in the security section or a proxy service provider in the security section with an associated WSS X.509 credential. If both are specified, only a UNT token is generated. |
||
|
The user must specify a username and password in the security section or a username and password in the transport section. If both are specified, only a UNT token is sent. |
||
1. 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 of proxy services with inbound SAML policies is not supported
- Testing business services with a SAML holder-of-key policy is a special case.
In both cases the user must specify a username and password—the SAML assertion will be on behalf of this user. If SAML holder-of-key is configured as an integrity policy, the user must also specify a proxy service provider. The proxy service provider must have a digital signature credential assigned to it. This case is special because this is the only case where a username 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 printed with extra white spaces. Because white spaces can affect the semantic 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.
Test Console Transport Settings
The transport panel in the test console provides the functionality to specify the metadata and transport headers for messages in your test system. The following figure shows an example of a Transport panel on the test console.
Figure 4-9 Transport Panel in the Test Console
The preceding figure displays an example of the transport panel for a given service—in this case, a WSDL-based proxy service.
You can set the metadata and the transport headers in the message flow of a proxy service. In doing this, you influence the actions of the outbound transport. You can test the metadata, the message, and the headers so that you can see the output you get in the pipeline. 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 presents depending on the proxy service. The same set of transport parameters are displayed on the page 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 grouped in the Transport panel, below the Username and Password fields and above the group of transport header fields. The fields displayed are based on the transport type of the service. Certain fields are pre populated in the test console depending on the operation selection algorithm you selected for the service when you defined it.
For example, in the case of the transport panel displayed in Figure 4-9, the SOAPAction header field is populated with "http://example.orgprocessLoanApp". This value was taken from the service definition (the selection algorithm selected for this proxy service was SOAPAction Header). For more information about the selection algorithms, see "Adding a Proxy Service" in Proxy Services in Using the AquaLogic Service Bus Console.
When you specify values for fields in the transport panel, be aware whether you opted to test the service using a direct or indirect call—see Direct Calls and Indirect Calls—and specify the values according to whether the message will be processed through the transport layer or not.
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 Understanding How the Run Time Uses the Transport Settings in the Test Console.
About Security and Transports
- When using the test console to test HTTP(S) business services with BASIC authentication, the test console authenticates with the username 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 with 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.
Understanding How the Run Time Uses the Transport Settings in the Test Console
The test console allows you to specify header values and metadata. However, when the message is sent out, some headers and metadata may be modified or removed, and the underlying transport may in turn, ignore some of the headers and use its own values when the test is executed.
The following table describes the headers and metadata for which there are limitations when using the test console.
Table 4-3 Limitations to Transport Header and Metadata Values You Specify in the Test Console When Testing a Service
|
HTTP(S)1 |
All transport headers and other fields you set are preserved at run time. |
||
|
The AquaLogic Service Bus run time overrides any values you set for these parameters |
|||
|
When the Direct Call option is used, all transport headers and other fields you set are preserved at run time |
|||
|
When the Direct Call option is not used, the same limitations apply as for a transport header action configuration |
See the limitations for JMS transport headers described in "Transport Headers" in Proxy Services: Actions in Using the AquaLogic Service Bus Console. |
||
|
The same limitations apply as for a transport header action configuration |
See the limitations for JMS transport headers described in "Transport Headers" in Proxy Services: Actions in Using the AquaLogic Service Bus Console. |
||
|
No limitations. In other words, any transport headers and other fields you set are honored by the run time. This is true whether or not Direct Call is specified. |
|||
|
The AquaLogic Service Bus run time overrides any values you set for these parameters |
|||
|
No limitations. In other words, any transport headers and other fields you set are honored by the run time.2 |
|||
|
No limitations. In other words, any transport headers and other fields you set are honored by the run time. |
|||
1. When you test proxy services, the test console never sends a HTTP request over the network, therefore transport-level access control is not applied.
2. For example, in the case of FileName (Transport metadata)—the value you assign is used to append to the output file name. For example,
1698922710078805308-b3fc544.1073968e0ab.-7e8e-{$FileName}
