14 Testing Your Integrated Excel Workbook

This chapter describes how to test and validate the integrated Excel workbooks as you configure it, and how to run a server ping test.

This chapter includes the following sections:

• About Testing Your Integrated Excel Workbook

• Testing Your Fusion Web Application

• Validating the Integrated Excel Workbook Configuration

• Testing Your Integrated Excel Workbook

14.1 About Testing Your Integrated Excel Workbook

Testing an integrated Excel workbook before you publish and deploy it to your end users enables you to verify that the functionality you configure behaves as you intend. Before you test your integrated Excel workbook, test the Fusion web application with which you integrate the Excel workbook.

Before you deploy the integrated Excel workbook, you should validate it and test its integration with your Fusion web application. Testing an integrated Excel workbook includes the following processes:

• Validating the integrated Excel workbook

• Running the integrated Excel workbook in test mode

14.1.1 Integrated Excel Workbook Testing Use Cases and Examples

To test your integrated Excel Workbook, click the Run button on the Oracle ADF tab, and click the Stop button to return to the design mode. Figure 14-1 shows the buttons of the Oracle ADF tab in design mode and in test mode.

Figure 14-1 Run and Stop buttons in Oracle ADF tab

14.1.2 Additional Functionality for Testing an Integrated Excel Workbook

After you have validated and tested your integrated Excel workbook, you may need to perform additional steps to make your workbook available to end users.

• Publishing your integrated Excel workbook: After you test and validate your workbook, you must publish it. For more information see, Publishing Your Integrated Excel Workbook.

• Deploying your integrated Excel workbook: After you publish your workbook, you may wish to deploy it with your Fusion web application. For more information, see Deploying a Published Workbook with Your Fusion Web Application.

14.2 Testing Your Fusion Web Application

Test the Fusion web application that you integrate your Excel workbook with before you start testing the integrated Excel workbook. For information about testing a Fusion web application, see the Developing Fusion Web Applications with Oracle Application Development Framework. Verify that the Fusion web application you want to integrate an Excel workbook with, supports ADF Desktop Integration by carrying out the procedure described in Verifying That Your Fusion Web Application Supports ADF Desktop Integration. You may also want to test the view instances of the ADF application module before you test the Fusion web application. For more information about testing ADF application module, see the "Using the Oracle ADF Model Tester for Testing and Debugging" section of Developing Fusion Web Applications with Oracle Application Development Framework.

If the integrated Excel workbooks are not saved in Application Sources directory of the Fusion web application, then before you run the Fusion web application in JDeveloper, ensure that all integrated Excel workbooks and the Excel application are closed. The application deployment may fail if it encounters locked files as Excel locks the files that it opens.

Tip:

If you plan to test integrated Excel workbooks that you downloaded from web pages of the Fusion web application, you should republish them before redeploying the application. Republishing the workbooks ensures that you have their latest versions.

If you make changes to the Fusion web application to resolve problems identified by testing the application, you need to:

• Close Excel and all integrated Excel workbooks. The application deployment may fail if it encounters locked files, as Excel locks the files that it opens.

• Rebuild the JDeveloper project where you develop the Fusion web application.

• Run the Fusion web application.

• Reload the page definition files that are associated with the integrated Excel workbook. Click the Refresh Bindings button in Oracle ADF tab of the integrated Excel workbook to reload the page definition files.

These steps make sure that the changes in the Fusion web application are available to the integrated Excel workbook. For information about how to reload a page definition file, see How to Reload a Page Definition File in an Excel Workbook.

14.3 Validating the Integrated Excel Workbook Configuration

ADF Desktop Integration provides a set of validation rules for the integrated Excel workbook configuration. After creating your integrated Excel workbook, you may validate the workbook before you proceed for testing or deployment.

14.3.1 How to Validate the Integrated Excel Workbook Configuration

You should validate the integrated Excel workbook configuration before testing or deploying the workbook.

To validate the integrated Excel workbook configuration:

1. Open the integrated Excel workbook.
2. In your integrated Excel workbook, click the Oracle ADF tab.
3. In the Test group, click Validate.

   The Configuration Validation dialog appears listing all your warnings and errors.

4. If any warning or error is displayed, click to select it. A description of the warning or error message is displayed in the dialog.

   For example, Figure 14-2 illustrates a validation failure message of an invalid EL expression.

   Figure 14-2 Invalid EL Expression Resulting in a Validation Failure

   

   If no warning or error appears, click Close to close the dialog.

Note:

You may continue to keep the Configuration Validation dialog open while you resolve the validation failures. To verify whether you have resolved an error or a warning, click Revalidate to run the validation rules again.

14.3.2 What Happens When You Validate the Integrated Excel Workbook Configuration

