3 use Wikimedia\TestingAccessWrapper
;
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
14 class ApiStructureTest
extends MediaWikiTestCase
{
19 /** @var array Sets of globals to test. Each array element is input to HashConfig */
20 private static $testGlobals = [
30 * Initialize/fetch the ApiMain instance for testing
33 private static function getMain() {
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' )
47 * @param string $what Which message is being checked
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" );
56 * @dataProvider provideDocumentationExists
57 * @param string $path Module path
58 * @param array $globals Globals to set
60 public function testDocumentationExists( $path, array $globals ) {
61 $main = self
::getMain();
63 // Set configuration variables
64 $main->getContext()->setConfig( new MultiConfig( [
65 new HashConfig( $globals ),
66 RequestContext
::getMain()->getConfig(),
68 foreach ( $globals as $k => $v ) {
69 $this->setMwGlobals( "wg$k", $v );
73 $module = TestingAccessWrapper
::newFromObject( $main->getModuleFromPath( $path ) );
75 // Test messages for flags.
76 foreach ( $module->getHelpFlags() as $flag ) {
77 $this->checkMessage( "api-help-flag-$flag", "Flag $flag" );
80 // Module description messages.
81 $this->checkMessage( $module->getSummaryMessage(), 'Module summary' );
82 $this->checkMessage( $module->getExtendedDescription(), 'Module help top text' );
84 // Parameters. Lots of messages in here.
85 $params = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
87 foreach ( $params as $name => $settings ) {
88 if ( !is_array( $settings ) ) {
92 // Basic description message
93 if ( isset( $settings[ApiBase
::PARAM_HELP_MSG
] ) ) {
94 $msg = $settings[ApiBase
::PARAM_HELP_MSG
];
96 $msg = "apihelp-{$path}-param-{$name}";
98 $this->checkMessage( $msg, "Parameter $name description" );
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];
111 $msg = "apihelp-{$path}-paramvalue-{$name}-{$value}";
113 $this->checkMessage( $msg, "Parameter $name value $value" );
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" );
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;
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" );
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" );
148 public static function provideDocumentationExists() {
149 $main = self
::getMain();
150 $paths = self
::getSubModulePaths( $main->getModuleManager() );
151 array_unshift( $paths, $main->getModulePath() );
154 foreach ( $paths as $path ) {
155 foreach ( self
::$testGlobals as $globals ) {
157 foreach ( $globals as $k => $v ) {
158 $g[] = "$k=" . var_export( $v, 1 );
160 $k = "Module $path with " . implode( ', ', $g );
161 $ret[$k] = [ $path, $globals ];
168 * @dataProvider provideParameterConsistency
169 * @param string $path
171 public function testParameterConsistency( $path ) {
172 $main = self
::getMain();
173 $module = TestingAccessWrapper
::newFromObject( $main->getModuleFromPath( $path ) );
175 $paramsPlain = $module->getFinalParams();
176 $paramsForHelp = $module->getFinalParams( ApiBase
::GET_VALUES_FOR_HELP
);
178 // avoid warnings about empty tests when no parameter needs to be checked
179 $this->assertTrue( true );
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
] )
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' );
199 if ( isset( $config[ApiBase
::PARAM_MAX_BYTES
] )
200 ||
isset( $config[ApiBase
::PARAM_MAX_CHARS
] )
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' );
213 * @return array List of API module paths to test
215 public static function provideParameterConsistency() {
216 $main = self
::getMain();
217 $paths = self
::getSubModulePaths( $main->getModuleManager() );
218 array_unshift( $paths, $main->getModulePath() );
221 foreach ( $paths as $path ) {
228 * Return paths of all submodules in an ApiModuleManager, recursively
229 * @param ApiModuleManager $manager
232 protected static function getSubModulePaths( ApiModuleManager
$manager ) {
234 foreach ( $manager->getNames() as $name ) {
235 $module = $manager->getModule( $name );
236 $paths[] = $module->getModulePath();
237 $subManager = $module->getModuleManager();
239 $paths = array_merge( $paths, self
::getSubModulePaths( $subManager ) );