tests/phpunit/structure/ApiDocumentationTest.php

   1 <?php
   2
   3 /**
   4  * Checks that all API modules, core and extensions, have documentation i18n messages
   5  *
   6  * It won't catch everything since i18n messages can vary based on the wiki
   7  * configuration, but it should catch many cases for forgotten i18n.
   8  *
   9  * @group API
  10  */
  11 class ApiDocumentationTest extends MediaWikiTestCase {
  12
  13         /** @var ApiMain */
  14         private static $main;
  15
  16         /** @var array Sets of globals to test. Each array element is input to HashConfig */
  17         private static $testGlobals = [
  18                 [
  19                         'MiserMode' => false,
  20                         'AllowCategorizedRecentChanges' => false,
  21                 ],
  22                 [
  23                         'MiserMode' => true,
  24                         'AllowCategorizedRecentChanges' => true,
  25                 ],
  26         ];
  27
  28         /**
  29          * Initialize/fetch the ApiMain instance for testing
  30          * @return ApiMain
  31          */
  32         private static function getMain() {
  33                 if ( !self::$main ) {
  34                         self::$main = new ApiMain( RequestContext::getMain() );
  35                         self::$main->getContext()->setLanguage( 'en' );
  36                         self::$main->getContext()->setTitle(
  37                                 Title::makeTitle( NS_SPECIAL, 'Badtitle/dummy title for ApiDocumentationTest' )
  38                         );
  39                 }
  40                 return self::$main;
  41         }
  42
  43         /**
  44          * Test a message
  45          * @param Message $msg
  46          * @param string $what Which message is being checked
  47          */
  48         private function checkMessage( $msg, $what ) {
  49                 $msg = ApiBase::makeMessage( $msg, self::getMain()->getContext() );
  50                 $this->assertInstanceOf( 'Message', $msg, "$what message" );
  51                 $this->assertTrue( $msg->exists(), "$what message {$msg->getKey()} exists" );
  52         }
  53
  54         /**
  55          * @dataProvider provideDocumentationExists
  56          * @param string $path Module path
  57          * @param array $globals Globals to set
  58          */
  59         public function testDocumentationExists( $path, array $globals ) {
  60                 $main = self::getMain();
  61
  62                 // Set configuration variables
  63                 $main->getContext()->setConfig( new MultiConfig( [
  64                         new HashConfig( $globals ),
  65                         RequestContext::getMain()->getConfig(),
  66                 ] ) );
  67                 foreach ( $globals as $k => $v ) {
  68                         $this->setMwGlobals( "wg$k", $v );
  69                 }
  70
  71                 // Fetch module.
  72                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
  73
  74                 // Test messages for flags.
  75                 foreach ( $module->getHelpFlags() as $flag ) {
  76                         $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
  77                 }
  78
  79                 // Module description messages.
  80                 $this->checkMessage( $module->getDescriptionMessage(), 'Module description' );
  81
  82                 // Parameters. Lots of messages in here.
  83                 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
  84                 $tags = [];
  85                 foreach ( $params as $name => $settings ) {
  86                         if ( !is_array( $settings ) ) {
  87                                 $settings = [];
  88                         }
  89
  90                         // Basic description message
  91                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
  92                                 $msg = $settings[ApiBase::PARAM_HELP_MSG];
  93                         } else {
  94                                 $msg = "apihelp-{$path}-param-{$name}";
  95                         }
  96                         $this->checkMessage( $msg, "Parameter $name description" );
  97
  98                         // If param-per-value is in use, each value's message
  99                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
 100                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE],
 101                                         "Parameter $name PARAM_HELP_MSG_PER_VALUE is array" );
 102                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_TYPE],
 103                                         "Parameter $name PARAM_TYPE is array for msg-per-value mode" );
 104                                 $valueMsgs = $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE];
 105                                 foreach ( $settings[ApiBase::PARAM_TYPE] as $value ) {
 106                                         if ( isset( $valueMsgs[$value] ) ) {
 107                                                 $msg = $valueMsgs[$value];
 108                                         } else {
 109                                                 $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
 110                                         }
 111                                         $this->checkMessage( $msg, "Parameter $name value $value" );
 112                                 }
 113                         }
 114
 115                         // Appended messages (e.g. "disabled in miser mode")
 116                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
 117                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_APPEND],
 118                                         "Parameter $name PARAM_HELP_MSG_APPEND is array" );
 119                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $i => $msg ) {
 120                                         $this->checkMessage( $msg, "Parameter $name HELP_MSG_APPEND #$i" );
 121                                 }
 122                         }
 123
 124                         // Info tags (e.g. "only usable in mode 1") are typically shared by
 125                         // several parameters, so accumulate them and test them later.
 126                         if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
 127                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
 128                                         $tags[array_shift( $i )] = 1;
 129                                 }
 130                         }
 131                 }
 132
 133                 // Info tags (e.g. "only usable in mode 1") accumulated above
 134                 foreach ( $tags as $tag => $dummy ) {
 135                         $this->checkMessage( "apihelp-{$path}-paraminfo-{$tag}", "HELP_MSG_INFO tag $tag" );
 136                 }
 137
 138                 // Messages for examples.
 139                 foreach ( $module->getExamplesMessages() as $qs => $msg ) {
 140                         $this->assertStringStartsNotWith( 'api.php?', $qs,
 141                                 "Query string must not begin with 'api.php?'" );
 142                         $this->checkMessage( $msg, "Example $qs" );
 143                 }
 144         }
 145
 146         public static function provideDocumentationExists() {
 147                 $main = self::getMain();
 148                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 149                 array_unshift( $paths, $main->getModulePath() );
 150
 151                 $ret = [];
 152                 foreach ( $paths as $path ) {
 153                         foreach ( self::$testGlobals as $globals ) {
 154                                 $g = [];
 155                                 foreach ( $globals as $k => $v ) {
 156                                         $g[] = "$k=" . var_export( $v, 1 );
 157                                 }
 158                                 $k = "Module $path with " . implode( ', ', $g );
 159                                 $ret[$k] = [ $path, $globals ];
 160                         }
 161                 }
 162                 return $ret;
 163         }
 164
 165         /**
 166          * Return paths of all submodules in an ApiModuleManager, recursively
 167          * @param ApiModuleManager $manager
 168          * @return string[]
 169          */
 170         protected static function getSubModulePaths( ApiModuleManager $manager ) {
 171                 $paths = [];
 172                 foreach ( $manager->getNames() as $name ) {
 173                         $module = $manager->getModule( $name );
 174                         $paths[] = $module->getModulePath();
 175                         $subManager = $module->getModuleManager();
 176                         if ( $subManager ) {
 177                                 $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
 178                         }
 179                 }
 180                 return $paths;
 181         }
 182 }