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                 ],
  24                 [
  25                         'MiserMode' => true,
  26                 ],
  27         ];
  28
  29         /**
  30          * Initialize/fetch the ApiMain instance for testing
  31          * @return ApiMain
  32          */
  33         private static function getMain() {
  34                 if ( !self::$main ) {
  35                         self::$main = new ApiMain( RequestContext::getMain() );
  36                         self::$main->getContext()->setLanguage( 'en' );
  37                         self::$main->getContext()->setTitle(
  38                                 Title::makeTitle( NS_SPECIAL, 'Badtitle/dummy title for ApiStructureTest' )
  39                         );
  40                 }
  41                 return self::$main;
  42         }
  43
  44         /**
  45          * Test a message
  46          * @param Message $msg
  47          * @param string $what Which message is being checked
  48          */
  49         private function checkMessage( $msg, $what ) {
  50                 $msg = ApiBase::makeMessage( $msg, self::getMain()->getContext() );
  51                 $this->assertInstanceOf( Message::class, $msg, "$what message" );
  52                 $this->assertTrue( $msg->exists(), "$what message {$msg->getKey()} exists" );
  53         }
  54
  55         /**
  56          * @dataProvider provideDocumentationExists
  57          * @param string $path Module path
  58          * @param array $globals Globals to set
  59          */
  60         public function testDocumentationExists( $path, array $globals ) {
  61                 $main = self::getMain();
  62
  63                 // Set configuration variables
  64                 $main->getContext()->setConfig( new MultiConfig( [
  65                         new HashConfig( $globals ),
  66                         RequestContext::getMain()->getConfig(),
  67                 ] ) );
  68                 foreach ( $globals as $k => $v ) {
  69                         $this->setMwGlobals( "wg$k", $v );
  70                 }
  71
  72                 // Fetch module.
  73                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
  74
  75                 // Test messages for flags.
  76                 foreach ( $module->getHelpFlags() as $flag ) {
  77                         $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
  78                 }
  79
  80                 // Module description messages.
  81                 $this->checkMessage( $module->getSummaryMessage(), 'Module summary' );
  82                 $this->checkMessage( $module->getExtendedDescription(), 'Module help top text' );
  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          * @dataProvider provideParameterConsistency
 169          * @param string $path
 170          */
 171         public function testParameterConsistency( $path ) {
 172                 $main = self::getMain();
 173                 $module = TestingAccessWrapper::newFromObject( $main->getModuleFromPath( $path ) );
 174
 175                 $paramsPlain = $module->getFinalParams();
 176                 $paramsForHelp = $module->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
 177
 178                 // avoid warnings about empty tests when no parameter needs to be checked
 179                 $this->assertTrue( true );
 180
 181                 foreach ( [ $paramsPlain, $paramsForHelp ] as $params ) {
 182                         foreach ( $params as $param => $config ) {
 183                                 if ( isset( $config[ApiBase::PARAM_ISMULTI_LIMIT1] )
 184                                         || isset( $config[ApiBase::PARAM_ISMULTI_LIMIT2] )
 185                                 ) {
 186                                         $this->assertTrue( !empty( $config[ApiBase::PARAM_ISMULTI] ), $param
 187                                                 . ': PARAM_ISMULTI_LIMIT* only makes sense when PARAM_ISMULTI is true' );
 188                                         $this->assertTrue( isset( $config[ApiBase::PARAM_ISMULTI_LIMIT1] )
 189                                                 && isset( $config[ApiBase::PARAM_ISMULTI_LIMIT2] ), $param
 190                                                 . ': PARAM_ISMULTI_LIMIT1 and PARAM_ISMULTI_LIMIT2 must be used together' );
 191                                         $this->assertType( 'int', $config[ApiBase::PARAM_ISMULTI_LIMIT1], $param
 192                                                 . 'PARAM_ISMULTI_LIMIT1 must be an integer' );
 193                                         $this->assertType( 'int', $config[ApiBase::PARAM_ISMULTI_LIMIT2], $param
 194                                                 . 'PARAM_ISMULTI_LIMIT2 must be an integer' );
 195                                         $this->assertGreaterThanOrEqual( $config[ApiBase::PARAM_ISMULTI_LIMIT1],
 196                                                 $config[ApiBase::PARAM_ISMULTI_LIMIT2], $param
 197                                                 . 'PARAM_ISMULTI limit cannot be smaller for users with apihighlimits rights' );
 198                                 }
 199                                 if ( isset( $config[ApiBase::PARAM_MAX_BYTES] )
 200                                         || isset( $config[ApiBase::PARAM_MAX_CHARS] )
 201                                 ) {
 202                                         $default = isset( $config[ApiBase::PARAM_DFLT] ) ? $config[ApiBase::PARAM_DFLT] : null;
 203                                         $type = isset( $config[ApiBase::PARAM_TYPE] ) ? $config[ApiBase::PARAM_TYPE]
 204                                                 : gettype( $default );
 205                                         $this->assertContains( $type, [ 'NULL', 'string', 'text', 'password' ],
 206                                                 'PARAM_MAX_BYTES/CHARS is only supported for string-like types' );
 207                                 }
 208                         }
 209                 }
 210         }
 211
 212         /**
 213          * @return array List of API module paths to test
 214          */
 215         public static function provideParameterConsistency() {
 216                 $main = self::getMain();
 217                 $paths = self::getSubModulePaths( $main->getModuleManager() );
 218                 array_unshift( $paths, $main->getModulePath() );
 219
 220                 $ret = [];
 221                 foreach ( $paths as $path ) {
 222                         $ret[] = [ $path ];
 223                 }
 224                 return $ret;
 225         }
 226
 227         /**
 228          * Return paths of all submodules in an ApiModuleManager, recursively
 229          * @param ApiModuleManager $manager
 230          * @return string[]
 231          */
 232         protected static function getSubModulePaths( ApiModuleManager $manager ) {
 233                 $paths = [];
 234                 foreach ( $manager->getNames() as $name ) {
 235                         $module = $manager->getModule( $name );
 236                         $paths[] = $module->getModulePath();
 237                         $subManager = $module->getModuleManager();
 238                         if ( $subManager ) {
 239                                 $paths = array_merge( $paths, self::getSubModulePaths( $subManager ) );
 240                         }
 241                 }
 242                 return $paths;
 243         }
 244 }