tests/phpunit/structure/ApiStructureTest.php

   1 <?php
   2
   3 use Wikimedia\TestingAccessWrapper;
   4
   5 /**
   6  * Checks that all API modules, core and extensions, conform to the conventions:
   7  * - have documentation i18n messages (the test won't catch everything since
   8  *   i18n messages can vary based on the wiki configuration, but it should
   9  *   catch many cases for forgotten i18n)
  10  * - do not have inconsistencies in the parameter definitions
  11  *
  12  * @group API
  13  */
  14 class ApiStructureTest extends MediaWikiTestCase {
  15
  16         /** @var ApiMain */
  17         private static $main;
  18
  19         /** @var array Sets of globals to test. Each array element is input to HashConfig */
  20         private static $testGlobals = [
  21                 [
  22                         'MiserMode' => false,
  23                         'AllowCategorizedRecentChanges' => false,
  24                 ],
  25                 [
  26                         'MiserMode' => true,
  27                         'AllowCategorizedRecentChanges' => true,
  28                 ],
  29         ];
  30
  31         /**
  32          * Initialize/fetch the ApiMain instance for testing
  33          * @return ApiMain
  34          */
  35         private static function getMain() {
  36                 if ( !self::$main ) {
  37                         self::$main = new ApiMain( RequestContext::getMain() );
  38                         self::$main->getContext()->setLanguage( 'en' );
  39                         self::$main->getContext()->setTitle(
  40                                 Title::makeTitle( NS_SPECIAL, 'Badtitle/dummy title for ApiStructureTest' )
  41                         );
  42                 }
  43                 return self::$main;
  44         }
  45
  46         /**
  47          * Test a message
  48          * @param Message $msg
  49          * @param string $what Which message is being checked
  50          */
  51         private function checkMessage( $msg, $what ) {
  52                 $msg = ApiBase::makeMessage( $msg, self::getMain()->getContext() );
  53                 $this->assertInstanceOf( Message::class, $msg, "$what message" );
  54                 $this->assertTrue( $msg->exists(), "$what message {$msg->getKey()} exists" );
  55         }
  56
  57         /**
  58          * @dataProvider provideDocumentationExists
  59          * @param string $path Module path
  60          * @param array $globals Globals to set
  61          */
  62         public function testDocumentationExists( $path, array $globals ) {
  63                 $main = self::getMain();
  64
  65                 // Set configuration variables
  66                 $main->getContext()->setConfig( new MultiConfig( [
  67                         new HashConfig( $globals ),
  68                         RequestContext::getMain()->getConfig(),
  69                 ] ) );
  70                 foreach ( $globals as $k => $v ) {
  71                         $this->setMwGlobals( "wg$k", $v );
  72                 }
  73
  74                 // Fetch module.
  75                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
  76
  77                 // Test messages for flags.
  78                 foreach ( $module->getHelpFlags() as $flag ) {
  79                         $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
  80                 }
  81
  82                 // Module description messages.
  83                 $this->checkMessage( $module->getSummaryMessage(), 'Module summary' );
  84                 $this->checkMessage( $module->getExtendedDescription(), 'Module help top text' );
  85
  86                 // Parameters. Lots of messages in here.
  87                 $params = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
  88                 $tags = [];
  89                 foreach ( $params as $name => $settings ) {
  90                         if ( !is_array( $settings ) ) {
  91                                 $settings = [];
  92                         }
  93
  94                         // Basic description message
  95                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG] ) ) {
  96                                 $msg = $settings[ApiBase::PARAM_HELP_MSG];
  97                         } else {
  98                                 $msg = "apihelp-{$path}-param-{$name}";
  99                         }
 100                         $this->checkMessage( $msg, "Parameter $name description" );
 101
 102                         // If param-per-value is in use, each value's message
 103                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE] ) ) {
 104                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE],
 105                                         "Parameter $name PARAM_HELP_MSG_PER_VALUE is array" );
 106                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_TYPE],
 107                                         "Parameter $name PARAM_TYPE is array for msg-per-value mode" );
 108                                 $valueMsgs = $settings[ApiBase::PARAM_HELP_MSG_PER_VALUE];
 109                                 foreach ( $settings[ApiBase::PARAM_TYPE] as $value ) {
 110                                         if ( isset( $valueMsgs[$value] ) ) {
 111                                                 $msg = $valueMsgs[$value];
 112                                         } else {
 113                                                 $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
 114                                         }
 115                                         $this->checkMessage( $msg, "Parameter $name value $value" );
 116                                 }
 117                         }
 118
 119                         // Appended messages (e.g. "disabled in miser mode")
 120                         if ( isset( $settings[ApiBase::PARAM_HELP_MSG_APPEND] ) ) {
 121                                 $this->assertInternalType( 'array', $settings[ApiBase::PARAM_HELP_MSG_APPEND],
 122                                         "Parameter $name PARAM_HELP_MSG_APPEND is array" );
 123                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_APPEND] as $i => $msg ) {
 124                                         $this->checkMessage( $msg, "Parameter $name HELP_MSG_APPEND #$i" );
 125                                 }
 126                         }
 127
 128                         // Info tags (e.g. "only usable in mode 1") are typically shared by
 129                         // several parameters, so accumulate them and test them later.
 130                         if ( !empty( $settings[ApiBase::PARAM_HELP_MSG_INFO] ) ) {
 131                                 foreach ( $settings[ApiBase::PARAM_HELP_MSG_INFO] as $i ) {
 132                                         $tags[array_shift( $i )] = 1;
 133                                 }
 134                         }
 135                 }
 136
 137                 // Info tags (e.g. "only usable in mode 1") accumulated above
 138                 foreach ( $tags as $tag => $dummy ) {
 139                         $this->checkMessage( "apihelp-{$path}-paraminfo-{$tag}", "HELP_MSG_INFO tag $tag" );
 140                 }
 141
 142                 // Messages for examples.
 143                 foreach ( $module->getExamplesMessages() as $qs => $msg ) {
 144                         $this->assertStringStartsNotWith( 'api.php?', $qs,
 145                                 "Query string must not begin with 'api.php?'" );
 146                         $this->checkMessage( $msg, "Example $qs" );
 147                 }
 148         }
 149
 150         public static function provideDocumentationExists() {
 151                 $main = self::getMain();
 152                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 153                 array_unshift( $paths, $main->getModulePath() );
 154
 155                 $ret = [];
 156                 foreach ( $paths as $path ) {
 157                         foreach ( self::$testGlobals as $globals ) {
 158                                 $g = [];
 159                                 foreach ( $globals as $k => $v ) {
 160                                         $g[] = "$k=" . var_export( $v, 1 );
 161                                 }
 162                                 $k = "Module $path with " . implode( ', ', $g );
 163                                 $ret[$k] = [ $path, $globals ];
 164                         }
 165                 }
 166                 return $ret;
 167         }
 168
 169         /**
 170          * @dataProvider provideParameterConsistency
 171          * @param string $path
 172          */
 173         public function testParameterConsistency( $path ) {
 174                 $main = self::getMain();
 175                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
 176
 177                 $paramsPlain = $module->getFinalParams();
 178                 $paramsForHelp = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
 179
 180                 // avoid warnings about empty tests when no parameter needs to be checked
 181                 $this->assertTrue( true );
 182
 183                 foreach ( [ $paramsPlain, $paramsForHelp ] as $params ) {
 184                         foreach ( $params as $param => $config ) {
 185                                 if ( isset( $config[ApiBase::PARAM_ISMULTI_LIMIT1] )
 186                                         || isset( $config[ApiBase::PARAM_ISMULTI_LIMIT2] )
 187                                 ) {
 188                                         $this->assertTrue( !empty( $config[ApiBase::PARAM_ISMULTI] ), $param
 189                                                 . ': PARAM_ISMULTI_LIMIT* only makes sense when PARAM_ISMULTI is true' );
 190                                         $this->assertTrue( isset( $config[ApiBase::PARAM_ISMULTI_LIMIT1] )
 191                                                 && isset( $config[ApiBase::PARAM_ISMULTI_LIMIT2] ), $param
 192                                                 . ': PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2 must be used together' );
 193                                         $this->assertType( 'int', $config[ApiBase::PARAM_ISMULTI_LIMIT1], $param
 194                                                 . 'PARAM_ISMULTI_LIMIT1 must be an integer' );
 195                                         $this->assertType( 'int', $config[ApiBase::PARAM_ISMULTI_LIMIT2], $param
 196                                                 . 'PARAM_ISMULTI_LIMIT2 must be an integer' );
 197                                         $this->assertGreaterThanOrEqual( $config[ApiBase::PARAM_ISMULTI_LIMIT1],
 198                                                 $config[ApiBase::PARAM_ISMULTI_LIMIT2], $param
 199                                                 . 'PARAM_ISMULTI limit cannot be smaller for users with apihighlimits rights' );
 200                                 }
 201                                 if ( isset( $config[ApiBase::PARAM_MAX_BYTES] )
 202                                         || isset( $config[ApiBase::PARAM_MAX_CHARS] )
 203                                 ) {
 204                                         $default = isset( $config[ApiBase::PARAM_DFLT] ) ? $config[ApiBase::PARAM_DFLT] : null;
 205                                         $type = isset( $config[ApiBase::PARAM_TYPE] ) ? $config[ApiBase::PARAM_TYPE]
 206                                                 : gettype( $default );
 207                                         $this->assertContains( $type, [ 'NULL', 'string', 'text', 'password' ],
 208                                                 'PARAM_MAX_BYTES/CHARS is only supported for string-like types' );
 209                                 }
 210                         }
 211                 }
 212         }
 213
 214         /**
 215          * @return array List of API module paths to test
 216          */
 217         public static function provideParameterConsistency() {
 218                 $main = self::getMain();
 219                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 220                 array_unshift( $paths, $main->getModulePath() );
 221
 222                 $ret = [];
 223                 foreach ( $paths as $path ) {
 224                         $ret[] = [ $path ];
 225                 }
 226                 return $ret;
 227         }
 228
 229         /**
 230          * Return paths of all submodules in an ApiModuleManager, recursively
 231          * @param ApiModuleManager $manager
 232          * @return string[]
 233          */
 234         protected static function getSubModulePaths( ApiModuleManager $manager ) {
 235                 $paths = [];
 236                 foreach ( $manager->getNames() as $name ) {
 237                         $module = $manager->getModule( $name );
 238                         $paths[] = $module->getModulePath();
 239                         $subManager = $module->getModuleManager();
 240                         if ( $subManager ) {
 241                                 $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
 242                         }
 243                 }
 244                 return $paths;
 245         }
 246 }