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 = array(
  18                 array(
  19                         'MiserMode' => false,
  20                         'AllowCategorizedRecentChanges' => false,
  21                 ),
  22                 array(
  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                 }
  37                 return self::$main;
  38         }
  39
  40         /**
  41          * Test a message
  42          * @param Message $msg
  43          * @param string $what Which message is being checked
  44          */
  45         private function checkMessage( $msg, $what ) {
  46                 $msg = ApiBase::makeMessage( $msg, self::getMain()->getContext() );
  47                 $this->assertInstanceOf( 'Message', $msg, "$what message" );
  48                 $this->assertTrue( $msg->exists(), "$what message {$msg->getKey()} exists" );
  49         }
  50
  51         /**
  52          * @dataProvider provideDocumentationExists
  53          * @param string $path Module path
  54          * @param array $globals Globals to set
  55          */
  56         public function testDocumentationExists( $path, array $globals ) {
  57                 $main = self::getMain();
  58
  59                 // Set configuration variables
  60                 $main->getContext()->setConfig( new MultiConfig( array(
  61                         new HashConfig( $globals ),
  62                         RequestContext::getMain()->getConfig(),
  63                 ) ) );
  64                 foreach ( $globals as $k => $v ) {
  65                         $this->setMWGlobals( "wg$k", $v );
  66                 }
  67
  68                 // Fetch module.
  69                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
  70
  71                 // Test messages for flags.
  72                 foreach ( $module->getHelpFlags() as $flag ) {
  73                         $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
  74                 }
  75
  76                 // Module description messages.
  77                 $this->checkMessage( $module->getDescriptionMessage(), 'Module description' );
  78
  79                 // Parameters. Lots of messages in here.
  80                 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
  81                 $tags = array();
  82                 foreach ( $params as $name => $settings ) {
  83                         if ( !is_array( $settings ) ) {
  84                                 $settings = array();
  85                         }
  86
  87                         // Basic description message
  88                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
  89                                 $msg = $settings[ApiBase::PARAM_HELP_MSG];
  90                         } else {
  91                                 $msg = "apihelp-{$path}-param-{$name}";
  92                         }
  93                         $this->checkMessage( $msg, "Parameter $name description" );
  94
  95                         // If param-per-value is in use, each value's message
  96                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
  97                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE],
  98                                         "Parameter $name PARAM_HELP_MSG_PER_VALUE is array" );
  99                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_TYPE],
 100                                         "Parameter $name PARAM_TYPE is array for msg-per-value mode" );
 101                                 $valueMsgs = $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE];
 102                                 foreach ( $settings[ApiBase::PARAM_TYPE] as $value ) {
 103                                         if ( isset( $valueMsgs[$value] ) ) {
 104                                                 $msg = $valueMsgs[$value];
 105                                         } else {
 106                                                 $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
 107                                         }
 108                                         $this->checkMessage( $msg, "Parameter $name value $value" );
 109                                 }
 110                         }
 111
 112                         // Appended messages (e.g. "disabled in miser mode")
 113                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
 114                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_APPEND],
 115                                         "Parameter $name PARAM_HELP_MSG_APPEND is array" );
 116                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $i => $msg ) {
 117                                         $this->checkMessage( $msg, "Parameter $name HELP_MSG_APPEND #$i" );
 118                                 }
 119                         }
 120
 121                         // Info tags (e.g. "only usable in mode 1") are typically shared by
 122                         // several parameters, so accumulate them and test them later.
 123                         if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
 124                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
 125                                         $tags[array_shift( $i )] = 1;
 126                                 }
 127                         }
 128                 }
 129
 130                 // Info tags (e.g. "only usable in mode 1") accumulated above
 131                 foreach ( $tags as $tag => $dummy ) {
 132                         $this->checkMessage( "apihelp-{$path}-paraminfo-{$tag}", "HELP_MSG_INFO tag $tag" );
 133                 }
 134
 135                 // Messages for examples.
 136                 foreach ( $module->getExamplesMessages() as $qs => $msg ) {
 137                         $this->checkMessage( $msg, "Example $qs" );
 138                 }
 139         }
 140
 141         public static function provideDocumentationExists() {
 142                 $main = self::getMain();
 143                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 144                 array_unshift( $paths, $main->getModulePath() );
 145
 146                 $ret = array();
 147                 foreach ( $paths as $path ) {
 148                         foreach ( self::$testGlobals as $globals ) {
 149                                 $g = array();
 150                                 foreach ( $globals as $k => $v ) {
 151                                         $g[] = "$k=" . var_export( $v, 1 );
 152                                 }
 153                                 $k = "Module $path with " . join( ', ', $g );
 154                                 $ret[$k] = array( $path, $globals );
 155                         }
 156                 }
 157                 return $ret;
 158         }
 159
 160         /**
 161          * Return paths of all submodules in an ApiModuleManager, recursively
 162          * @param ApiModuleManager $manager
 163          * @return string[]
 164          */
 165         protected static function getSubModulePaths( ApiModuleManager $manager ) {
 166                 $paths = array();
 167                 foreach ( $manager->getNames() as $name ) {
 168                         $module = $manager->getModule( $name );
 169                         $paths[] = $module->getModulePath();
 170                         $subManager = $module->getModuleManager();
 171                         if ( $subManager ) {
 172                                 $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
 173                         }
 174                 }
 175                 return $paths;
 176         }
 177 }