diff options
| author | Paul Wicking <paul.wicking@qt.io> | 2018-12-18 15:08:00 +0100 |
|---|---|---|
| committer | Paul Wicking <paul.wicking@qt.io> | 2019-01-15 05:17:20 +0000 |
| commit | ca97f0694d9483a7a0013ecc356f65c36581a4d0 (patch) | |
| tree | a05b31da9f96f10029ffac85502ac005ce86f830 /tests | |
| parent | 5cb9ce406ee036fc587456281641ee1bb7eadf1f (diff) | |
| download | qttools-ca97f0694d9483a7a0013ecc356f65c36581a4d0.tar.gz | |
Add simple smoke test for QDoc
This adds a simple QDoc project that makes use of a subset of
QDoc's commands in a .qdoc file, and a data set containing the
expected output when qdoc runs on this project. The idea is to
generate output that can be compared across versions of QDoc
itself.
Task-number: QTBUG-71168
Change-Id: Idaba28d3fdfd5dbedfcd2ce4cc4d8e9361bd2008
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@qt.io>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Diffstat (limited to 'tests')
6 files changed, 235 insertions, 0 deletions
diff --git a/tests/auto/qdoc/qdoc.pro b/tests/auto/qdoc/qdoc.pro index da9d55a8f..fd4953df8 100644 --- a/tests/auto/qdoc/qdoc.pro +++ b/tests/auto/qdoc/qdoc.pro @@ -1,5 +1,6 @@ TEMPLATE = subdirs SUBDIRS = \ + qdocfileoutput \ qdocglobals diff --git a/tests/auto/qdoc/qdocfileoutput/expected_output/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/qdocfileoutput/expected_output/qdoctests-qdocfileoutput.html new file mode 100644 index 000000000..ea9946d6b --- /dev/null +++ b/tests/auto/qdoc/qdocfileoutput/expected_output/qdoctests-qdocfileoutput.html @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<!-- qdoctests-outputfromqdocfiles.qdoc --> + <title>Testing QDoc output from .qdoc files | Test</title> +</head> +<body> +<li>Testing QDoc output from .qdoc files</li> +<div class="sidebar"> +<div class="toc"> +<h3><a name="toc">Contents</a></h3> +<ul> +<li class="level1"><a href="#supported-file-types">Supported file types</a></li> +<li class="level1"><a href="#further-information">Further information</a></li> +</ul> +</div> +<div class="sidebar-content" id="sidebar-content"></div></div> +<h1 class="title">Testing QDoc output from .qdoc files</h1> +<span class="subtitle"></span> +<!-- $$$qdoctests-qdocfileoutput.html-description --> +<div class="descr"> <a name="details"></a> +<p>QDoc generates documentation for software projects. It does this by extracting <i>QDoc comments</i> from project source files. QDoc comments are signified by a C-style-like comment tag followed by an exclamation point, like this: <code>/*!</code> <code>This text is contained within QDoc comment tags.</code> <code>*/</code>.</p> +<a name="supported-file-types"></a> +<h2 id="supported-file-types">Supported file types</h2> +<p>QDoc parses <code>.cpp</code> and <code>.qdoc</code> files. It does extract comments from header (<code>.h</code>) files.</p> +<a name="further-information"></a> +<h2 id="further-information">Further information</h2> +<p>This test document is written with the purpose of testing the output QDoc generates when parsing <code>.qdoc</code> files. It is fairly simple and makes use of a limited subset of QDoc's command. Those commands are:</p> +<ul> +<li><code>\page</code></li> +<li><code>\title</code></li> +<li><code>\brief</code></li> +<li><code>\e</code> (for emphasizing "QDoc comments")</li> +<li><code>\c</code> (for multiple monospace-formatted entries)</li> +<li><code>\section1</code></li> +<li><code>\list</code></li> +<li><code>\li</code></li> +<li><code>\endlist</code></li> +</ul> +</div> +<!-- @@@qdoctests-qdocfileoutput.html --> +</body> +</html> diff --git a/tests/auto/qdoc/qdocfileoutput/qdocfileoutput.pro b/tests/auto/qdoc/qdocfileoutput/qdocfileoutput.pro new file mode 100644 index 000000000..a03f5ab6e --- /dev/null +++ b/tests/auto/qdoc/qdocfileoutput/qdocfileoutput.pro @@ -0,0 +1,9 @@ +CONFIG += testcase +QT = core testlib + +TARGET = tst_qdocfileoutput + +SOURCES += \ + tst_qdocfileoutput.cpp + +QMAKE_DOCS = $$PWD/test.qdocconf diff --git a/tests/auto/qdoc/qdocfileoutput/qdoctests-outputfromqdocfiles.qdoc b/tests/auto/qdoc/qdocfileoutput/qdoctests-outputfromqdocfiles.qdoc new file mode 100644 index 000000000..fc3a5d870 --- /dev/null +++ b/tests/auto/qdoc/qdocfileoutput/qdoctests-outputfromqdocfiles.qdoc @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qdoctests-qdocfileoutput.html + \title Testing QDoc output from .qdoc files + \brief This is a simple page for testing purposes only. + + QDoc generates documentation for software projects. It does this by + extracting \e {QDoc comments} from project source files. QDoc comments are + signified by a C-style-like comment tag followed by an exclamation point, + like this: + \beginqdoc \c {This text is contained within QDoc comment tags.} \endqdoc. + + \section1 Supported file types + QDoc parses \c .cpp and \c .qdoc files. It does extract comments from + header (\c {.h}) files. + + \section1 Further information + This test document is written with the purpose of testing the output QDoc + generates when parsing \c .qdoc files. It is fairly simple and makes use of + a limited subset of QDoc's command. Those commands are: + \list + \li \c {\page} + \li \c {\title} + \li \c {\brief} + \li \c {\e} (for emphasizing "QDoc comments") + \li \c {\c} (for multiple monospace-formatted entries) + \li \c {\section1} + \li \c {\list} + \li \c {\li} + \li \c {\endlist} + \endlist +*/ diff --git a/tests/auto/qdoc/qdocfileoutput/test.qdocconf b/tests/auto/qdoc/qdocfileoutput/test.qdocconf new file mode 100644 index 000000000..47ed6a919 --- /dev/null +++ b/tests/auto/qdoc/qdocfileoutput/test.qdocconf @@ -0,0 +1,11 @@ +project = Test +description = "A test project for QDoc build artifacts" +moduleheader = + +headerdirs = . +sourcedirs = . + +sources.fileextensions = *.qdoc + +macro.beginqdoc = "\\c {/*!}" +macro.endqdoc = "\\c */" diff --git a/tests/auto/qdoc/qdocfileoutput/tst_qdocfileoutput.cpp b/tests/auto/qdoc/qdocfileoutput/tst_qdocfileoutput.cpp new file mode 100644 index 000000000..1be519786 --- /dev/null +++ b/tests/auto/qdoc/qdocfileoutput/tst_qdocfileoutput.cpp @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the tools applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:GPL-EXCEPT$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3 as published by the Free Software +** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include <QProcess> +#include <QTemporaryDir> +#include <QtTest> + +class tstQDocFileOutput : public QObject +{ + Q_OBJECT + +private slots: + void initTestCase(); + void compareQDocOutputWithExpectedData(); + +private: + QTemporaryDir m_outputDir; +}; + +void tstQDocFileOutput::initTestCase() +{ + if (!m_outputDir.isValid()) { + const QString errorMessage = + "Couldn't create temporary directory:" + m_outputDir.errorString(); + QFAIL(qPrintable(errorMessage)); + } +} + +void tstQDocFileOutput::compareQDocOutputWithExpectedData() +{ + // Build the path to the QDoc binary the same way moc tests do for moc. + QString binpath = QLibraryInfo::location(QLibraryInfo::BinariesPath); + QString extension; + if (QSysInfo::productType() == "windows") + extension += ".exe"; + const QString qdoc = QString("%1/qdoc" + extension).arg(binpath); + + const QStringList arguments = { + "--outputdir", + m_outputDir.path(), + QFINDTESTDATA("test.qdocconf") + }; + + QProcess qdocProcess; + qdocProcess.setProgram(qdoc); + qdocProcess.setArguments(arguments); + qdocProcess.start(); + qdocProcess.waitForFinished(); + QString output(qdocProcess.readAllStandardOutput()); + QString errors(qdocProcess.readAllStandardError()); + + if (qdocProcess.exitCode() != 0) { + qInfo() << "QDoc exited with exit code" << qdocProcess.exitCode(); + if (output.size() > 0) + qInfo() << "Received output:\n" << output; + if (errors.size() > 0) + qInfo() << "Received errors:\n" << errors; + QFAIL("Running QDoc failed. See output above."); + } + + QFile expected(QFINDTESTDATA("/expected_output/qdoctests-qdocfileoutput.html")); + QFile actual(m_outputDir.path() + "/qdoctests-qdocfileoutput.html"); + + if (!expected.open(QIODevice::ReadOnly)) + QFAIL("Cannot open expected data file!"); + QTextStream expectedIn(&expected); + + if (!actual.open(QIODevice::ReadOnly)) + QFAIL("Cannot open actual data file!"); + QTextStream actualIn(&actual); + + int lineNumber = 0; + while (!expectedIn.atEnd()) { + while (!actualIn.atEnd()) { + lineNumber++; + QString expectedLine = + QString::number(lineNumber) + ": " + expectedIn.readLine(); + QString actualLine = + QString::number(lineNumber) + ": " + actualIn.readLine(); + QCOMPARE(expectedLine, actualLine); + } + } +} + +QTEST_APPLESS_MAIN(tstQDocFileOutput) + +#include "tst_qdocfileoutput.moc" |