MediaWiki API integration tests

The API testing tool is a standalone project that contains end-to-end integration tests for MediaWiki's action 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
Test code is stored in the /test 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 and 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.

Creating accounts and logging in
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.

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.

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.

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.

Edit a page

Return a revision record for a page

Return HTML for a page with comments stripped

Return the most recent changes entry matching the given parameters

Return the newest log entry matching the given parameters

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.

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.

The List API

The Meta API

The Properties API

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.

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

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.