From c8f8f36292d3d9f7c881126fc0e5c0775b14060b Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Tue, 22 Apr 2025 13:28:42 +0000
Subject: [PATCH] QDoc: Allow optional extra arguments in output test

Add a capability of testing features enabled via command line arguments
passed to QDoc in data-driven tests.

Additional arguments are read from an optional `args.txt` located in the
same folder as the main qdocconf file.

Task-number: QTBUG-136115
Change-Id: I801144a385d19b3ffeffa12db6716fdca5146a51
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit bbbf1ad606f2ba0b244ed609d746408a3d25f30d)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 64f2acae3d330f530d1bf241bb31257184ec9995)
---
 .../tests/validateqdocoutputfiles/README.md   | 21 +++++++++++++------
 .../tst_validateqdocoutputfiles.cpp           | 16 ++++++++++++--
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/README.md b/src/qdoc/qdoc/tests/validateqdocoutputfiles/README.md
index 728cbee62..cba45a84b 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/README.md
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/README.md
@@ -22,14 +22,17 @@ includes the diff in its output if this happens.
    directory should be descriptive of the test project.
 2. Create a `.qdocconf` file in the new directory. See
    [The .qdocconf file](# The .qdocconf file) below for further details.
-3. Add the necessary files (.qdoc, .h/.cpp, .qml, etc) so that the project
+3. If the test requires additional command line arguments passed to QDoc,
+   create an `args.txt` file in the same location as the main .qdocconf
+   file. See [The args.txt file](# The args.txt file) below.
+4. Add the necessary files (.qdoc, .h/.cpp, .qml, etc) so that the project
    can be built in a meaningful manner.
-4. Run QDoc on the project.
-5. Verify that the output looks correct.
-6. Copy the output into `[testdata/[new test directory]/expected`.
-7. Run the test executable and verify that the test output includes a **PASS**
+5. Run QDoc on the project.
+6. Verify that the output looks correct.
+7. Copy the output into `[testdata/[new test directory]/expected`.
+8. Run the test executable and verify that the test output includes a **PASS**
    line for the new test-case.
-8. Push your change upstream.
+9. Push your change upstream.
 
 ## Update the expected content for all tests
 If you make a change to QDoc that causes significant changes in output, you may
@@ -72,6 +75,12 @@ QDoc project in the directory. Observe the following:
 - Place the sources for your new test in a subdirectory of the test project
   directory. By convention, the sources are placed in a directory named `src`.
 
+### The args.txt file
+An optional `args.txt` file, located in the same directory as the main .qdocconf
+file, is used for passing additional command line arguments to QDoc for a
+particular test. The file can contain any argument(s) accepted by QDoc on the
+command line.
+
 ### The `expected` directory
 The `expected` directory contains the expected output from QDoc
 for the project. If QDoc generates an empty directory (for example, it
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/tst_validateqdocoutputfiles.cpp b/src/qdoc/qdoc/tests/validateqdocoutputfiles/tst_validateqdocoutputfiles.cpp
index a3c08ad7b..40368faf4 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/tst_validateqdocoutputfiles.cpp
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/tst_validateqdocoutputfiles.cpp
@@ -132,6 +132,7 @@ void tst_validateQdocOutputFiles::qdocProjects_data()
     using namespace Qt::StringLiterals;
     QTest::addColumn<QString>("qdocconf");
     QTest::addColumn<QString>("expectedPath");
+    QTest::addColumn<QString>("extraArgs");
 
     QDirIterator qdocconfit(m_testDataDirectory, QStringList { u"*.qdocconf"_s },
                             QDir::Files | QDir::NoDotAndDotDot, QDirIterator::Subdirectories);
@@ -140,11 +141,19 @@ void tst_validateQdocOutputFiles::qdocProjects_data()
         if (configFile.baseName() != configFile.dir().dirName())
             continue;
 
+        QString extraArgs{configFile.dir().absolutePath() + u"/args.txt"_s};
+        if (QFileInfo::exists(extraArgs))
+            extraArgs.insert(0, u'@');
+        else
+            extraArgs.clear();
+
         const QString testName =
                 configFile.dir().dirName() + u'/' + configFile.fileName();
 
         QTest::newRow(testName.toUtf8().constData())
-                << configFile.absoluteFilePath() << configFile.dir().absolutePath() + "/expected/";
+                << configFile.absoluteFilePath()
+                << configFile.dir().absolutePath() + "/expected/"
+                << extraArgs;
     }
 }
 
@@ -152,6 +161,7 @@ void tst_validateQdocOutputFiles::qdocProjects()
 {
     QFETCH(const QString, qdocconf);
     QFETCH(const QString, expectedPath);
+    QFETCH(const QString, extraArgs);
 
     QString actualPath{m_outputDir->path()};
     if (regenerate) {
@@ -161,7 +171,9 @@ void tst_validateQdocOutputFiles::qdocProjects()
             qCritical("Cannot remove expected output directory, aborting!");
     }
 
-    const QStringList arguments{ "-outputdir", actualPath, m_extraParams, qdocconf };
+    QStringList arguments{ "-outputdir", actualPath, m_extraParams, qdocconf };
+    if (!extraArgs.isEmpty())
+        arguments << extraArgs;
 
     runQDocProcess(arguments);