MediaWiki API integration tests

The API testing tool is a standalone project that contains end-to-end integration tests for the MediaWiki Action API and REST API. You can run the tests locally by downloading the testing tool and configuring it to access a test wiki. The tests are implemented in JavaScript for node.js, using the SuperTest HTTP testing library, the Chai assertion library, and the Mocha testing framework.

Setting up a testing environment
See the project README.

Running tests
See the project README.

Writing tests
Action API tests are stored in the /test directory; REST API tests are stored in the /test/REST directory. Each file corresponds to a test suite covering an area of MediaWiki functionality. A test suite is defined by a top-level  function that takes two parameters:


 * a string describing the feature being tested
 * a function containing the test code

Within the  function, you can use the   hook to set up preconditions and the   function to create individual test cases. You can break up a long, complex test suite by nesting additional  functions under the top-level function.

Within a test suite, each test case is executed as an  function. These asynchronous functions contain  expressions to execute test steps in sequence and   expressions to evaluate responses. Assertions can use any methods supported by the Chai  interface, such as ,   (using a regular expression), and.

Here's a template that shows the main sections of a test suite:

Generating random strings
When writing tests, use random values whenever possible. This allows tests to function when run against a wiki that already contains content from previous test runs. To generate a random string for use in a test, use the  function.

Handling page titles
The API testing tool includes functions to help you manage wiki page titles.

Fixtures
To manage accounts and sessions, the API testing tool provides convenient fixtures that you can reuse across tests.

To open a wiki session and log in using a fixture, instantiate the account asynchronously using a fixtures function.

Action API

REST API

Custom accounts
If you're planning to make a permanent change to an account (for example: blocking an account) or if you need an account with a custom prefix, you can create a custom account instead of using a fixture. To open a wiki session and log in using a custom account, define a session using the  function, and log in using the   method. Applying a prefix to the username is optional.

Action API

REST API

Account properties
Once logged in, you can access information about the account using the,  , and   properties.

Anonymous users
To create an anonymous user, define the account using the  function, but omit the   function. This opens a new session without logging in, resulting in an anonymous user.

Action API

REST API

Working with wiki pages
The API testing tool provides helpful methods for interacting with wiki pages, including editing a page, exploring page history, and retrieving page HTML. To create and edit a page, use the  function to generate a random title and the   method to edit the page. To validate the edit, you can use the  method to get the HTML of the page and the   method to check for the edited text. For a REST API test, add  to the top level   function below.

Calling the Action API
The Action API list, meta, and prop modules provide access to information about wiki pages and users. The testing tool provides methods that let you make GET requests to these modules within tests.

Other Action API calls
To call any module in the Action API, use the  method.

Some Action API calls require a token. See individual API action docs for token requirements. For example, to patrol a page, make a POST request to the  action. In the API:Patrol docs, we can see that this call requires a token, which we can get using the  method.

The  method fails if the response contains an error code. To test for expected errors, you can use the  method.

Action API example test
The Recent Changes test suite contains two tests cases that validate a user's ability to access recent changes for a page.

Calling the REST API
The testing tool provides methods that let you make requests to the MediaWiki REST API by the HTTP request method:


 * : Make an HTTP GET request to the REST API
 * : Make an HTTP POST request to the REST API
 * : Make an HTTP PUT request to the REST API
 * : Make an HTTP DELETE request to the REST API

All REST API methods take two arguments:


 * The endpoint path as a string, starting after the version number (Example:  for the compare revisions endpoint)
 * If supported by the endpoint, a request body as an object

See the REST API docs for endpoint paths and request body requirements.

REST API example test
Here's an example test suite with two tests for the get revision endpoint.

Contributing
The API tests are hosted on Gerrit and mirrored on GitHub. To open a patch request, see the guide to using Gerrit for Wikimedia projects.

To review open tasks or file a bug report, visit Phabricator.

Sharing feedback
To share your feedback about this page or to ask a question about API tests, leave a comment on the talk page.