common_macros.tex

\newif\ifnotpaper
\newif\ifnotdefense

%------------------------------------------------------------------------------
% Reused in seminar slides
%------------------------------------------------------------------------------

\def\rqatext{What test approaches do the literature describe?}
\def\rqbtext{How consistent are these descriptions?}
\def\rqctext{Can we systematically resolve any of these inconsistencies?}

\def\addTextEx{For example, \citetISTQB{} \multiAuthHelper{cite}
    \citet{GerrardAndThompson2002} as the original source
    for \ifnotpaper their \else its \fi definition of ``scalability''
    % (see \Cref{scal-test-rec})
    which we verify by looking at this original source.}

\newcommand\iterGraphHelper[3]{\centering
    \begin{tikzpicture}[thick, scale=#3, every label/.style={align=left, scale=#3}]
        \pie[text=inside, sum=auto, color={blue!60, orange!60}]{
            {\the\numexpr #1 - #2\relax}/,
            {\the#2}/
        }
    \end{tikzpicture}}

\newcommand\beforeIterGraph[1]{\iterGraphHelper{\TotalBefore}{\UndefBefore}{#1}}
\newcommand\afterIterGraph [1]{\iterGraphHelper{\TotalAfter} {\UndefAfter} {#1}}

\newcommand\iterLegend[1]{\centering
    \begin{tikzpicture}[scale=#1]
        \matrix [thick, draw=black] {
        \node[label=right:{\hspace{-0.25cm} \Large \textbf{Legend}}] {}; \\
        \node[thick, shape=rectangle, draw=black, fill=blue!60,   label=right:{Defined}](0) {}; \\
        \node[thick, shape=rectangle, draw=black, fill=orange!60, label=right:{Undefined}](1) {}; \\
        };
    \end{tikzpicture}}

\def\supers{Dr.~Spencer Smith and Dr.~Jacques Carette}
\def\supersAck{\supers{} have been great supervisors and valuable sources of
    guidance and feedback}
\def\familyAck{My family has also supported me in more ways than I can count,
    and I cannot thank them enough}
\NewDocumentCommand{\codeAI}{s}{ChatGPT was used to help generate supplementary
    Python code for constructing visualizations and generating \LaTeX{} code,
    including regex\IfBooleanTF{#1}{\\ \item}{.} ChatGPT and GitHub Copilot
    were both used for assistance with \LaTeX{} formatting}

%------------------------------------------------------------------------------
% Spacing Options
%------------------------------------------------------------------------------

\newcommand{\thesisForceSingleSpacing}{\singlespacing}
\newcommand{\thesisForceDoubleSpacing}{\doublespacing}

%------------------------------------------------------------------------------
% Portable HREFs
%------------------------------------------------------------------------------

% Common variant
\newcommand{\porthref}[2]{\href{#2}{#1}\printOnlyFootnote{\url{#2}}}

% Custom URLs
\newcommand{\porthreft}[3]{\href{#3}{#1}\printOnlyFootnote{\href{#3}{#2}}}
% Inside of some environments, footnote marks aren't registered properly, so we
% need to manually write the "text" part
\newcommand{\porthreftm}[2]{\href{#2}{#1\printOnlyFootnoteMark}}

\newcommand{\formatPaper}[2]{%
    \ifnotpaper #1{#2}%
    \else \underline{#2}%
    \fi
}

\def\refHelper{\ifnotpaper\else Reference \fi}
\newcommand\multiAuthHelper[1]{\ifnotpaper #1\else #1s\fi}
\def\docType{\ifnotpaper thesis%
    \else paper%
    \fi}

\newcommand\flawref[1]{%
    \ifnotpaper \labelcref{#1}%
    \else \Cref{#1}%
    \fi}

\newcommand\ifblind[2]{\IfEndWith*{\jobname}{_blind}{#1}{#2}}

%------------------------------------------------------------------------------
% Generic "chunks" that get reused
%------------------------------------------------------------------------------

\NewDocumentCommand{\citepos}{o m}{%
    \citeauthor{#2}'s \IfValueTF{#1}{\citeyearpar[#1]{#2}}{\citeyearpar{#2}}}

\def\PaigeMtgNote{\citetext{Dr.~R.~Paige, private communication, Oct.~14, 2025}}

\def\oneSrcDistinct{we make a distinction between ``self-contained'' flaws and
    ``internal'' flaws}

\def\highLvlScope{a high-level overview of what is in scope\ifnotpaper; see
    \Cref{app-scope} for more detailed discussion on what we include and
    exclude\fi}

\def\listAllSrcs{\ifnotpaper\ and list all sources in each tier
        in \Cref{app-src-tiers}\fi}

\newcommand\defRel[3]{We can formally define the #1 relation $#2$ on the set
    $T$ of terms used by the literature to describe test approaches based on #3.}

\NewDocumentCommand{\approachFields}{s}{%
    definitions, categories\IfBooleanTF{#1}{}{\ (see \Cref{cats-def})},
    synonyms\IfBooleanTF{#1}{}{\ (see \Cref{syn-rels})}, and
    parents\IfBooleanTF{#1}{}{\ (see \Cref{par-chd-rels})}%
}

\def\displayNL{\\
    $\,\hookrightarrow\,$\quad }

\DeclareDocumentCommand\seeSrcCode{ m m m g }{(see the
    \href{https://github.com/samm82/TestingTesting/blob/#1/#2\#L#3\IfNoValueF{#4}{-L#4}}
    {relevant source code})}

\def\ourApproachGlossary{\ifblind{our test approach glossary}{%
        \href{https://github.com/samm82/TestingTesting/blob/main/ApproachGlossary.csv}
        {our test approach glossary}}}

\def\accelTolTest{astronauts \citep[p.~11]{MorgunEtAl1999}, aviators
    \citep[pp.~27, 42]{HoweAndJohnson1995}, or catalysts
    \citep[p.~1463]{LiuEtAl2023}}
\NewDocumentCommand{\orthTestIntro}{s}{%
    \IfBooleanTF{#1}{s}{S}ome test approaches appear to be combinations of
    other (seemingly orthogonal) approaches}
\def\impKeywords{``implied'', ``can be'', ``sometimes'', ``should be'',
    ``ideally'', ``usually'', ``most'', ``likely'', ``often'', ``if'',
    ``although'', and ``incorrectly''\utd{}}

\def\recFigs{\Cref{fig:recoveryIdealGraphs,fig:recoveryGraphs,fig:perf-graph}}
% fig:scalGraphs

% Define common footnotes about IEEE testing terms for reuse
\def\noHyperIEEE{\begin{NoHyper}\citeauthor{IEEE2022}\end{NoHyper}}
\newcommand{\distinctIEEE}[1]{distinct from the notion of ``test #1'' described
    in \Cref{tab:ieeeCats}}
\newcommand{\notDefDistinctIEEE}[1]{\footnote{Not formally defined, but
        \distinctIEEE{#1}.}}
% % Defined with help from GitHub Copilot
% \NewDocumentCommand{\gerrardDistinctIEEE}{s m}{%
%     \IfBooleanTF{#1}{}{\footnote}%
%     {``Each type of test addresses a different risk area''
%         \citep[p.~12]{Gerrard2000a}, which is \distinctIEEE{#2}.}%
% }

\NewDocumentCommand{\multiCatIntro}{s}{%
    \IfBooleanTF{#1}{T}{we automatically detected t}est approaches with more
    than one category that violate our assumption of orthogonality
    (see \Cref{orth-approach})}

\newcommand\reflexParChdFlaw{Parent-child relations that violate irreflexivity as
    outlined in \Cref{par-chd-rels} (i.e., cases where a child is given as a
    parent of itself)}
\NewDocumentCommand{\parSynFlaw}{s}{%
    \IfBooleanTF#1{P}{p}airs of synonyms where one is a subapproach of the
    other; these relations cannot coexist since synonym relations are symmetric
    while parent-child relations are asymmetric (as outlined in
    \Cref{syn-rels,par-chd-rels}, respectively).}
\NewDocumentCommand\parSynIntro{s}{%
    \IfBooleanTF#1{t}{T}here are also \parSynFlaw{}
    \IfBooleanTF#1{Below are all}{We identified} \parSynCount{}
    of these pairs\IfBooleanTF#1{\ that we identified}{} through automatic
    analysis of our generated visualizations\ifnotpaper\ as described in
        \Cref{auto-flaw-detect}\fi}

\def\contraSummary{Contradictions are by
    \emph{far} the most common manifestation. This is likely because these
    are the most obvious flaws to detect automatically (see
    \Cref{\ifnotpaper auto-flaw-detect,\fi flawDmns})
    and because two (sets of) authors using different resources and not
    communicating have a high chance of disagreeing.}
\NewDocumentCommand\catsSummary{s}{\IfBooleanTF#1{a}{A}pproach categorizations
    are the most subjective and one of the most common flaw domains, likely due
    to the lack of standardization about what categories to use\ifnotpaper\
        (see \Cref{alt-cats} for more detailed discussion)\fi.}
\def\semFlaws{In general, semantic flaws are more common than syntactic ones.
    The number of category flaws is comparable to the numbers of flaws
    with the relations and definitions of test approaches.}

\def\testingDefRefs{\ifnotpaper
        (\citealp[p.~10]{IEEE2022}; \citeyear[p.~6]{IEEE2021c};
        \citeyear[p.~473]{IEEE2017})\else \cite[p.~473]{IEEE2017},
        \cite[p.~10]{IEEE2022}, \cite[p.~6]{IEEE2021c}\fi}

\newcommand{\appDiffs}[1]{These differences make it unclear how testers should
    perform #1, which could lead to miscommunication and unmet expectations.}

% Examples of flaws
\def\bugPattonFlaw{\citet[pp.~13\==14]{Patton2006} ``just call[s] it what it
    is and get[s] on with it'', abandoning these four terms, ``problem'',
    ``incident'', ``anomaly'', ``variance'', ``inconsistency'', ``feature'' (!),
    and ``a list of unmentionable terms'' in favour of ``bug''; after all,
    ``there's no reason to dice words''!}
\NewDocumentCommand\tourFlaw{s}{%
    The structure of tours can be defined as either quite general
    \IfBooleanTF#1{\citetext{p.~34}}{\citep[p.~34]{IEEE2022}} or ``organized
    around a special focus'' \citepISTQB{}.}
\def\alphaFlaw{Alpha testing can be performed by ``users within the organization
    developing the software'' \citep[p.~17]{IEEE2017}, ``a small, selected
    group of potential users'' \citep[p.~5\=/8]{SWEBOK2025}, or ``roles outside
    the development organization'' conducted ``in the developer's test
    environment'' \citepISTQB{}.}
\def\loadFlaw{Load testing may be performed with loads ``between anticipated
    conditions of low, typical, and peak usage'' \citep[p.~5]{IEEE2022} or with
    loads that are as large as possible \citep[p.~86]{Patton2006}.}
\newcommand\staticLevelBlurb[1]{\ifnotpaper\else inconsistently \fi categorize
    static testing as a test level in \citeyearpar[p.~43\ifnotpaper #1\fi]{IEEE2021b}}
\NewDocumentCommand{\seeRefMissing}{s}{%
    \IfBooleanTF#1{}{\refHelper} \citet[p.~42]{Kam2008} says ``See
    \emph{boundary value analysis},'' for the glossary entry of ``boundary
    value testing'' but does not include ``boundary value analysis'' in the
    glossary.}
\def\qualImprovFlaw{\citet[p.~5\=/4]{SWEBOK2025} says that quality improvement,
    along with quality assurance, is an aspect of testing that involves
    ``defining methods, tools, skills, and practices to achieve the specific
    quality level and objectives''; while testing that a system possesses
    certain qualities is in scope, actively improving the system in response to
    these results is \emph{not} itself part of testing \testingDefRefs{}.}
\NewDocumentCommand{\tolTestFlaw}{s}{%
    \IfBooleanTF#1{t}{T}he terms ``acceleration tolerance testing'' and
    ``acoustic tolerance testing'' do not seem to refer to software testing,
    but \citet[p.~56]{Firesmith2015} includes them regardless. Elsewhere,
    they seem to refer to testing the acoustic tolerance of rats
    \citep{HolleyEtAl1996} or the acceleration tolerance of \accelTolTest{},
    which which are not relevant to software testing.}
\NewDocumentCommand{\perfSecParFlaw}{s}{%
    \IfBooleanTF#1{p}{P}erformance testing and security testing are subtypes of
    reliability testing \citep{ISO_IEC2023a} but \citet[p.~53]{Firesmith2015}
    lists all three separately.}
\def\parSheetTestFlaw{\refHelper \citetISTQB{} \multiAuthHelper{define} ``par
sheet testing'' as ``testing to determine that the game returns the correct
mathematical results to the screen, to the players' accounts, and to the casino
account''. This seems to refer to \ifnotpaper the specific example from
    \flawref{specific-istqb-a,specific-istqb-b} \else some specific example it
    does not cite \fi and could be a valid domain-specific test approach, but
this definition does not even seem specific to PAR sheets---``list[s] of all
the symbols on each reel of a slot machine'' \citep{Bluejay2024}---themselves!}
\NewDocumentCommand{\redBoxFlaw}{s}{%
    \IfBooleanTF#1{t}{T}he incorrect claim that ``white-box
    testing'', ``grey-box testing'', and ``black-box testing'' are
    synonyms for ``module testing'', ``integration testing'', and
    ``system testing'', respectively, \ifnotpaper (see
        \flawref{dubious-syns}) \fi casts doubt on the claim that
    ``red-box testing'' is a synonym for ``acceptance testing''
    \citep[p.~3]{SneedAndGöschl2000}\ifnotpaper\
        (see \flawref{dubious-red-box-syn})\fi.}

\NewDocumentCommand{\defLabelDistinct}{s}{%
    \IfBooleanTF#1{t}{T}erms can be thought of as definition-label pairs,
    but there is a meaningful distinction between definition flaws and label
    flaws}

% Used in parSyns tables
\def\ftrnote{Fault tolerance testing may also be a subapproach of
    reliability testing \ifnotpaper
        \citetext{\citealp[p.~375]{IEEE2017}; \citealp[p.~7\=/10]{SWEBOK2025}}%
    \else \cite[p.~7\=/10]{SWEBOK2025}, \cite[p.~375]{IEEE2017}%
    \fi, which is distinct from robustness testing \citep[p.~53]{Firesmith2015}.}
\def\specfn{%
    % Flaw count (MISS, SYNS): ISTQB | {IEEE2017}
    \refHelper \citetISTQB{} \multiAuthHelper{cite} \citet[p.~431]{IEEE2017}
    for \ifnotpaper their \else its \fi definition of ``functional testing''
    but \multiAuthHelper{exclude} the transitive synonym relationship
    (see \Cref{syn-rels}) \ifnotpaper they give \else it gives \fi to
    ``specification-based testing''.
    % Flaw count (CONTRA, SYNS): {IEEE2017} implied by {IEEE2021c} {IEEE2017} | {IEEE2022} {IEEE2021c} ISTQB
    % Assertion: {Kam2008} {vanVliet2000}
    These terms are also defined separately elsewhere \ifnotpaper
        (\citeyear[Fig.~2]{IEEE2022}; \citeyear[pp.~8, 49, 125]{IEEE2021c})\else
        \cite{IEEE2022}, \cite{IEEE2021c}\fi, further supporting that they are
    not synonyms.
}
\def\ucstn{%
    % Flaw count (CONTRA, SYNS): ISTQB | {IEEE2022}
    \refHelper \citet[Fig.~2]{IEEE2022} also \multiAuthHelper{list}
    ``use case testing'' and ``scenario testing'' separately, further
    supporting that these terms are not synonyms.}

%------------------------------------------------------------------------------
% For populating values from files
%------------------------------------------------------------------------------

\ExplSyntaxOn
\ior_new:N \g_hringriin_file_stream

\NewDocumentCommand{\ReadFile}{mm}
{
    \hringriin_read_file:nn { #1 } { #2 }
    \cs_new:Npn #1 ##1
    {
        \str_if_eq:nnTF { ##1 } { * }
        { \seq_count:c { g_hringriin_file_ \cs_to_str:N #1 _seq } }
        { \seq_item:cn { g_hringriin_file_ \cs_to_str:N #1 _seq } { ##1 } }
    }
}

\cs_new_protected:Nn \hringriin_read_file:nn
{
    \ior_open:Nn \g_hringriin_file_stream { #2 }
    \seq_gclear_new:c { g_hringriin_file_ \cs_to_str:N #1 _seq }
    \ior_map_inline:Nn \g_hringriin_file_stream
    {
        \seq_gput_right:cx
        { g_hringriin_file_ \cs_to_str:N #1 _seq }
        { \tl_trim_spaces:n { ##1 } }
    }
    \ior_close:N \g_hringriin_file_stream
}

\ExplSyntaxOff

% Define/read values for Undefined Terms methodology for reuse and calculation!
\ReadFile{\undefTermCounts}{assets/misc/undefTermCounts}

\newcount\TotalBefore
\newcount\UndefBefore
\newcount\TotalAfter
\newcount\UndefAfter

\TotalBefore=\undefTermCounts{1}
\UndefBefore=\undefTermCounts{2}
\TotalAfter=\undefTermCounts{3}
\UndefAfter=\undefTermCounts{4}

\def\approachCount{\undefTermCounts{3}}

\ReadFile{\qualityCounts}{build/qualityCount}
\def\qualityCount{\qualityCounts{1}}

\ReadFile{\orphanCounts}{build/futureOrphanCount}
\def\orphanCount{\orphanCounts{1}}

\ReadFile{\uncatCounts}{build/uncatCount}
\def\uncatCount{\uncatCounts{1}}

\ReadFile{\multiCatCounts}{build/multiCatCounts}
\def\multiCatCount{\multiCatCounts{1}}
\def\multiCatMax{\multiCatCounts{2}}
\def\multiCatMaxCount{\multiCatCounts{3}}

\ReadFile{\multiSynCounts}{build/multiSynCounts}
\def\multiSynCount{\multiSynCounts{1}}

\ReadFile{\parSynCounts}{build/parSynCounts}
\def\parSynCount{\parSynCounts{1}}
\def\selfParCount{\parSynCounts{2}}

\ReadFile{\stdSources}{build/stdSources}
\ReadFile{\metaSources}{build/metaSources}
\ReadFile{\textSources}{build/textSources}
\ReadFile{\paperSources}{build/paperSources}

\def\srcCount{\the\numexpr\stdSources{3} + \metaSources{3} + \textSources{3} + \paperSources{3}}
\def\undefPerc{\the\numexpr 100 * \UndefAfter / \TotalAfter}

\ReadFile{\stdFlawDmnBrkdwn}{build/stdFlawDmnBrkdwn}
\ReadFile{\metaFlawDmnBrkdwn}{build/metaFlawDmnBrkdwn}
\ReadFile{\textFlawDmnBrkdwn}{build/textFlawDmnBrkdwn}
\ReadFile{\paperFlawDmnBrkdwn}{build/paperFlawDmnBrkdwn}
\ReadFile{\totalFlawDmnBrkdwn}{build/totalFlawDmnBrkdwn}

\ReadFile{\stdFlawMnfstBrkdwn}{build/stdFlawMnfstBrkdwn}
\ReadFile{\metaFlawMnfstBrkdwn}{build/metaFlawMnfstBrkdwn}
\ReadFile{\textFlawMnfstBrkdwn}{build/textFlawMnfstBrkdwn}
\ReadFile{\paperFlawMnfstBrkdwn}{build/paperFlawMnfstBrkdwn}
\ReadFile{\totalFlawMnfstBrkdwn}{build/totalFlawMnfstBrkdwn}

\def\flawCount{\totalFlawMnfstBrkdwn{13}}

\def\stds{\nameref{stds}}
\def\metas{\nameref{metas}}
\def\texts{\nameref{texts}}
\NewDocumentCommand{\papers}{s}{%
    \IfBooleanTF{#1}{\hyperref[papers]{Papers and Others}}{\nameref{papers}}%
}

\def\srcTier{\hyperref[source-tiers]{Source Tier}}

\input{build/FlawDmnMacros}
\input{build/FlawMnfstMacros}

% Assisted by GitHub Copilot
\newcommand\macro[2][]{\texttt{\textbackslash#2\{#1\}}}

%------------------------------------------------------------------------------
% TODOs
%------------------------------------------------------------------------------

% Generic Inlined TODOs
\newcommand{\intodo}[1]{\todo[inline]{#1}}

% Unimportant TODOs for "later" (i.e., finishing touches or changes immediately before submission)
\newcommand{\latertodo}[1]{\todo[backgroundcolor=Cyan]{\textit{Later}: #1}}

% "Important" TODOs
\newcommand{\imptodo}[1]{\todo[inline,backgroundcolor=Red]{\textbf{Important}: #1}}

% "Easy" TODOs
\newcommand{\easytodo}[1]{\todo[inline,backgroundcolor=SeaGreen]{\textit{Easy}: #1}}
\newcommand{\eztodo}[1]{\easytodo{#1}}

% "Tedious" TODOs
\newcommand{\tedioustodo}[1]{\todo[inline,backgroundcolor=PineGreen]{\textit{Needs time}: #1}}

% "Question" TODO Notes
\newcounter{todonoteQuestionsCtr}
\newcommand{\questiontodo}[1]{\stepcounter{todonoteQuestionsCtr}\todo[backgroundcolor=Lavender]{\textbf{Q \#\thetodonoteQuestionsCtr{}}: #1}}
\newcommand{\qtodo}[1]{\questiontodo{#1}}

% Specific categories of TODOs
\def\utd{\latertodo{Ensure this is up to date}}

%------------------------------------------------------------------------------
% Link to Drasil issue
%------------------------------------------------------------------------------

\newcommand{\issueref}[1]{\href{https://github.com/JacquesCarette/Drasil/issues/#1}{\##1}}
\newcommand{\pullref}[1]{\href{https://github.com/JacquesCarette/Drasil/pull/#1}{\##1}}
\newcommand{\thesisissuerefhelper}[1]{\href{https://github.com/samm82/TestingTesting/issues/#1}{\##1}}

\ExplSyntaxOn

% Based on output from ChatGPT
\NewDocumentCommand{\mapthesisissueref}{m}
{
    % Clear temporary sequences to store transformed items
    \seq_clear:N \l_tmpa_seq
    \seq_clear:N \l_tmpb_seq

    \seq_set_split:Nnn \l_tmpa_seq { , } { #1 } % Split the input by commas
    \seq_map_inline:Nn \l_tmpa_seq
    {
        \seq_put_right:Nn \l_tmpb_seq {\thesisissuerefhelper{##1}}
    }
    \seq_use:Nnnn \l_tmpb_seq { ~and~ } { ,~ } { ,~and~ }
}

\ExplSyntaxOff

\newcommand{\thesisissuetodo}[1]{\todo[backgroundcolor=lightgray]{See \mapthesisissueref{#1}}}
\newcommand{\thesisissuenote}[1]{\ifnotpaper\footnote{Discussed in \mapthesisissueref{#1}.}\fi}