WOPI Validation application¶
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.
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 test suite will test operations like PutFile, so the contents of the
.wopitest file will be
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
.wopitest files the same way other Office documents are treated. In other words, hosts should do the
- Launch a host page pointed at the
.wopitestfile. 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.
- 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.
- 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.
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.
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.
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¶
Office Online will do some basic validation (e.g. confirm the file really has the
.wopitestextension) and then return a JSON-formatted array of test URLs.
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.
- Create a
.wopitestfile on the host.
- Download and install the command-line tool by following the instructions at https://github.com/Microsoft/wopi-validator-cli-python
- Execute the tool by providing the WOPIsrc and access token of the
- The tool executes all the tests based on the chosen VALIDATOR_TEST_CATEGORY and displays the results.
- To view the request and response details for each test, you can turn on verbose logging while executing the command-line tool.