tests/phpunit/structure/ApiDocumentationTest.php

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