API Reference

Library Scope: GLOBAL

Robot Framework library for interactive C++ execution using Clang-REPL (via xeus-cpp).

This library allows you to write, execute, and test C++ code snippets directly within Robot Framework test suites. It relies on a Jupyter kernel (specifically xeus-cpp) to maintain a persistent C++ interpreter session.

Key Features:

JIT Compilation: Immediate execution of C++ code without linking or main() replacement.
Modern C++: Full support for C++20 and C++23 standards.
Cross-Platform: Pipelines tested and fully functional on Linux, Windows, and macOS.
Easy Integration: Available via Conda/Pixi for clean dependency management (Clang, xeus-cpp, etc.).

Basic Usage Example:

*** Settings ***
Library    clang

*** Test Cases ***
Example Test
    Start Kernel
    Source Exec        int answer = 42;
    ${result}=         Source Exec        std::cout << answer;
    Should Be Equal    ${result}    42
    Shutdown Kernel

Add Include Path 

Arguments: *paths

Adds directories to the C++ include search path (equivalent to -I flag).

Paths added here are used by Start Kernel (at startup) and Source Include (to resolve header files).

Must be called before Start Kernel.

Arguments:

paths: One or more directory paths to add.

Example:

Add Include Path | /opt/mylib/include | ${CURDIR}/../include |

Add Link Directory 

Arguments: *paths

Adds directories to the linker search path (equivalent to -L flag).

Must be called before Start Kernel.

Arguments:

paths: One or more directory paths to add.

Assert 

Arguments: cond, otherwise=None

Evaluates a C++ boolean condition and fails the test if it is false.

Arguments:

cond: A string containing a C++ expression that evaluates to bool.
otherwise: Optional message or value to include in the error if the assertion fails.

Example:

Source Exec | int x = 5; |
Assert | x > 0 | Context: x should be positive |
Assert | x == 5 |

Call Function 

Arguments: func, *params

Calls a global C++ function with the provided arguments and returns its output.

Arguments:

func: Name of the function to call.
params: Arguments to pass to the function.

Example:

Source Exec | int add(int a, int b) {{ return a + b; }} |

${res}= | Call Function | add | 2 | 3 |

Get Value 

Arguments: obj_expression

Retrieves the string representation of a C++ expression/variable.

Basically executes std::cout << (expression) and returns the result.

Arguments:

obj_expressionencode: The C++ variable or expression to evaluate.

Example:

Source Exec | int x = 100; |
${val}= | Get Value | x * 2 |
Should Be Equal | ${val} | 200 |

Link Libraries 

Arguments: *libs

Specifies libraries to link against at startup (equivalent to -l flag).

Must be called before Start Kernel.

Arguments:

libs: Names of libraries (e.g., m for libm, pthread).

Load Shared Library 

Arguments: *libraries

Loads a shared object (.so) or dynamic library (.dylib/dll) into the process via dlopen.

This allows calling functions from shared libraries that are not linked at startup. Ensure symbols are loaded with global visibility (RTLD_GLOBAL).

Arguments:

libraries: Paths or names of libraries to load.

Example:

Load Shared Library | /usr/lib/libm.so |

Nullptr 

Returns the string nullptr.

Helper to represent the null pointer in keyword arguments.

Shutdown Kernel 

Stops the running C++ kernel and cleans up resources.

This also clears the accumulated include paths and link settings.

Source Exec 

Arguments: *parts, timeout=30

Executes C++ code and returns the standard output.

This is the primary keyword for interacting with the REPL. If the C++ code prints to std::cout, that output is captured and returned. If the code throws an exception or fails to compile, the test fails.

Arguments:

parts: One or more strings constituting the C++ code to run.
timeout: Maximum time (seconds) to wait for kernel response. Default 30s.

Returns:

The captured stdout as a string, stripped of trailing whitespace.

Example:

${out}= | Source Exec | std::cout << “Hello”; |

Source File 

Arguments: path

Reads a C++ source file and executes its content in the REPL.

Arguments:

path: Path to the C++ source file (.cpp, .h, etc.).

Example:

Source File | ${CURDIR}/my_impl.cpp |

Source Include 

Arguments: *files

Includes header files in the current session.

This keyword attempts to resolve the provided file names. If a file is not found in the current directory, it searches through the paths added via Add Include Path and uses an absolute path if a match is found.

Arguments:

files: Names of the header files to include (e.g., vector, myheader.h).

Example:

Source Include | vector | map |

Source Parse 

Arguments: *parts

Defines C++ code structure (declarations) without expecting output.

Useful for defining classes, functions, or globals. Alias for Source Exec.

Arguments:

parts: Lines of C++ code.

Start Kernel 

Arguments: kernel_name=xcpp20

Starts the Clang-REPL kernel (Xeus-cpp) in a subprocess.

This keyword must be called before executing any C++ code. It initializes the standard library and prepares the environment.

Arguments:

kernel_name: The name of the Jupyter kernel to use. Defaults to xcpp20. Ensure this kernel is installed in your environment (jupyter kernelspec list).

Example:

Start Kernel | kernel_name=xcpp17 |

Typeid 

Arguments: expression

Returns the mangled C++ type name of an expression (using typeid(...).name()).

Arguments:

expression: The object or type to inspect.

Typename 

Arguments: expression

Returns the demangled (human-readable) C++ type name of an expression.

Uses abi::__cxa_demangle internally.

Arguments:

expression: The object or type to inspect.

Example:

${name}= | Typename | std::string(“foo”) |

Should Contain | ${name} | string |