component---src-docs-cpp-stubs-md-9672adf8e1c77a7d3da2.js.map

{"version":3,"file":"component---src-docs-cpp-stubs-md-9672adf8e1c77a7d3da2.js","mappings":"8RAMaA,EAAe,CAAC,OAAE,6NAC/B,IAAMC,EAAc,CAClBD,aAAAA,GAEIE,EAAYC,EAAAA,EACH,SAASC,EAAW,GAGhC,IAFDC,EAAU,EAAVA,WACGC,GAAK,YAER,OAAO,QAACJ,GAAS,UAAKD,EAAiBK,EAAK,CAAED,WAAYA,EAAYE,QAAQ,eAG5E,cACE,GAAM,SAAO,UAEf,4FACA,2BACE,aAAGC,WAAW,cAAY,MAAO,kBAAQA,WAAW,KAAG,UACvD,aAAGA,WAAW,eAAa,kBAAQA,WAAW,KAAG,QAAkB,oLAGrE,cACE,GAAM,uBAAqB,wBAE7B,uJAEA,kEAAoD,sBAAYA,WAAW,KAAG,4CAA0D,gRAGxI,oBAAK,gBAAMA,WAAW,OAAK,iGAO3B,mDAAqC,sBAAYA,WAAW,KAAG,OAAqB,yBAAyB,sBAAYA,WAAW,KAAG,UAAwB,2EACpJ,sBAAYA,WAAW,KAAG,OAAqB,UAAU,sBAAYA,WAAW,KAAG,OAAqB,wBAAwB,sBAAYA,WAAW,KAAG,OAAqB,UAAU,sBAAYA,WAAW,KAAG,OAAqB,iCAAiC,sBAAYA,WAAW,KAAG,OAAqB,oGACvP,sBAAYA,WAAW,KAAG,OAAqB,yCACtH,sBAAYA,WAAW,KAAG,aAA2B,iBAAiB,aAAGA,WAAW,IACrF,KAAQ,uCAAqC,YAC5B,MACrB,cACE,GAAM,qBAAmB,sBAE3B,gDAAkC,sBAAYA,WAAW,KAAG,eAA6B,4DACvF,sBAAYA,WAAW,KAAG,uCAAqD,eAC/E,aAAGA,WAAW,IACZ,KAAQ,iFAA+E,mBAC/D,MAC5B,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,2iBA4B/B,6KAEA,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,8BAG/B,gCAAkB,sBAAYA,WAAW,KAAG,aAA2B,gHAC3D,sBAAYA,WAAW,KAAG,aAA2B,gEACjE,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,0HAK/B,6EACA,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,gCAG/B,iPAEA,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,oCAG/B,+CAAiC,sBAAYA,WAAW,KAAG,aAA2B,wIAEtF,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,wOAS/B,cACE,GAAM,gBAAc,iBAEtB,qSAGA,2BACE,aAAGA,WAAW,cAAY,MAAO,kBAAQA,WAAW,KAAG,UACvD,aAAGA,WAAW,cAAY,kOAE5B,cACE,GAAM,oBAAkB,qBAE1B,oJAEA,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,8xBAyC/B,0BAAY,sBAAYA,WAAW,KAAG,6BAA2C,6BAA6B,sBAAYA,WAAW,KAAG,oBAAkC,oBAC1K,cACE,GAAM,mBAAiB,oBAEzB,oLACsC,sBAAYA,WAAW,KAAG,aAA2B,4CAC3F,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,4UAmB/B,qHACG,sBAAYA,WAAW,KAAG,gCAA8C,MAC3E,oaAIA,oBAAK,gBAAMA,WAAW,MAClB,UAAa,gBAAc,mlBA8B/B,qCAAuB,sBAAYA,WAAW,KAAG,oBAAkC,2LAIvF,CAAC,oNAEDJ,EAAWK,gBAAiB,C","sources":["webpack://unittestbot-web/./src/docs/cpp/stubs.md"],"sourcesContent":["import * as React from 'react'\n  /* @jsx mdx */\nimport { mdx } from '@mdx-js/react';\n/* @jsxRuntime classic */\n/* @jsx mdx */\nimport DefaultLayout from \"/home/runner/work/utbot-site-staging/utbot-site-staging/node_modules/gatsby-theme-docz/src/base/Layout.js\";\nexport const _frontmatter = {};\nconst layoutProps = {\n  _frontmatter\n};\nconst MDXLayout = DefaultLayout;\nexport default function MDXContent({\n  components,\n  ...props\n}) {\n  return <MDXLayout {...layoutProps} {...props} components={components} mdxType=\"MDXLayout\">\n\n\n    <h1 {...{\n      \"id\": \"stubs\"\n    }}>{`Stubs`}</h1>\n    <p>{`Here we describe how stubs are generated and what they are needed for.`}</p>\n    <blockquote>\n      <p parentName=\"blockquote\">{`📝`}<strong parentName=\"p\">{`Note`}</strong></p>\n      <p parentName=\"blockquote\"><strong parentName=\"p\">{`Stub`}</strong>{` is a function which emulates behavior of another function it is written for.\nIt's often useful to write stubs for functions from another module that you don't want to test.`}</p>\n    </blockquote>\n    <h3 {...{\n      \"id\": \"when-stubs-are-used\"\n    }}>{`When stubs are used`}</h3>\n    <p>{`UTBot generates stubs for every function in the project first time you open it and synchronize each time before test\ngeneration.`}</p>\n    <p>{`First time you open the project you will see `}<inlineCode parentName=\"p\">{`UTBot is generating stubs for project...`}</inlineCode>{` message. It means that for each\nfile in your project UTBot generates file which contains all non-static functions signatures from the source file. Stubs\ncan be used as substitutes for calling functions from another module. Consider the following project structure:`}</p>\n    <pre><code parentName=\"pre\" {...{}}>{`executable\n|---- lib1.a\n|     |---- A.c\n|     +---- B.c\n|---- lib2.a\n|     |---- C.c\n`}</code></pre>\n    <p>{`If we run test generation for `}<inlineCode parentName=\"p\">{`C.c`}</inlineCode>{`, all functions from `}<inlineCode parentName=\"p\">{`lib1.a`}</inlineCode>{` will be replaced with their stubs on build step. So, if\nthe function `}<inlineCode parentName=\"p\">{`foo`}</inlineCode>{` from `}<inlineCode parentName=\"p\">{`C.c`}</inlineCode>{` calls the function `}<inlineCode parentName=\"p\">{`bar`}</inlineCode>{` from `}<inlineCode parentName=\"p\">{`A.c`}</inlineCode>{`, then stub for the function `}<inlineCode parentName=\"p\">{`bar`}</inlineCode>{` will be invoked\ninstead. Note that you can still generate tests using the exact definition of `}<inlineCode parentName=\"p\">{`bar`}</inlineCode>{`; for that, you will need to\nunmark `}<inlineCode parentName=\"p\">{`Use Stubs`}</inlineCode>{` checkbox in `}<a parentName=\"p\" {...{\n        \"href\": \"vscode-extension-settings#use-stubs\"\n      }}>{`settings`}</a>{`.`}</p>\n    <h3 {...{\n      \"id\": \"stub-file-example\"\n    }}>{`Stub file example`}</h3>\n    <p>{`Stub files can be found in `}<inlineCode parentName=\"p\">{`tests/stubs`}</inlineCode>{` folder. This is an example of stub file generated\nfor `}<inlineCode parentName=\"p\">{`c-example/lib/dependent_functions.c`}</inlineCode>{` from\nthe `}<a parentName=\"p\" {...{\n        \"href\": \"https://github.com/UnitTestBot/UTBotCpp/tree/main/integration-tests/c-example\"\n      }}>{`example project`}</a>{`:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`// 1624618650000000000\n// Please, do not change the line above\n\n#ifdef\nKLEE_MODE\nextern void klee_make_symbolic(void *addr, unsigned long long nbytes, const char *name);\n#endif\n#include\n\"dependent_functions_stub.h\"\n\n#define\nNULL ((void*)0)\n\nint double_max_symbolic;\nint double_max(int a, int b) {\nstatic int firstTimeCall = 1;\n#ifdef\nKLEE_MODE\nif (firstTimeCall == 1) {\nfirstTimeCall = 0;\nklee_make_symbolic(&double_max_symbolic, sizeof(double_max_symbolic), \"double_max_symbolic\");\n}\n#endif\nreturn double_max_symbolic;\n}\n\n`}</code></pre>\n    <p>{`The first line contains timestamp of stub file creation. It is required for synchronization with the source code, so,\nplease, do not modify this line:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`// 1619438023000000000\n`}</code></pre>\n    <p>{`Then, if a `}<inlineCode parentName=\"p\">{`KLEE_MODE`}</inlineCode>{` macro is passed during preprocessing, we add a KLEE declaration to allow us to use symbolic\nreturn value. `}<inlineCode parentName=\"p\">{`KLEE_MODE`}</inlineCode>{` serves for both test generation and test running purposes.`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`#ifdef KLEE_MODE\nextern void klee_make_symbolic(void *addr, unsigned long long nbytes, const char *name);\n#endif\n`}</code></pre>\n    <p>{`This variable stores return value of the stub function:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`int double_max_symbolic;\n`}</code></pre>\n    <p>{`Stub function signature is always the same as the signature of the source function. If it's not (for example, if the\nfunction was modified), then UTBot will synchronize them by rewriting stub function with the new one:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`int double_max(int a, int b)\n`}</code></pre>\n    <p>{`If UTBot uses stubs, then `}<inlineCode parentName=\"p\">{`KLEE_MODE`}</inlineCode>{` is defined, and the return value is made symbolic. This way KLEE can decide what\nvalues to return to satisfy the execution paths:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`static int firstTimeCall = 1;\n#ifdef KLEE_MODE\n    if (firstTimeCall == 1) {\n        firstTimeCall = 0;\n        klee_make_symbolic(&double_max_symbolic, sizeof(double_max_symbolic), \"double_max_symbolic\");\n    }\n#endif\n`}</code></pre>\n    <h3 {...{\n      \"id\": \"stub-headers\"\n    }}>{`Stub headers`}</h3>\n    <p>{`For each stub, a header is generated. It contains definitions of types and structures used in function headers, allowing\nstubs to be compilable. Stub headers may contain definitions fetched from system headers and may look obscure, but\nusually you will not modify them.`}</p>\n    <blockquote>\n      <p parentName=\"blockquote\">{`📝`}<strong parentName=\"p\">{`Note`}</strong></p>\n      <p parentName=\"blockquote\">{`You can change the stub function body however you want. UTBot saves custom code inside the function while synchronizing. However, if the source function signature changes, then stub function will be completely rewritten.`}</p>\n    </blockquote>\n    <h3 {...{\n      \"id\": \"tests-with-stubs\"\n    }}>{`Tests with stubs`}</h3>\n    <p>{`For the tests that use stubs, the return values are generated in a such way that the code coverage is maximized. For\nexample:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`extern \"C\" char pointerToPointer_symbolic;\n\nTEST(regression, calc_two_numbers_f_test_1)\n{\n    // Initialize symbolic stubs\n    pointerToPointer_symbolic = '\\\\x10';\n\n    // Construct input\n    char a = 'c';\n    char b = 'p';\n\n    // Expected output\n    int expected = 2;\n\n    // Trigger the function\n    int actual = calc_two_numbers_f(a, b);\n\n    // Check results\n    EXPECT_EQ(expected, actual);\n}\n\nTEST(regression, calc_two_numbers_f_test_2)\n{\n    // Initialize symbolic stubs\n    pointerToPointer_symbolic = 'b';\n\n    // Construct input\n    char a = 'c';\n    char b = 'b';\n\n    // Expected output\n    int expected = 1;\n\n    // Trigger the function\n    int actual = calc_two_numbers_f(a, b);\n\n    // Check results\n    EXPECT_EQ(expected, actual);\n}\n`}</code></pre>\n    <p>{`Here `}<inlineCode parentName=\"p\">{`pointerToPointer_symbolic`}</inlineCode>{` stores return value for `}<inlineCode parentName=\"p\">{`pointerToPointer`}</inlineCode>{` stub function.`}</p>\n    <h3 {...{\n      \"id\": \"modifying-stubs\"\n    }}>{`Modifying stubs`}</h3>\n    <p>{`As it was noted, it is easy to rewrite UTBot stubs into anything you want them to be. You should modify only function\nbodies and not touch header include, or `}<inlineCode parentName=\"p\">{`KLEE_MODE`}</inlineCode>{` ifdefs. Consider the simplest example:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`// 1624618650000000000\n// Please, do not change the line above\n\n#ifdef\nKLEE_MODE\nextern void klee_make_symbolic(void *addr, unsigned long long nbytes, const char *name);\n#endif\n#include\n\"dependent_functions_stub.h\"\n\n#define\nNULL ((void*)0)\n\nint double_max_symbolic;\nint double_max(int a, int b) {\nreturn a;\n}\n`}</code></pre>\n    <p>{`In such a case, UTBot will generate tests for functions from other CMake modules implying\nthat `}<inlineCode parentName=\"p\">{`double_max(int a, int b) = a`}</inlineCode>{`.`}</p>\n    <p>{`However, you can also use symbolic variable power when modifying stubs. Suppose that you want your function not to\nreturn any value, but perform some checks on the arguments prior to that. Also, there may be a special case in that\nfunction that is highly important to be reflected in the stub. In that case, you can insert those checks in the stub,\nand, if they succeed, return a symbolic value:`}</p>\n    <pre><code parentName=\"pre\" {...{\n        \"className\": \"language-cpp\"\n      }}>{`// 1624618650000000000\n// Please, do not change the line above\n\n#ifdef\nKLEE_MODE\nextern void klee_make_symbolic(void *addr, unsigned long long nbytes, const char *name);\n#endif\n#include\n\"dependent_functions_stub.h\"\n\n#define\nNULL ((void*)0)\n\nint double_max_symbolic;\nint double_max(int a, int b) {\nif (a == 100 && a > b) {\nreturn 100;\n}\nstatic int firstTimeCall = 1;\n#ifdef\nKLEE_MODE\nif (firstTimeCall == 1) {\nfirstTimeCall = 0;\nklee_make_symbolic(&double_max_symbolic, sizeof(double_max_symbolic), \"double_max_symbolic\");\n}\n#endif\nreturn double_max_symbolic;\n}\n`}</code></pre>\n    <p>{`By this change, `}<inlineCode parentName=\"p\">{`double_max(a, b)`}</inlineCode>{` will preserve its behaviour if a certain condition holds. This principle can be used\nto achieve the similarity of the stub and the original code while leaving out big parts of code.`}</p>\n\n    </MDXLayout>;\n}\n;\nMDXContent.isMDXComponent = true;\n      "],"names":["_frontmatter","layoutProps","MDXLayout","DefaultLayout","MDXContent","components","props","mdxType","parentName","isMDXComponent"],"sourceRoot":""}