Localisation updates from https://translatewiki.net.

[mediawiki.git] / tests / phpunit / structure / ApiStructureTest.php

<?php

use MediaWiki\Api\ApiBase;
use MediaWiki\Api\ApiDisabled;
use MediaWiki\Api\ApiMain;
use MediaWiki\Api\ApiModuleManager;
use MediaWiki\Api\ApiQueryDisabled;
use MediaWiki\Context\RequestContext;
use MediaWiki\MainConfigNames;
use MediaWiki\Message\Message;
use MediaWiki\Title\Title;
use Wikimedia\TestingAccessWrapper;

/**
 * Checks that all API modules, core and extensions, conform to the conventions:
 * - have documentation i18n messages (the test won't catch everything since
 *   i18n messages can vary based on the wiki configuration, but it should
 *   catch many cases for forgotten i18n)
 * - do not have inconsistencies in the parameter definitions
 *
 * @group API
 * @group Database
 * @coversNothing
 */
class ApiStructureTest extends MediaWikiIntegrationTestCase {

        /** @var ApiMain */
        private static $main;

        /** @var array Sets of globals to test. Each array element is input to HashConfig */
        private static $testGlobals = [
                [
                        MainConfigNames::MiserMode => false,
                ],
                [
                        MainConfigNames::MiserMode => true,
                ],
        ];

        /**
         * Initialize/fetch the ApiMain instance for testing
         * @return ApiMain
         */
        private static function getMain() {
                if ( !self::$main ) {
                        self::$main = new ApiMain( RequestContext::getMain() );
                        self::$main->getContext()->setLanguage( 'en' );
                        self::$main->getContext()->setTitle(
                                Title::makeTitle( NS_SPECIAL, 'Badtitle/dummy title for ApiStructureTest' )
                        );

                        // Inject ApiDisabled and ApiQueryDisabled so they can be tested too
                        self::$main->getModuleManager()->addModule( 'disabled', 'action', ApiDisabled::class );
                        self::$main->getModuleFromPath( 'query' )
                                ->getModuleManager()->addModule( 'query-disabled', 'meta', ApiQueryDisabled::class );
                }
                return self::$main;
        }

        /**
         * Test a message
         * @param string|array|Message $msg Message definition, see Message::newFromSpecifier()
         * @param string $what Which message is being checked
         */
        private function checkMessage( $msg, $what ) {
                // Message::newFromSpecifier() will throw and fail the test if the specifier isn't valid
                $msg = Message::newFromSpecifier( $msg );
                $this->assertTrue( $msg->exists(), "API $what message \"{$msg->getKey()}\" must exist. Did you forgot to add it to your i18n/en.json?" );
        }

        /**
         * @dataProvider provideDocumentationExists
         * @param string $path Module path
         * @param array $globals Globals to set
         */
        public function testDocumentationExists( $path, array $globals ) {
                // Set configuration variables
                $this->overrideConfigValues( $globals );

                $main = self::getMain();

                // Fetch module.
                $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );

                // Test messages for flags.
                foreach ( $module->getHelpFlags() as $flag ) {
                        $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
                }

                // Module description messages.
                $this->checkMessage( $module->getSummaryMessage(), 'Module summary' );
                $extendedDesc = $module->getExtendedDescription();
                if ( is_array( $extendedDesc ) && is_array( $extendedDesc[0] ) ) {
                        // The definition in getExtendedDescription() may also specify fallback keys. This is weird,
                        // and it was never needed for other API doc messages, so it's only supported here.
                        $extendedDesc = Message::newFallbackSequence( $extendedDesc[0] )
                                ->params( array_slice( $extendedDesc, 1 ) );
                }
                $this->checkMessage( $extendedDesc, 'Module help top text' );

