WOPI Validation application

Status

To assist hosts in verifying their WOPI implementation, Office Online provides a WOPI Validation application that executes a test suite against a host’s WOPI implementation. The test suite verifies a variety of things, including that the semantics for all of the WOPI operations (CheckFileInfo, GetFile, PutFile, etc.) are correct and that request/response headers are set properly. New tests are added regularly.

The WOPI Validation application is an Office Online application similar to Word Online or PowerPoint Online. It uses the .wopitest file extension. The WOPI Validation application is included in the WOPI discovery XML just like all other Office Online applications.

Important

WOPI hosts should use the Test environment to ensure that they are running the latest version of the WOPI validation application.

<app name="WopiTest" checkLicense="true">
    <action name="view" urlsrc="https://onenote.officeapps-df.live.com/hosting/WopiTestFrame.aspx" ext="wopitest"/>
    <action name="getinfo" urlsrc="https://onenote.officeapps-df.live.com/hosting/GetWopiTestInfo.ashx" ext="wopitest"/>
</app>

The validation application provides two WOPI actions, view and getinfo, which can be used to trigger the test suite.

Warning

The test suite will test operations like PutFile, so the contents of the .wopitest file will be destroyed.

In addition, some tests create new files or containers using the PutRelativeFile, CreateChildFile, and CreateChildContainer operations. While the validation application attempts to clean up these files, if there are errors in the WOPI implementation, these clean up actions may fail, leaving behind these test files.

If that should happen, you must clean up these test files manually. If you don’t, subsequent test runs may fail.

Interactive WOPI validation

The simplest way to use the validation application is to use the view action. To use the view action hosts should treat .wopitest files the same way other Office documents are treated. In other words, hosts should do the following:

  1. Launch a host page pointed at the .wopitest file. Ideally, this should be the same host page used to host regular Office Online sessions. This will allow the validation application to test things like PostMessage and do some validation on the way the Office Online iframe was loaded.
  2. The host page will create and navigate the Office Online iframe to the view action URL provided in WOPI discovery. The WOPIsrc and access token should be provided just like with all other actions.
  3. The WOPI validation application will load and display a number of test groups. Each test group can be expanded to reveal the individual tests that it contains. You can run tests individually, by test group, or run all tests using the Run All button.
An image showing the WOPI validation application user interface.

Figure 6 WOPI validation application UI

Tests can either pass, fail, or be skipped. Before executing any tests, Office Online will do some basic validation (e.g. confirm the file really has the .wopitest file extension) and check any applicable pre-requisites. Any test whose pre-requisites are not met will simply be skipped. For example, the tests in the EditFlows test group require the SupportsUpdate property to be set to true. If it is not, the tests in that group will all be skipped.

An image showing the WOPI validation application after the entire test suite has been run.

Figure 7 Tests can pass, fail, or be skipped

Once a test has been run, you can click on it to see the each request that was issued by the test and the response data. If the test failed or was skipped, the reason will be displayed just under the test name. You can click on the specific request that failed and see more information about what the test was expecting. If you are implementing proof key validation, you can use the Current Proof Key Data and Old Proof Key Data buttons to see the intermediate data on how the request was signed, which is extremely useful when debugging a proof key validation implementation.

An image showing WOPI validation results for a particular test.

Figure 8 Example WOPI validation results

Tip

For ease of testing, we strongly recommend that hosts support the .wopitest file extension just like all other file extensions supported by Office Online and included in WOPI discovery. This is especially important while testing, since it provides any user a quick and easy way to execute the validation test suite.

Automated WOPI validation

The WOPI Validation Application exposes a second action, getinfo. The getinfo action is designed to be used server-to-server. Instead of launching a host page, the host can simply do the following:

  1. Issue a GET request to the getinfo action URL provided in WOPI discovery. The WOPIsrc, access token, and access_token_ttl should be provided just like with all other actions.

    Note

    The getinfo action only supports GET requests, so the access token, and access_token_ttl values must be appended to the URL instead of being passed as POST parameters.

  2. Office Online will do some basic validation (e.g. confirm the file really has the .wopitest extension) and then return a JSON-formatted array of test URLs.

  3. Hosts should then make a GET request to each test URL. Office Online will run the specified test and return results in a simple JSON object. No changes to the URL are needed; the necessary parameters are included already on the URL returned from the validation application.

This is intended for automated use. For example, a host may wish to run this validation as part of rolling out new versions of their WOPI host.

Automated WOPI validation using a command-line tool

The host can use a Python-based command-line tool at https://github.com/Microsoft/wopi-validator-cli-python instead of launching a host page. This tool also uses the getinfo action URL provided in WOPI discovery to execute the WOPI Validation application.

  1. Create a .wopitest file on the host.
  2. Download and install the command-line tool by following the instructions at https://github.com/Microsoft/wopi-validator-cli-python
  3. Execute the tool by providing the WOPIsrc and access token of the .wopitest file.

Tip

  1. The tool executes all the tests based on the chosen VALIDATOR_TEST_CATEGORY and displays the results.
  2. To view the request and response details for each test, you can turn on verbose logging while executing the command-line tool.