boost/boostlook
2
0
Fork 0
mirror of https://github.com/boostorg/boostlook.git synced 2026-02-25 16:22:12 +00:00
Code Issues Projects Releases Wiki Activity
Files
33ce117d70197f543c1957616a233cc343d2c168
boostlook/preview/contributor-guide/testing/intro.html

602 lines
23 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1">
<style>html.fonts-loading{visibility:hidden;opacity:0}</style>
<script>document.documentElement.classList.add('fonts-loading');</script>
<link rel="preload" href="../../_/font/NotoSansDisplay.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/NotoSansDisplay-Italic.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/MonaspaceNeon-Var.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<link rel="preload" href="../../_/font/MonaspaceXenon-Var.woff2" as="font" type="font/woff2" crossorigin="anonymous" />
<script>
(function() {
'use strict';
var revealed = false;
var reveal = function() {
if (revealed) return;
revealed = true;
document.documentElement.classList.remove('fonts-loading');
};
setTimeout(reveal, 3000);
if (!('FontFace' in window) || !('fonts' in document)) {
setTimeout(reveal, 100);
return;
}
var uiRoot = '../../_';
var fonts = [
{
family: 'Noto Sans',
url: uiRoot + '/font/NotoSansDisplay.woff2',
descriptors: { style: 'normal', weight: '100 900', stretch: '62.5% 100%' }
},
{
family: 'Noto Sans',
url: uiRoot + '/font/NotoSansDisplay-Italic.woff2',
descriptors: { style: 'italic', weight: '100 900', stretch: '62.5% 100%' }
},
{
family: 'Monaspace Neon',
url: uiRoot + '/font/MonaspaceNeon-Var.woff2',
descriptors: { style: 'normal', weight: '400' }
},
{
family: 'Monaspace Xenon',
url: uiRoot + '/font/MonaspaceXenon-Var.woff2',
descriptors: { style: 'italic', weight: '400' }
}
];
var loadPromises = fonts.map(function(f) {
try {
var face = new FontFace(f.family, 'url("' + f.url + '")', f.descriptors);
return face.load().then(function(loaded) {
document.fonts.add(loaded);
return loaded;
}).catch(function() {
return null;
});
} catch (e) {
return Promise.resolve(null);
}
});
Promise.all(loadPromises)
.then(function() {
return document.fonts.ready;
})
.then(reveal)
.catch(reveal);
})();
</script> <title>Introduction to Testing :: Boost Site Docs</title>
<link rel="canonical" href="https://boost.revsys.dev/contributor-guide/testing/intro.html">
<link rel="prev" href="../debug-visualisers.html">
<link rel="next" href="test-policy.html">
<meta name="generator" content="Antora 3.1.14">
<link rel="stylesheet" href="../../_/css/boostlook.css">
<link rel="stylesheet" href="../../_/css/site.css">
<link rel="stylesheet" href="../../_/css/vendor/tabs.css">
<script>
(function() {
if (window.self !== window.top) return;
var theme = localStorage.getItem('antora-theme');
if (!theme && window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
theme = 'dark';
}
if (theme === 'dark') document.documentElement.classList.add('dark');
})();
</script>
<script>var uiRootPath = '../../_'</script>
<link rel="icon" href="../../_/img/favicons/favicon.ico" type="image/x-icon">
<!-- Favicon configuration -->
<link rel="apple-touch-icon" sizes="180x180" href="../../_/img/favicons/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="../../_/img/favicons/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="../../_/img/favicons/favicon-16x16.png">
<link rel="manifest" href="../../_/img/favicons/site.webmanifest">
<link rel="shortcut icon" href="../../_/img/favicons/favicon.ico">
</head>
<body class="article toc2 toc-left">
<div class="boostlook">
<script type="module">import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs'; mermaid.initialize({"startOnLoad":true});</script> <div id="header">
<div id="toc" class="nav-container toc2" data-component="contributor-guide" data-version="">
<aside class="nav">
<button class="nav-close"></button>
<div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
<nav class="nav-menu">
<div class="title-row">
<h3 class="title"><a href="../index.html">Contributor Guide</a></h3>
<button class="theme-toggle" aria-label="Toggle dark mode" title="Toggle theme" style="display:none">
<i class="fas fa-sun theme-icon-light"></i>
<i class="fas fa-moon theme-icon-dark"></i>
</button> </div>
<ul class="nav-list">
<ul class="nav-list">
<li class="" data-depth="1">
<a class="nav-link" href="../getting-involved.html">Getting Involved</a>
</li>
<li class="" data-depth="1">
<a class="nav-link" href="../contributors-faq.html">Contributors FAQ</a>
</li>
<li class="" data-depth="1">
<span class="nav-text">Requirements</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/library-requirements.html">Library</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/license-requirements.html">License</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/portability-requirements.html">Portability</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/organization-requirements.html">Organization</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../requirements/library-metadata.html">Metadata</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Design</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/design-best-practices.html">Best Practices</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/headers.html">Headers</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/backwards-compatibility.html">Backwards Compatibility</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/separate-compilation.html">Separate Compilation</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/dependencies.html">Dependencies</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../design-guide/borland.html">Borland Portability</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Development</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../version-control.html">Version Control</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../best-practices.html">Best Practices</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../debug-visualisers.html">Debug Visualizers</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Testing</span>
</li>
<ul class="nav-list">
<li class=" is-current-page" data-depth="2">
<a class="nav-link" href="intro.html">Introduction</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="test-policy.html">Test Policy</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="boost-test-matrix.html">Test Matrix</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="regression-tests.html">Local Regression Tests</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="writing-tests.html">Writing Tests</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="sanitizers.html">Sanitizers</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="continuous-integration.html">Continuous Integration</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="fuzzing.html">Fuzzing</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">The Super-Project</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/overview.html">Layout</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/getting-started.html">Getting Started</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/library-maintenance.html">Library Maintenance</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../superproject/library-workflow.html">Library Workflow</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Writing Documentation</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../docs/layout.html">Guidelines</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../docs/content.html">Content</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../docs/components.html">Components</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../docs/antora.html">Antora Guide</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../docs/asciidoc.html">AsciiDoc Style Guide</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../docs/logo-policy-media-guide.html">Logo Policy and Media Guide</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Releases</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../release-process.html">Release Process</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../release-notes.html">Release Notes</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Contributor Community</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../contributor-community-introduction.html">Introduction</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../oversight-committee.html">Fiscal Sponsorship Committee</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../tweeting.html">Tweeting</a>
</li>
<li class="" data-depth="2">
<a class="nav-link" href="../site-docs-style-guide.html">Site-docs Style Guide</a>
</li>
</ul>
<li class="" data-depth="1">
<span class="nav-text">Appendices</span>
</li>
<ul class="nav-list">
<li class="" data-depth="2">
<a class="nav-link" href="../organization-guide.html">Organization Guide</a>
</li>
</ul>
</ul>
</ul>
</nav>
</div>
</div>
</aside>
</div>
</div> <div id="content">
<article class="doc max-width-reset">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<nav class="breadcrumbs" aria-label="breadcrumbs">
<ul>
<li>
<a href="../index.html" aria-label="Home: Contributor Guide">
<svg xmlns="http://www.w3.org/2000/svg" width="1rem" height="1rem" viewBox="0 -960 960 960" fill="#000000" aria-hidden="true"><path d="M160-120v-480l320-240 320 240v480H560v-280H400v280H160Z"/></svg>
</a>
</li>
<li>Testing</li>
<li><a href="intro.html">Introduction</a></li>
</ul>
</nav>
<div class="spirit-nav">
<a accesskey="p" href="../debug-visualisers.html">
<span class="material-symbols-outlined" title="Previous: Debug Visualizers">arrow_back</span>
</a>
<a class="disabled" accesskey="u" aria-disabled="true" tabindex="-1">
<span class="material-symbols-outlined" title="Up:">arrow_upward</span>
</a>
<a accesskey="n" href="test-policy.html">
<span class="material-symbols-outlined" title="Next: Test Policy">arrow_forward</span>
</a>
</div></div>
<h1 class="page">Introduction to Testing</h1>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The Boost libraries are intended to be both reliable and portable. Every experienced programmer knows that means each library must be tested against a suitable number of test cases, on a range of platforms and compilers, and then tested again (<em>regression tested</em>) every time a change is made. The regression tests are run again before every public release.</p>
</div>
<div class="paragraph">
<p>There are three broad dimensions to Boost library testing:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The actual test codes - unit tests, regression tests, new feature and bug tests. Refer to <a href="writing-tests.html" class="xref page">Writing Tests</a>.</p>
</li>
<li>
<p>Tests that are integrated with the primary build systems, <a href="../build-systems/b2.html" class="xref page">B2</a> and <a href="../build-systems/cmake.html" class="xref page">CMake</a>.</p>
</li>
<li>
<p><a href="continuous-integration.html" class="xref page">Continuous Integration</a></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The new library developer needs to consider all three, however the initial focus on a new library will be the first in this list. Or, to put it another way, "Quality assurance based on a wide range of targeted tests" as one of the key answers to Professor Hoare&#8217;s question:</p>
</div>
<div class="paragraph">
<p>"<em>How did software get so reliable without proof?</em>"</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#_define_a_test_matrix">Define a Test Matrix</a></p>
</li>
<li>
<p><a href="#_use_predefined_macros_from_boost_config">Use Predefined Macros from Boost.Config</a></p>
</li>
<li>
<p><a href="#_regression_testing">Regression Testing</a></p>
</li>
<li>
<p><a href="#_next_steps">Next Steps</a></p>
</li>
<li>
<p><a href="#_see_also">See Also</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_define_a_test_matrix"><a class="anchor" href="#_define_a_test_matrix"></a>Define a Test Matrix</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When you&#8217;re looking to submit a library to the Boost collection, it&#8217;s essential to ensure broad compatibility with various compilers, platforms, and configurations. Create a test matrix of what you intend to support, and document what you do not intend to support, and consider:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Testing with multiple versions of each compiler. Popular compilers to consider include:</p>
<div class="ulist">
<ul>
<li>
<p>GCC (GNU Compiler Collection)</p>
</li>
<li>
<p>Clang</p>
</li>
<li>
<p>MSVC (Microsoft Visual C++)</p>
<div class="paragraph">
<p>The Boost user base can be using older versions of these compilers, so strive for compatibility with a reasonable range of versions if possible.</p>
</div>
<div class="paragraph">
<p>If your library depends on other Boost libraries or external libraries, ensure they are compatible with the compilers you are targeting. Be clear about any dependencies or prerequisites in your documentation.</p>
</div>
<div class="paragraph">
<p>Be wary of non-standard compiler features or extensions. If you must use them, guard them with appropriate preprocessor checks.
Boost provides its own set of configuration macros to help with this.</p>
</div>
</li>
</ul>
</div>
</li>
<li>
<p>Compatibility with various versions of the C++ Standard: C++11, C++14, C++17, C++20, and C++23. Some Boost libraries support many of the standards, while others target only more recent ones.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">Note</dt>
<dd>
<p>Supporting C++03 is no longer considered good practice.</p>
</dd>
</dl>
</div>
</li>
<li>
<p>Different operating systems, including Linux, Windows, macOS, and others like various BSDs.</p>
</li>
<li>
<p>Different architectures: x86, x64, ARM, MIPS. Architecture can affect word size (usually 32 or 64 bit), endianness, memory alignment, inline assembly, cache sizes, latency, and other memory and performance issues.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>When you have outlined your test matrix, study the predefined macros available to assist you, and make adjustments to your matrix appropriately.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_use_predefined_macros_from_boost_config"><a class="anchor" href="#_use_predefined_macros_from_boost_config"></a>Use Predefined Macros from Boost.Config</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are a set of macros in the <a href="https://www.boost.org/libs/config">Boost.Config</a> library that can be used to identify compiler capabilities, platform specifics, and other configuration details. These macros are designed to smooth out differences between compilers and platforms, allowing for more portable code, for example:</p>
</div>
<div class="sect2">
<h3 id="_compiler_identification"><a class="anchor" href="#_compiler_identification"></a>Compiler Identification</h3>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_COMP_GNUC</code>: Defined if the compiler is GCC.</p>
</li>
<li>
<p><code>BOOST_COMP_MSVC</code>: Defined if the compiler is Microsoft Visual C++.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_compiler_version_checks"><a class="anchor" href="#_compiler_version_checks"></a>Compiler Version Checks</h3>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_COMP_MSVC &gt;= BOOST_VERSION_NUMBER(19, 0, 0)</code>: Checks if the MSVC version is 19 or greater.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_platform_checks"><a class="anchor" href="#_platform_checks"></a>Platform Checks</h3>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_OS_LINUX</code>: Defined if the operating system is Linux.</p>
</li>
<li>
<p><code>BOOST_ARCH_X86_64</code>: Defined if the architecture is x86_64.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_standard_library_checks"><a class="anchor" href="#_standard_library_checks"></a>Standard Library Checks</h3>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_LIB_C_GNU</code>: Defined if the C standard library is from <a href="https://gcc.gnu.org/onlinedocs/libstdc++/">GNU</a>.</p>
</li>
<li>
<p><code>BOOST_LIB_STD_DINKUMWARE</code>: Defined if the standard library is from <a href="https://docwiki.embarcadero.com/RADStudio/Sydney/en/Dinkumware_Standard_C%2B%2B_Library">Dinkumware</a> (often associated with MSVC).</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="_feature_checks"><a class="anchor" href="#_feature_checks"></a>Feature Checks</h3>
<div class="ulist">
<ul>
<li>
<p><code>BOOST_NO_CXX14_RETURN_TYPE_DEDUCTION</code>: Defined if the compiler does not support return type deduction introduced in C++14.</p>
</li>
<li>
<p><code>BOOST_NO_CXX11_AUTO_DECLARATIONS</code>: Defined if the compiler does not support auto declarations from C++11. For example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">#include &lt;boost/config.hpp&gt;
// ...
#ifdef BOOST_NO_CXX11_AUTO_DECLARATIONS
// Use traditional type declaration
int x = 42;
#else
// Use C++11 auto
auto x = 42;
#endif
// ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Use this same coding structure for any of the other macros.</p>
</div>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_regression_testing"><a class="anchor" href="#_regression_testing"></a>Regression Testing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Boost releases are run through regression tests which automatically generates compiler status HTML tables for various platforms. Unless otherwise indicated, the C++ Standard Library implementation is the one shipped with the compiler. Refer to <a href="https://www.boost.org/doc/regression/library_status/doc/library_status.html">Generating Library Status Tables</a>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Note</dt>
<dd>
<p>The HTML tables are not a good indication of a particular compiler&#8217;s compliance with the C++ Standard. The Boost libraries often contain workarounds which mask compiler deficiencies.</p>
<div class="paragraph">
<p>Some regression tests are run only occasionally, and might be relatively out-of-date. Check the date and revision in the column headings.</p>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_next_steps"><a class="anchor" href="#_next_steps"></a>Next Steps</h2>
<div class="sectionbody">
<div class="paragraph">
<p>First, familiarize yourself with the Boost <a href="test-policy.html" class="xref page">Test Policy</a>.</p>
</div>
<div class="paragraph">
<p>Then, read the documentation for the following libraries, which support the writing of unit, feature and regression tests:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://www.boost.org/libs/test">Boost.Test</a></p>
</li>
<li>
<p><a href="https://www.boost.org/libs/core">Boost.Core</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Start small and develop a good understanding of how these testing libraries work, before writing more than a few tests.</p>
</div>
<div class="sect2">
<h3 id="_advanced_testing"><a class="anchor" href="#_advanced_testing"></a>Advanced Testing</h3>
<div class="paragraph">
<p>When you have a good understanding of the basic testing procedures, look into more advanced techniques, such as <a href="fuzzing.html" class="xref page">Fuzz Testing</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also"><a class="anchor" href="#_see_also"></a>See Also</h2>
<div class="sectionbody">
<div class="ulist">
<ul>
<li>
<p><a href="../release-process.html" class="xref page">Release Process</a></p>
</li>
<li>
<p><a href="../../user-guide/testing-debugging.html" class="xref page">Testing and Debugging</a></p>
</li>
<li>
<p><a href="writing-tests.html" class="xref page">Writing Tests</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="edit-this-page">
<a href="file:///Users/julio/dev/website-v2-docs/contributor-guide/modules/ROOT/pages/testing/intro.adoc">Edit this Page</a>
</div>
<nav class="pagination">
<span class="prev"><a href="../debug-visualisers.html">Debug Visualizers</a></span>
<span class="next"><a href="test-policy.html">Test Policy</a></span>
</nav>
</article>
</div>
<div id="footer">
<script id="site-script" src="../../_/js/site.js" data-ui-root-path="../../_"></script>
<script async src="../../_/js/vendor/highlight.js"></script>
<script async src="../../_/js/vendor/tabs.js" data-sync-storage-key="preferred-tab"></script>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink