Issue 932 - improve docs about JSONScript

tests/phpunit/Integration/JSONScript/README.md

@@ -1,9 +1,28 @@
+## How to update List of tests
+
+The `readmeContentsBuilder.php` script can be used to update the list of available test cases, including their descriptions.
+
+To use this script, navigate to the following directory in your project:
+- `extensions/SemanticResultFormats/tests/phpunit/Integration/JSONScript/`
+
+Once there, run the script using PHP with the following command:
+- `php ReadmeContentsBuilder.php`
+
+The script will automatically fetch the test cases, update the `README.md` file, and ensure that the list of tests is up to date with any changes made in the test case files.
+It will also generate the descriptions for each test based on the contents of the corresponding JSON files.
 
 <!-- Begin of generated contents by readmeContentsBuilder.php -->
 
-## TestCases
+## List of tests
 
-Contains 21 files with a total of 62 tests:
+- Files: 33 (includes 131 tests)
+- Last update: 2025-04-01
+
+### B
+* [bibtex-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/bibtex-01.json) Test `format=bibtex`
+
+### C
+* [carousel-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/carousel-01.json) Test `format=carousel` html output (no JS validation)
 
 ### D
 * [datatables-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/datatables-01.json) Test `format=datatables` html output (no JS validation)
@@ -15,9 +34,13 @@ Contains 21 files with a total of 62 tests:
 ### F
 * [filtered-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/filtered-01.json) Filtered format: ...
 * [filtered-02.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/filtered-02.json) Filtered format: ...
+* [filtered-03.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/filtered-03.json) Filtered format: List view tests
 
 ### G
 * [gallery-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/gallery-01.json) Test `format=gallery` with file upload
+* [gallery-02.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/gallery-02.json) Test `format=gallery` with file upload and captiontemplate
+* [gallery-03.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/gallery-03.json) Test `format=gallery` with different different parameters like widget, redirects, overlay
+* [gantt-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/gantt-01.json) Test the gantt format
 
 ### I
 * [icalendar-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/icalendar-01.json) Test `format=icalendar`
@@ -26,12 +49,19 @@ Contains 21 files with a total of 62 tests:
 
 ### L
 * [latest-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/latest-01.json) Test for `format=latest`
