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->getSummaryMessage(), 'Module summary' );
  83                 $this->checkMessage( $module->getExtendedDescription(), 'Module help top text' );
  84
  85                 // Parameters. Lots of messages in here.
  86                 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
  87                 $tags = [];
  88                 foreach ( $params as $name => $settings ) {
  89                         if ( !is_array( $settings ) ) {
  90                                 $settings = [];
  91                         }
  92
  93                         // Basic description message
  94                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
  95                                 $msg = $settings[ApiBase::PARAM_HELP_MSG];
  96                         } else {
  97                                 $msg = "apihelp-{$path}-param-{$name}";
  98                         }
  99                         $this->checkMessage( $msg, "Parameter $name description" );
 100
 101                         // If param-per-value is in use, each value's message
 102                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
 103                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE],
 104                                         "Parameter $name PARAM_HELP_MSG_PER_VALUE is array" );
 105                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_TYPE],
 106                                         "Parameter $name PARAM_TYPE is array for msg-per-value mode" );
 107                                 $valueMsgs = $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE];
 108                                 foreach ( $settings[ApiBase::PARAM_TYPE] as $value ) {
 109                                         if ( isset( $valueMsgs[$value] ) ) {
 110                                                 $msg = $valueMsgs[$value];
 111                                         } else {
 112                                                 $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
 113                                         }
 114                                         $this->checkMessage( $msg, "Parameter $name value $value" );
 115                                 }
 116                         }
 117
 118                         // Appended messages (e.g. "disabled in miser mode")
 119                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
 120                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_APPEND],
 121                                         "Parameter $name PARAM_HELP_MSG_APPEND is array" );
 122                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $i => $msg ) {
 123                                         $this->checkMessage( $msg, "Parameter $name HELP_MSG_APPEND #$i" );
 124                                 }
 125                         }
 126
 127                         // Info tags (e.g. "only usable in mode 1") are typically shared by
 128                         // several parameters, so accumulate them and test them later.
 129                         if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
 130                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
 131                                         $tags[array_shift( $i )] = 1;
 132                                 }
 133                         }
 134                 }
 135
 136                 // Info tags (e.g. "only usable in mode 1") accumulated above
 137                 foreach ( $tags as $tag => $dummy ) {
 138                         $this->checkMessage( "apihelp-{$path}-paraminfo-{$tag}", "HELP_MSG_INFO tag $tag" );
 139                 }
 140
 141                 // Messages for examples.
 142                 foreach ( $module->getExamplesMessages() as $qs => $msg ) {
 143                         $this->assertStringStartsNotWith( 'api.php?', $qs,
 144                                 "Query string must not begin with 'api.php?'" );
 145                         $this->checkMessage( $msg, "Example $qs" );
 146                 }
 147         }
 148
 149         public static function provideDocumentationExists() {
 150                 $main = self::getMain();
 151                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 152                 array_unshift( $paths, $main->getModulePath() );
 153
 154                 $ret = [];
 155                 foreach ( $paths as $path ) {
 156                         foreach ( self::$testGlobals as $globals ) {
 157                                 $g = [];
 158                                 foreach ( $globals as $k => $v ) {
 159                                         $g[] = "$k=" . var_export( $v, 1 );
 160                                 }
 161                                 $k = "Module $path with " . implode( ', ', $g );
 162                                 $ret[$k] = [ $path, $globals ];
 163                         }
 164                 }
 165                 return $ret;
 166         }
 167
 168         /**
 169          * Return paths of all submodules in an ApiModuleManager, recursively
 170          * @param ApiModuleManager $manager
 171          * @return string[]
 172          */
 173         protected static function getSubModulePaths( ApiModuleManager $manager ) {
 174                 $paths = [];
 175                 foreach ( $manager->getNames() as $name ) {
 176                         $module = $manager->getModule( $name );
 177                         $paths[] = $module->getModulePath();
 178                         $subManager = $module->getModuleManager();
 179                         if ( $subManager ) {
 180                                 $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
 181                         }
 182                 }
 183                 return $paths;
 184         }
 185 }