{"id":12808,"library":"api-testing","title":"MediaWiki API Testing Library","description":"API-Testing is an open-source JavaScript library designed for conducting end-to-end integration tests against MediaWiki's Action API and REST API. It runs on Node.js environments (specifically Node.js >= 14.18.0) and is built upon established testing tools: `supertest` for making HTTP requests, `Chai` for its flexible assertion capabilities, and `Mocha` as the test runner. The current stable version is 1.7.3. This library provides a specialized framework for testing MediaWiki instances, whether locally installed or remote, offering a higher-level abstraction compared to using the underlying HTTP and assertion libraries directly. Its release cadence is tied to MediaWiki development and is actively maintained, as evidenced by its integration with Wikimedia's Gerrit and Phabricator for contributions and bug tracking. Key differentiators include its tight coupling with MediaWiki API structures, simplifying test authoring for that ecosystem, and its comprehensive integration test approach.","status":"active","version":"1.7.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install api-testing","lang":"bash","label":"npm"},{"cmd":"yarn add api-testing","lang":"bash","label":"yarn"},{"cmd":"pnpm add api-testing","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by api-testing for making HTTP requests; users will typically need it for advanced request customization.","package":"supertest","optional":false},{"reason":"Assertion library commonly used alongside api-testing for writing test assertions.","package":"chai","optional":false},{"reason":"The primary testing framework expected for running tests written with api-testing.","package":"mocha","optional":false}],"imports":[{"note":"This is the primary factory function to initialize and configure an API testing client instance for a MediaWiki endpoint. ESM import is preferred in modern Node.js environments.","wrong":"const createMediaWikiTestClient = require('api-testing').createMediaWikiTestClient;","symbol":"createMediaWikiTestClient","correct":"import { createMediaWikiTestClient } from 'api-testing';"},{"note":"Represents the client for interacting with the MediaWiki Action API. It exposes chainable methods for constructing and sending API requests.","wrong":"import MediaWikiActionApiClient from 'api-testing/action';","symbol":"MediaWikiActionApiClient","correct":"import { MediaWikiActionApiClient } from 'api-testing';"},{"note":"A utility function or custom Chai assertion for robustly checking common MediaWiki API error structures within test responses, streamlining error assertion logic.","wrong":"expect(response).to.have.mediawikiError('code');","symbol":"expectMediaWikiApiError","correct":"import { expectMediaWikiApiError } from 'api-testing';"}],"quickstart":{"code":"import { expect } from 'chai';\nimport 'mocha'; // Mocha's describe/it are globally available after importing 'mocha'\nimport { createMediaWikiTestClient } from 'api-testing';\n\n// Configure the client to point to your test MediaWiki instance.\n// For demonstration, we use a public wiki, but you'd typically use a local test wiki or a dedicated service.\nconst wikiBaseUrl = process.env.MEDIAWIKI_BASE_URL ?? 'https://en.wikipedia.org';\n\n// Create a client instance. This object handles making requests to the configured MediaWiki API.\nconst apiTestClient = createMediaWikiTestClient(wikiBaseUrl);\n\ndescribe('MediaWiki Action API - Basic Site Info Tests', () => {\n  it('should be able to get basic site information without authentication', async () => {\n    // Use the Action API client to query for site info\n    const response = await apiTestClient.action({\n      action: 'query',\n      meta: 'siteinfo',\n      format: 'json'\n    })\n    .expectStatusCode(200) // Expect an HTTP 200 OK status\n    .expectSuccess()      // Expect a successful MediaWiki API response (no 'error' field)\n    .send();               // Execute the API request\n\n    expect(response.body.query.general.sitename).to.be.a('string').and.not.empty;\n    expect(response.body.query.general.generator).to.match(/^MediaWiki/);\n    expect(response.body.query.general.base).to.include(wikiBaseUrl);\n  }).timeout(10000); // Set a higher timeout for network requests\n\n  it('should gracefully handle requests for non-existent actions', async () => {\n    const response = await apiTestClient.action({\n      action: 'nonExistentMediaWikiAction123',\n      format: 'json'\n    })\n    .expectStatusCode(200) // MediaWiki often returns 200 for API errors within the response body\n    .expectFailure()      // Expect a MediaWiki API failure (presence of 'error' field)\n    .send();\n\n    expect(response.body.error.code).to.equal('apierror-unknown_action');\n    expect(response.body.error.info).to.include('Unrecognized parameter value for action');\n  }).timeout(5000);\n});\n\ndescribe('MediaWiki REST API - Page Content Tests', () => {\n  it('should retrieve the HTML content for the Main Page', async () => {\n    // Use the REST API client for specific page content\n    const response = await apiTestClient.rest(`/page/Main_Page/html`) // Example path for REST API\n      .expectStatusCode(200)\n      .send();\n\n    expect(response.text).to.be.a('string');\n    expect(response.text).to.include('<!DOCTYPE html>'); // Expect HTML content\n    expect(response.text).to.include('Main Page');\n  }).timeout(10000);\n});\n\n// To run this test file:\n// 1. Install dependencies: `npm install mocha chai api-testing`\n// 2. Ensure your package.json has `\"type\": \"module\"` if you're using ESM directly.\n// 3. Configure `MEDIAWIKI_BASE_URL` environment variable if targeting a specific wiki.\n// 4. Execute: `npx mocha path/to/your/test-file.ts` (if using TypeScript with ts-node) \n//    or `npx mocha path/to/your/test-file.js` (for plain JavaScript or transpiled code).","lang":"typescript","description":"Demonstrates how to set up `api-testing` with Mocha and Chai to test both MediaWiki Action and REST APIs, including success and error scenarios."},"warnings":[{"fix":"Upgrade your Node.js environment to version 14.18.0 or later. Consider using nvm (Node Version Manager) for easy switching.","message":"This library requires Node.js version 14.18.0 or newer. Running with older Node.js versions may lead to unexpected errors or unsupported features.","severity":"gotcha","affected_versions":"<14.18.0"},{"fix":"Ensure a MediaWiki instance is running and accessible from your test environment. Configure the `MEDIAWIKI_BASE_URL` environment variable or directly pass the URL when initializing the client. For local testing, consider using Docker to spin up a MediaWiki container.","message":"API-Testing relies on a running MediaWiki instance for executing tests. Tests will fail if the configured `MEDIAWIKI_BASE_URL` is inaccessible or does not point to a valid MediaWiki API endpoint.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the MediaWiki API documentation for specific authentication methods. Configure your test client with the necessary credentials (e.g., `apiTestClient.withCredentials('username', 'password')` if such methods are exposed).","message":"Authentication to MediaWiki APIs, especially for write actions or protected content, requires proper setup of user credentials (e.g., bot passwords, OAuth). Failure to configure authentication correctly will result in permission errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update all `require()` statements to `import` statements and ensure your `package.json` includes `\"type\": \"module\"` for Node.js projects, or use a bundler like Webpack/Rollup if targeting the browser (though this library is Node.js focused).","message":"Starting with a major version (e.g., v2.0.0 if it occurs), the library might transition to an ESM-only distribution, dropping CommonJS support. This would require changes to `require()` statements.","severity":"breaking","affected_versions":"future major versions (e.g., >=2.0.0)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `\"type\": \"module\"` to your `package.json` file, or rename your test file to `.mjs` to enable ESM support. Alternatively, if using CommonJS, convert `import` statements to `require()` (though `api-testing` might primarily offer ESM).","cause":"Attempting to use ES Modules (import/export) syntax in a Node.js environment configured for CommonJS, or without transpilation.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Increase the timeout for the specific test or suite using `this.timeout(20000)` inside the test function, or globally via Mocha's `--timeout` option. Investigate network connectivity or the responsiveness of the MediaWiki instance.","cause":"A test took longer than the default or specified Mocha timeout, often due to slow network requests or a non-responsive MediaWiki API.","error":"Error: Timeout of 10000ms exceeded. For async tests and hooks, ensure \"done()\" is called or a Promise is returned."},{"fix":"Ensure `createMediaWikiTestClient` is imported correctly and that the client object is properly instantiated. Consult the library's documentation for the exact API method names available on the client instance.","cause":"The `apiTestClient` object was not correctly initialized, or the method name is incorrect/unavailable in the current version.","error":"TypeError: apiTestClient.action is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}