+* [listwidget-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/listwidget-01.json) Listwidget format: widgets - unordered (#449 - `wgContLang=fr`, `wgLang=en`)
 
 ### M
 * [math-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/math-01.json) Test for math/sum result format in pt-br lang
+* [media-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/media-01.json) Test `format=media` with file upload
+
+### O
+* [outline-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/outline-01.json) Test `format=outline` template output
+* [outline-02.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/outline-02.json) Test `format=outline` list output
 
 ### T
 * [tagcloud-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/tagcloud-01.json) Test `format=tagcloud` html output
+* [tagcloud-02.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/tagcloud-02.json) Test `format=tagcloud` html output, namespaced
 * [timeline-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/timeline-01.json) Test for timeline result format
 * [tree-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/tree-01.json) Tree format: Multi-page results
 * [tree-02.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/tree-02.json) Tree format: Simple one-page result
@@ -42,10 +72,9 @@ Contains 21 files with a total of 62 tests:
 * [tree-07.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/tree-07.json) Tree format: Simple one-page result
 
 ### V
+* [valuerank-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/valuerank-01.json) Test `format=valuerank` with all related parameters
 * [vcard-01.json](https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases/vcard-01.json) Test `format=vcard`
 
--- Last updated on 2017-11-11 by `readmeContentsBuilder.php`
-
 <!-- End of generated contents by readmeContentsBuilder.php -->
 
 ## Writing a test case
@@ -59,21 +88,21 @@ combination with the `--filter` option allows to select a single specific case.
 
 <pre>
 $ composer integration -- --filter vcard
-Using PHP 7.1.1
+Using PHP 8.1.31
 
-Semantic Result Formats: 3.0.0-alpha
+Semantic Result Formats: 5.0.0-alpha
 
-Semantic MediaWiki: 3.0.0-alpha (c352b6a, SMWSQLStore3, mysql)
-MediaWiki:          1.31.0-alpha (44c06df, MediaWiki vendor autoloader)
+Semantic MediaWiki: 5.0.1-alpha (25f24c1, SMWSQLStore, mysql)
+MediaWiki:          1.39.11 (MediaWiki vendor autoloader)
 Site language:      en
 
-Execution time:     2017-01-01 12:00
+Execution time:     2025-04-01 06:40
 Debug logs:         Disabled
 Xdebug:             Disabled (or not installed)
 
-PHPUnit 4.8.35 by Sebastian Bergmann and contributors.
+PHPUnit 8.5.41 by Sebastian Bergmann and contributors.
 
-Runtime:        PHP 7.1.1
+Runtime:        PHP 8.1.31
 Configuration:  /var/www/html/w/extensions/SemanticResultFormats/phpunit.xml.dist
 
 .

tests/phpunit/Integration/JSONScript/ReadmeContentsBuilder.php

@@ -0,0 +1,112 @@
+<?php
+
+namespace SRF\Tests\Integration\JSONScript;
+
+/**
+ * Build contents from a selected folder and replaces the content of the
+ * README.md from where the script was started.
+ *
+ * @license GPL-2.0-or-later
+ * @since 4.2.1
+ *
+ * @author milic
+ */
+class ReadmeContentsBuilder {
+
+	/**
+	 * @var string
+	 */
+	public const REPLACE_START_MARKER = '<!-- Begin of generated contents by readmeContentsBuilder.php -->';
+	public const REPLACE_END_MARKER = '<!-- End of generated contents by readmeContentsBuilder.php -->';
+
+	/**
+	 * @var array
+	 */
+	private $urlLocationMap = [
+		'List of tests' => 'https://github.com/SemanticMediaWiki/SemanticResultFormats/tree/master/tests/phpunit/Integration/JSONScript/TestCases'
+	];
+
+	/**
+	 * @since  4.2.1
+	 */
+	public function run() {
+		$file = __DIR__ . '/README.md';
+
+		$replacement = self::REPLACE_START_MARKER . "\n\n";
+		$replacement .= $this->doGenerateContentFor( 'List of tests', __DIR__ . '/TestCases' );
+
+		$replacement .= "\n" . self::REPLACE_END_MARKER;
+
+		$contents = file_get_contents( $file );
+		$start = strpos( $contents, self::REPLACE_START_MARKER );
+		$length = strrpos( $contents, self::REPLACE_END_MARKER ) - $start + strlen( self::REPLACE_END_MARKER );
+
+		file_put_contents(
+			$file,
+			substr_replace( $contents, $replacement, $start, $length )
+		);
+	}
+
+	private function doGenerateContentFor( $title, $path ) {
+		$dateTimeUtc = new \DateTime( 'now', new \DateTimeZone( 'UTC' ) );
+		$urlLocation = $this->urlLocationMap[$title];
+
+		$counter = 0;
+		$tests = 0;
+		$previousFirstKey = '';
+		$list = '';
+
+		$files = $this->findFilesFor( $path, 'json' );
+		ksort( $files );
+
+		foreach ( $files as $key => $location ) {
+			if ( $previousFirstKey !== $key[0] ) {
+				$list .= "\n" . '### ' . ucfirst( $key[0] ) . "\n";
+			}
+
+			$list .= '* [' . $key . '](' . $urlLocation . '/' . $key . ')';
+
+			$contents = json_decode( file_get_contents( $location ), true );
+
+			if ( $contents === null || json_last_error() !== JSON_ERROR_NONE ) {
+				continue;
+			}
+
+			if ( isset( $contents['description'] ) ) {
+				$list .= " " . $contents['description'];
+			}
+
+			if ( isset( $contents['tests'] ) ) {
+				$tests += count( $contents['tests'] );
+			}
+
+			$list .= "\n";
+			$counter++;
+			$previousFirstKey = $key[0];
+		}
+
+		$head = "## $title\n\n";
+		$head .= "- Files: $counter (includes $tests tests)\n";
+		$head .= "- Last update: " . $dateTimeUtc->format( 'Y-m-d' ) . "\n";
+
+		return $head . $list;
+	}
+
+	private function findFilesFor( $path, $extension ) {
+		$files = [];
+
+		$directoryIterator = new \RecursiveDirectoryIterator( $path );
+
+		foreach ( new \RecursiveIteratorIterator( $directoryIterator ) as $fileInfo ) {
+			if ( strtolower( substr( $fileInfo->getFilename(), -( strlen( $extension ) + 1 ) ) ) === ( '.' . $extension ) ) {
+				$files[$fileInfo->getFilename()] = $fileInfo->getPathname();
+			}
+		}
+
+		return $files;
+	}
+
+}
+
+$readmeContentsBuilder = new ReadmeContentsBuilder();
+$readmeContentsBuilder->run();