When you validate the workbook at design time, ADF Desktop Integration validates all workbook configuration properties, including worksheet and worksheet component properties, against defined validation rules. Any and all validation failures (errors and warnings) are listed in the Configuration Validation dialog. Each validation failure, when selected, provides contextual information about the failure, and provides enough detail to locate and fix each validation failure.

The Configuration Validation dialog provides the following information for each validation failure:

• Severity type (error or warning)

• Name of the worksheet. The word Workbook is displayed if the validation failure does not correspond to a particular worksheet.

• Worksheet component ID ("Workbook" or "Worksheet" if the validation failure does not correspond to a particular worksheet component)

• Property containing the validation failure

• Description of the validation failure (error or warning)

When you select a specific failure entry in the dialog, the dialog displays additional details about the failure including:

• Full property context path

• Property value

Certain validation rules may result in multiple distinct failures. For example, when an expression is being validated, different validation failures occur based on expression type, expression syntax, or the location in which the property is exposed in the workbook configuration.

For example, consider the following expression value:

#{bindings.EmpView1.hints.Empno.label}

The expression value is legal when used within a column header label inside of a table component, but the same expression value is illegal when specified as part of the Worksheet.Title expression.

Note:

If Enabled is set to False for a group of workbook configuration properties, validation of other property values within the same group is skipped.

14.3.3 How to Fix Validation Failures

When you validate your workbook, you might get validation failures or warning messages, which you can fix easily by following these steps:

1. Identify the component that gave the error or warning message.

   In Figure 14-2, note the component location and other details (for example, property name) that the Configuration Validation dialog provides.

2. Open the property editor of the component.
3. Navigate to the invalid property value identified by the full property context path.
4. Edit the property value to resolve the validation failure.

   Figure 14-3 illustrates the property editor for the ADF Table component with a valid value for the RowLimit.MaxRows property.

   Figure 14-3 Resolving Validation Failure

   
5. Revalidate the workbook to verify whether the validation failure has been resolved. Click Revalidate to run the validation rules again.
6. After fixing all validation failures, click Close to close the Configuration Validation dialog.

   Figure 14-4 illustrates the Configuration Validation dialog with no warnings or error messages.

   Figure 14-4 Configuration Validation Dialog with No Validation Failure Messages

   

14.3.4 How to Log the Integrated Excel Workbook Configuration Validation Failures at Runtime

By default, there is no runtime validation of integrated Excel workbook configuration. However, you may log validation failures at runtime by setting the client log level to Verbose. For more information about enabling client-side logging, see About Client-Side Logging.

14.4 Testing Your Integrated Excel Workbook

As you configure your Excel workbook to integrate with a Fusion web application, you can switch to test mode from design mode to test the functionality that you add to the workbook. You use the Oracle ADF tab to switch to test mode from design mode and from design mode to test mode.

Test mode enables you to test the functionality of your integrated Excel workbook as you configure it incrementally. It also enables you to view the integrated Excel workbook from the end user's perspective, as test mode corresponds to what end users see when they view and run the published integrated Excel workbook. The difference between an integrated Excel workbook in test mode and a published integrated Excel workbook is that the ADF Desktop Integration task pane is not available to users of the published integrated Excel workbook.

For more information about test mode and design mode, see About Development Tools.

There are some differences between the test mode and the runtime mode when you run the integrated Excel workbook. Table 14-1 lists these differences.

---

Table 14-1 Differences between Test mode and Runtime mode

Test mode	Runtime mode
Does not perform tamper check	Performs tamper check, if enabled by the server
Does not display the connection confirmation dialog	Displays the connection confirmation dialog
Displays the Oracle ADF ribbon tab	Does not display Oracle ADF tab
Allows you to switch back to design mode	Does not allow you to switch back to design mode

---

ADF Desktop Integration can generate log files that capture information based on events triggered by an integrated Excel workbook. For more information about these log files, see Troubleshooting an Integrated Excel Workbook.

Note:

Before you start testing the integrated Excel workbook, ensure that:

• The Fusion web application is running.

• The ping to server is successful, and the server is configured for ADF Desktop Integration.

• The ADF Desktop Integration version of the server and the client are the same.

To run an integrated Excel workbook in test mode:

• To test and run an integrated Excel workbook, click the Run button on the Oracle ADF tab.

  The integrated Excel workbook switches to test mode from design mode. Before starting the test mode, ADF Desktop Integration clears all design time component placeholders.

To stop test mode and return the integrated Excel workbook to design mode:

• In the integrated Excel workbook that you are testing, click the Stop button on the Oracle ADF tab.

  The integrated Excel workbook switches to design mode from test mode. Before switching back to design mode, ADF Desktop Integration removes all visible and cached data from all parts of the workbook, and then redraws the design time component placeholders.