ApiTestCase.php
No OneTemporary
Actions

Size

10 KB

Referenced Files

None

Subscribers

None

ApiTestCase.php
View Options

	<?php

	namespace MediaWiki\Tests\Api;

	use ArrayAccess;
	use LogicException;
	use MediaWiki\Api\ApiBase;
	use MediaWiki\Api\ApiErrorFormatter;
	use MediaWiki\Api\ApiMain;
	use MediaWiki\Api\ApiMessage;
	use MediaWiki\Api\ApiQueryTokens;
	use MediaWiki\Api\ApiResult;
	use MediaWiki\Api\ApiUsageException;
	use MediaWiki\Context\RequestContext;
	use MediaWiki\MediaWikiServices;
	use MediaWiki\Message\Message;
	use MediaWiki\Permissions\Authority;
	use MediaWiki\Request\FauxRequest;
	use MediaWiki\Session\Session;
	use MediaWiki\Session\SessionManager;
	use MediaWiki\Tests\Unit\Permissions\MockAuthorityTrait;
	use MediaWikiLangTestCase;
	use PHPUnit\Framework\AssertionFailedError;
	use PHPUnit\Framework\Constraint\Constraint;
	use ReturnTypeWillChange;

	abstract class ApiTestCase extends MediaWikiLangTestCase {
	use MockAuthorityTrait;

	/** @var string */
	protected static $apiUrl;

	/** @var ApiErrorFormatter\|null */
	protected static $errorFormatter = null;

	/**
	* @var ApiTestContext
	*/
	protected $apiContext;

	protected function setUp(): void {
	global $wgServer;

	parent::setUp();
	self::$apiUrl = $wgServer . wfScript( 'api' );

	// HACK: Avoid creating test users in the DB if the test may not need them.
	$getters = [
	'sysop' => fn () => $this->getTestSysop(),
	'uploader' => fn () => $this->getTestUser(),
	];
	$fakeUserArray = new class ( $getters ) implements ArrayAccess {
	private array $getters;
	private array $extraUsers = [];

	public function __construct( array $getters ) {
	$this->getters = $getters;
	}

	public function offsetExists( $offset ): bool {
	return isset( $this->getters[$offset] ) \|\| isset( $this->extraUsers[$offset] );
	}

	#[ReturnTypeWillChange]
	public function offsetGet( $offset ) {
	if ( isset( $this->getters[$offset] ) ) {
	return ( $this->getters[$offset] )();
	}
	if ( isset( $this->extraUsers[$offset] ) ) {
	return $this->extraUsers[$offset];
	}
	throw new LogicException( "Requested unknown user $offset" );
	}

	public function offsetSet( $offset, $value ): void {
	$this->extraUsers[$offset] = $value;
	}

	public function offsetUnset( $offset ): void {
	unset( $this->getters[$offset] );
	unset( $this->extraUsers[$offset] );
	}
	};

	self::$users = $fakeUserArray;

	$this->setRequest( new FauxRequest( [] ) );

	$this->apiContext = new ApiTestContext();
	}

	protected function tearDown(): void {
	// Avoid leaking session over tests
	SessionManager::getGlobalSession()->clear();

	ApiBase::clearCacheForTest();

	parent::tearDown();
	}

	/**
	* Does the API request and returns the result.
	*
	* @param array $params
	* @param array\|null $session
	* @param bool $appendModule
	* @param Authority\|null $performer
	* @param string\|null $tokenType Set to a string like 'csrf' to send an
	* appropriate token
	* @param string\|null $paramPrefix Prefix to prepend to parameters
	* @return array List of:
	* - the result data (array)
	* - the request (WebRequest)
	* - the session data of the request (array)
	* - if $appendModule is true, the Api module $module
	* @throws ApiUsageException
	*/
	protected function doApiRequest( array $params, ?array $session = null,
	$appendModule = false, ?Authority $performer = null, $tokenType = null,
	$paramPrefix = null
	) {
	global $wgRequest;

	// re-use existing global session by default
	$session ??= $wgRequest->getSessionArray();

	$sessionObj = SessionManager::singleton()->getEmptySession();

	if ( $session !== null ) {
	foreach ( $session as $key => $value ) {
	$sessionObj->set( $key, $value );
	}
	}

	// set up global environment
	if ( !$performer && !$this->needsDB() ) {
	$performer = $this->mockRegisteredUltimateAuthority();
	}
	if ( $performer ) {
	$legacyUser = $this->getServiceContainer()->getUserFactory()->newFromAuthority( $performer );
	$contextUser = $legacyUser;
	// Clone the user object, because something in Session code will replace its user with "Unknown user"
	// if it doesn't exist. But that'll also change $contextUser, and the token won't match (T341953).
	$sessionUser = clone $contextUser;
	} else {
	$contextUser = $this->getTestSysop()->getUser();
	$performer = $contextUser;
	$sessionUser = $contextUser;
	}

	$sessionObj->setUser( $sessionUser );
	if ( $tokenType !== null ) {
	if ( $tokenType === 'auto' ) {
	$tokenType = ( new ApiMain() )->getModuleManager()
	->getModule( $params['action'], 'action' )->needsToken();
	}
	if ( $tokenType !== false ) {
	$params['token'] = ApiQueryTokens::getToken(
	$contextUser,
	$sessionObj,
	ApiQueryTokens::getTokenTypeSalts()[$tokenType]
	)->toString();
	}
	}

	// prepend parameters with prefix
	if ( $paramPrefix !== null && $paramPrefix !== '' ) {
	$prefixedParams = [];
	foreach ( $params as $key => $value ) {
	$prefixedParams[$paramPrefix . $key] = $value;
	}
	$params = $prefixedParams;
	}

	$wgRequest = $this->buildFauxRequest( $params, $sessionObj );
	RequestContext::getMain()->setRequest( $wgRequest );
	RequestContext::getMain()->setAuthority( $performer );
	RequestContext::getMain()->setUser( $sessionUser );

	// set up local environment
	$context = $this->apiContext->newTestContext( $wgRequest, $performer );

	$module = new ApiMain( $context, true );

	// run it!
	$module->execute();

	// construct result
	$results = [
	$module->getResult()->getResultData( null, [ 'Strip' => 'all' ] ),
	$context->getRequest(),
	$context->getRequest()->getSessionArray()
	];

	if ( $appendModule ) {
	$results[] = $module;
	}

	return $results;
	}

	/**
	* @since 1.37
	* @param array $params
	* @param Session\|array\|null $session
	* @return FauxRequest
	*/
	protected function buildFauxRequest( $params, $session ) {
	return new FauxRequest( $params, true, $session );
	}

	/**
	* Convenience function to access the token parameter of doApiRequest()
	* more succinctly.
	*
	* @param array $params Key-value API params
	* @param array\|null $session Session array
	* @param Authority\|null $performer A User object for the context
	* @param string $tokenType Which token type to pass
	* @param string\|null $paramPrefix Prefix to prepend to parameters
	* @return array Result of the API call
	*/
	protected function doApiRequestWithToken( array $params, ?array $session = null,
	?Authority $performer = null, $tokenType = 'auto', $paramPrefix = null
	) {
	return $this->doApiRequest( $params, $session, false, $performer, $tokenType, $paramPrefix );
	}

	protected static function getErrorFormatter() {
	self::$errorFormatter ??= new ApiErrorFormatter(
	new ApiResult( false ),
	MediaWikiServices::getInstance()->getLanguageFactory()->getLanguage( 'en' ),
	'none'
	);
	return self::$errorFormatter;
	}

	public static function apiExceptionHasCode( ApiUsageException $ex, $code ) {
	return (bool)array_filter(
	self::getErrorFormatter()->arrayFromStatus( $ex->getStatusValue() ),
	static function ( $e ) use ( $code ) {
	return is_array( $e ) && $e['code'] === $code;
	}
	);
	}

	/**
	* Expect an ApiUsageException to be thrown with the given parameters, which are the same as
	* ApiUsageException::newWithMessage()'s parameters. This allows checking for an exception
	* whose text is given by a message key instead of text, so as not to hard-code the message's
	* text into test code.
	*
	* @deprecated since 1.43; use expectApiErrorCode() instead, it's better to test error codes than messages
	* @param string\|array\|Message $msg
	* @param string\|null $code
	* @param array\|null $data
	* @param int $httpCode
	*/
	protected function setExpectedApiException(
	$msg, $code = null, ?array $data = null, $httpCode = 0
	) {
	$expected = ApiUsageException::newWithMessage( null, $msg, $code, $data, $httpCode );
	$this->expectException( ApiUsageException::class );
	$this->expectExceptionMessage( $expected->getMessage() );
	}

	private ?string $expectedApiErrorCode;

	/**
	* Expect an ApiUsageException that results in the given API error code to be thrown.
	*
	* Note that you can't mix this method with standard PHPUnit expectException() methods,
	* as PHPUnit will catch the exception and prevent us from testing it.
	*
	* @since 1.41
	* @param string $expectedCode
	*/
	protected function expectApiErrorCode( string $expectedCode ) {
	$this->expectedApiErrorCode = $expectedCode;
	}

	/**
	* Assert that an ApiUsageException will result in the given API error code being outputted.
	*
	* @since 1.41
	* @param string $expectedCode
	* @param ApiUsageException $exception
	* @param string $message
	*/
	protected function assertApiErrorCode( string $expectedCode, ApiUsageException $exception, string $message = '' ) {
	$constraint = new class( $expectedCode ) extends Constraint {
	private string $expectedApiErrorCode;

	public function __construct( string $expected ) {
	$this->expectedApiErrorCode = $expected;
	}

	public function toString(): string {
	return 'API error code is ';
	}

	private function getApiErrorCode( $other ) {
	if ( !$other instanceof ApiUsageException ) {
	return null;
	}
	$errors = $other->getStatusValue()->getMessages();
	if ( count( $errors ) === 0 ) {
	return '(no error)';
	} elseif ( count( $errors ) > 1 ) {
	return '(multiple errors)';
	}
	return ApiMessage::create( $errors[0] )->getApiCode();
	}

	protected function matches( $other ): bool {
	return $this->getApiErrorCode( $other ) === $this->expectedApiErrorCode;
	}

	protected function failureDescription( $other ): string {
	return sprintf(
	'%s is equal to expected API error code %s',
	$this->exporter()->export( $this->getApiErrorCode( $other ) ),
	$this->exporter()->export( $this->expectedApiErrorCode )
	);
	}
	};

	$this->assertThat( $exception, $constraint, $message );
	}

	/**
	* @inheritDoc
	*
	* Adds support for expectApiErrorCode().
	*/
	protected function runTest() {
	try {
	$testResult = parent::runTest();

	} catch ( ApiUsageException $exception ) {
	if ( !isset( $this->expectedApiErrorCode ) ) {
	throw $exception;
	}

	$this->assertApiErrorCode( $this->expectedApiErrorCode, $exception );

	return null;
	}

	if ( !isset( $this->expectedApiErrorCode ) ) {
	return $testResult;
	}

	throw new AssertionFailedError(
	sprintf(
	'Failed asserting that exception with API error code "%s" is thrown',
	$this->expectedApiErrorCode
	)
	);
	}
	}

	/** @deprecated class alias since 1.42 */
	class_alias( ApiTestCase::class, 'ApiTestCase' );

File Metadata

Mime Type: text/x-php
Expires: Aug 20 2026, 02:11 (10 w, 4 d ago)
Storage Engine: local-disk
Storage Format: Raw Data
Storage Handle: cb/be/c2a28316f7bfb1ec272cc04fd001
Default Alt Text: ApiTestCase.php (10 KB)

ApiTestCase.phpNo OneTemporaryActions

ApiTestCase.phpView Options

File Metadata

Event Timeline

ApiTestCase.php
No OneTemporary
Actions

ApiTestCase.php
View Options