                // Messages for examples.
                foreach ( $module->getExamplesMessages() as $qs => $msg ) {
                        $this->assertStringStartsNotWith( 'api.php?', $qs,
                                "Query string must not begin with 'api.php?'" );
                        $this->checkMessage( $msg, "Example $qs" );
                }
        }

        public static function provideDocumentationExists() {
                $main = self::getMain();
                $paths = self::getSubModulePaths( $main->getModuleManager() );
                array_unshift( $paths, $main->getModulePath() );

                $ret = [];
                foreach ( $paths as $path ) {
                        foreach ( self::$testGlobals as $globals ) {
                                $g = [];
                                foreach ( $globals as $k => $v ) {
                                        $g[] = "$k=" . var_export( $v, 1 );
                                }
                                $k = "Module $path with " . implode( ', ', $g );
                                $ret[$k] = [ $path, $globals ];
                        }
                }
                return $ret;
        }

        private function doTestParameters( string $path, array $params, string $name ): void {
                $main = self::getMain();

                $dataName = $this->dataName();
                $this->assertNotSame( '', $name, "$dataName: Name cannot be empty" );
                $this->assertArrayHasKey( $name, $params, "$dataName: Existence check" );

                $ret = $main->getParamValidator()->checkSettings(
                        $main->getModuleFromPath( $path ), $params, $name, []
                );

                // Warn about unknown keys. Don't fail, they might be for forward- or back-compat.
                if ( is_array( $params[$name] ) ) {
                        $keys = array_diff(
                                array_keys( $params[$name] ),
                                $ret['allowedKeys']
                        );
                        if ( $keys ) {
                                // Don't fail for this, for back-compat
                                $this->addWarning(
                                        "$dataName: Unrecognized settings keys were used: " . implode( ', ', $keys )
                                );
                        }
                }

                if ( count( $ret['issues'] ) === 1 ) {
                        $this->fail( "$dataName: Validation failed: " . reset( $ret['issues'] ) );
                } elseif ( $ret['issues'] ) {
                        $this->fail( "$dataName: Validation failed:\n* " . implode( "\n* ", $ret['issues'] ) );
                }

                // Check message existence
                $done = [];
                foreach ( $ret['messages'] as $msg ) {
                        // We don't really care about the parameters, so do it simply
                        $key = $msg->getKey();
                        if ( !isset( $done[$key] ) ) {
                                $done[$key] = true;
                                $this->checkMessage( $key, "$dataName: Parameter" );
                        }
                }
        }

        /**
         * @dataProvider provideParameters
         */
        public function testParameters( string $path, string $argset, array $args, ApiMain $main ): void {
                $module = $main->getModuleFromPath( $path );
                $params = $module->getFinalParams( ...$args );
                if ( !$params ) {
                        $this->addToAssertionCount( 1 );
                        return;
                }
                foreach ( $params as $param => $_ ) {
                        $this->doTestParameters( $path, $params, $param );
                }
        }

        public static function provideParameters(): Iterator {
                $main = self::getMain();
                $paths = self::getSubModulePaths( $main->getModuleManager() );
                array_unshift( $paths, $main->getModulePath() );
                $argsets = [
                        'plain' => [],
                        'for help' => [ ApiBase::GET_VALUES_FOR_HELP ],
                ];

                foreach ( $paths as $path ) {
                        foreach ( $argsets as $argset => $args ) {
                                // NOTE: Retrieving the module parameters here may have side effects such as DB queries that
                                // should be avoided in data providers (T341731). So do that in the test method instead.
                                yield "Module $path, argset $argset" => [ $path, $argset, $args, $main ];
                        }
                }
        }

        /**
         * Return paths of all submodules in an ApiModuleManager, recursively
         * @param ApiModuleManager $manager
         * @return string[]
         */
        protected static function getSubModulePaths( ApiModuleManager $manager ) {
                $paths = [];
                foreach ( $manager->getNames() as $name ) {
                        $module = $manager->getModule( $name );
                        $paths[] = $module->getModulePath();
                        $subManager = $module->getModuleManager();
                        if ( $subManager ) {
                                $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
                        }
                }
                return $paths;
        }
}