Skip to content

Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.

UI tests that drive the real app; keep side panels on screen

islandmedbb287cadaed5
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5907e531..546c1bcf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,7 +42,20 @@ jobs:
- name: Build
run: cmake --build build --config Release --parallel
- name: Test (C++ and Python API)
- run: ctest --test-dir build -C Release --output-on-failure
+ run: ctest --test-dir build -C Release --output-on-failure -LE ui
+ - name: UI tests (real app, Xvfb + Mesa)
+ if: runner.os == 'Linux'
+ run: |
+ sudo apt-get install -y xvfb libgl1-mesa-dri
+ xvfb-run -a -s "-screen 0 1920x1080x24" env LIBGL_ALWAYS_SOFTWARE=1 \
+ ctest --test-dir build -C Release --output-on-failure -L ui
+ - name: UI test screenshots
+ if: always() && runner.os == 'Linux'
+ uses: actions/upload-artifact@v4
+ with:
+ name: ui-shots-${{ matrix.os }}
+ path: build/ui-shots
+ if-no-files-found: ignore
# VFX Reference Platform (vfxplatform.com): GCC 14.2 with glibc 2.28 (CY2026, EL8)
# or glibc 2.34 (CY2027, EL9), C++20, Python 3.13.
@@ -73,7 +86,7 @@ jobs:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DSCULPTFORGE_USE_SYSTEM_SDL=OFF \
-DSCULPTFORGE_BUILD_PYTHON=ON -DPython_EXECUTABLE="$PYTHON313"
cmake --build build --parallel
- ctest --test-dir build --output-on-failure
+ ctest --test-dir build --output-on-failure -LE ui
- name: Check binary compatibility (glibc <= ${{ matrix.glibc }})
run: |
for f in build/sculptforge build/sculptforge-cli build/sculptforge*.so; do
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e1ea1b78..7db28561 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ All notable changes to SculptForge are listed here. The format follows
## [Unreleased]
+### Fixed
+- Side panels (Brush Lab, Tools, Generate 3D...) never grow past the bottom of the window. They move up
+ and scroll instead, so expanded sections such as AI provider are always reachable.
+
+### Development
+- UI tests: `sculptforge --ui-test script.sfui` drives the real interface (clicks, typing, strokes,
+ shortcuts), checks what it shows and saves screenshots. They run in CI on Linux.
+
### AI
- Brush Lab is free out of the box: the new default **Free** provider uses an open model hosted by
Pollinations.ai with no account or key, and falls back to a running local Ollama. Key-less Anthropic
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 0b35f97d..69e63a53 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -115,6 +115,7 @@ if(SCULPTFORGE_BUILD_APP)
src/app/main.cpp
src/app/App.cpp
src/app/Demo.cpp
+ src/app/UiTest.cpp
src/app/PanelMasking.cpp
src/app/PanelPolygroups.cpp
src/app/PanelBrushes.cpp
@@ -285,4 +286,15 @@ if(SCULPTFORGE_BUILD_TESTS)
target_compile_options(sculptforge_tests PRIVATE /utf-8)
endif()
add_test(NAME sculptforge_tests COMMAND sculptforge_tests)
+
+ # UI tests: each tests/ui/*.sfui script drives the real app headless (needs an
+ # OpenGL 3.3 context; CI runs them on Linux under Xvfb with Mesa). Label "ui".
+ if(SCULPTFORGE_BUILD_APP)
+ file(GLOB SCULPTFORGE_UI_TESTS CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/tests/ui/*.sfui)
+ foreach(script ${SCULPTFORGE_UI_TESTS})
+ get_filename_component(name ${script} NAME_WE)
+ add_test(NAME ui_${name} COMMAND sculptforge --ui-test ${script} --ui-out ${CMAKE_CURRENT_BINARY_DIR}/ui-shots/${name})
+ set_tests_properties(ui_${name} PROPERTIES LABELS ui TIMEOUT 300)
+ endforeach()
+ endif()
endif()
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 34d9d017..49022b3b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,6 +33,24 @@ See [README.md#building](README.md#building). On Linux, `packaging/linux/install
build dependencies. `ctest` runs the unit tests; `cpack` in the build folder makes the platform's packages.
Releases are built by `.github/workflows/release.yml` when a `v*` tag is pushed.
+### UI tests
+
+UI changes need a UI test. `tests/ui/*.sfui` scripts drive the real app the way a person does: they click
+buttons by their labels, type into fields, draw brush strokes, press shortcuts, and then check the result
+(on-screen text, the status bar, mesh values). They also save screenshots, so you can look at what the
+test saw.
+
+```sh
+./build/sculptforge --ui-test tests/ui/sculpt_basics.sfui --ui-out /tmp/shots # one script
+ctest --test-dir build -L ui # all of them
+```
+
+The step reference is at the top of `src/app/UiTest.cpp`. Tests run headless on simulated time, so most
+take under a second. They use a throwaway settings folder and never touch your own. A failing step stops
+the script and saves `FAIL-line-N.png`, and clicking a missing item lists similarly named items. Clicks
+scroll panels as needed, and clicking an item a person couldn't reach (off screen) fails. CI runs the UI
+tests on Linux under Xvfb and uploads the screenshots as an artifact.
+
## Demo videos
The website's videos are real recordings made by the app itself:
diff --git a/src/app/App.cpp b/src/app/App.cpp
index 2f234448..f4e50028 100644
--- a/src/app/App.cpp
+++ b/src/app/App.cpp
@@ -88,7 +88,7 @@ App::~App() = default;
bool App::init(const AppOptions& options) {
options_ = options;
- const bool recording = !options.recordPath.empty();
+ const bool recording = !options.recordPath.empty() || !options.uiTest.empty();
const bool headless = !options.renderPath.empty() || recording;
if (!SDL_Init(SDL_INIT_VIDEO)) {
SDL_Log("SDL_Init failed: %s", SDL_GetError());
@@ -278,14 +278,83 @@ int App::renderHeadless() {
return 0;
}
+int App::runUiTest(int w, int h, int fps) {
+ // Same frame loop as a recording, but frames are only read back for screenshots.
+ std::vector<uint8_t> rgba;
+ std::string err;
+ const float dt = 1.0f / float(fps);
+ int frames = 0;
+ bool finalFrame = false;
+ while (frames < fps * 60 * 30) {
+ SDL_Event e;
+ while (SDL_PollEvent(&e)) {
+ } // the script provides all input
+ if (demo_->finished()) {
+ if (finalFrame) break;
+ finalFrame = true; // one more frame, for a failure screenshot
+ }
+ demo_->update(dt);
+ processPendingFiles();
+ animateLayers(dt);
+ pollBrushRequest();
+ pollUnreal();
+ pollGenerator();
+ camera_.aspect = float(w) / float(h);
+
+ Demo::beginFrame();
+ ImGui_ImplOpenGL3_NewFrame();
+ ImGui_ImplSDL3_NewFrame();
+ ImGuiIO& io = ImGui::GetIO();
+ io.DisplaySize = ImVec2(float(w), float(h));
+ io.DisplayFramebufferScale = ImVec2(1.0f, 1.0f);
+ io.DeltaTime = dt;
+ ImGui::NewFrame();
+ ImGui::LogToBuffer(0); // capture every drawn string (0: don't auto-open tree nodes)
+ drawUi();
+ if (ImGuiContext* g = ImGui::GetCurrentContext()) demo_->setFrameText(g->LogBuffer.c_str());
+ ImGui::LogFinish();
+ ImGui::Render();
+
+ Mesh& shown = displayedMesh();
+ if (&shown != lastDisplayed_) shown.topologyDirty = true;
+ lastDisplayed_ = &shown;
+ renderer_.sync(shown);
+ renderer_.syncSplats(doc_.splats, doc_.splatsVersion);
+ ++frames;
+ const std::string shot = demo_->takeShotRequest();
+ if (shot.empty()) continue;
+ if (!renderer_.beginCapture(w, h, err)) {
+ SDL_Log("%s", err.c_str());
+ return 1;
+ }
+ renderer_.draw(camera_, w, h, renderSettings_);
+ ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
+ renderer_.endCapture(rgba);
+ Image img;
+ img.width = w;
+ img.height = h;
+ img.rgba = rgba;
+ for (size_t i = 3; i < img.rgba.size(); i += 4) img.rgba[i] = 255;
+ if (!img.savePng(shot, err)) SDL_Log("%s", err.c_str());
+ else SDL_Log("Screenshot %s", shot.c_str());
+ }
+ for (const auto& f : demo_->failures()) std::fprintf(stderr, "FAIL %s\n", f.c_str());
+ if (demo_->failures().empty())
+ std::printf("PASS %s (%d frames)\n", options_.uiTest.c_str(), frames);
+ return demo_->failures().empty() ? 0 : 1;
+}
+
int App::runRecording() {
demo_ = std::make_unique<Demo>(*this);
std::string err;
- if (!demo_->load(options_.demo.empty() ? "sculpt" : options_.demo, err)) {
+ const bool testing = !options_.uiTest.empty();
+ if (testing ? !demo_->loadScript(options_.uiTest, err)
+ : !demo_->load(options_.demo.empty() ? "sculpt" : options_.demo, err)) {
SDL_Log("%s", err.c_str());
return 1;
}
const int w = options_.width, h = options_.height, fps = std::max(options_.fps, 1);
+ if (testing) return runUiTest(w, h, fps);
// Frames go straight to ffmpeg as raw RGBA.
std::string cmd = "ffmpeg -loglevel error -y -f rawvideo -pix_fmt rgba -s " + std::to_string(w) + "x" + std::to_string(h) +
" -r " + std::to_string(fps) +
@@ -356,7 +425,7 @@ int App::runRecording() {
int App::run() {
if (!options_.renderPath.empty()) return renderHeadless();
- if (!options_.recordPath.empty()) return runRecording();
+ if (!options_.recordPath.empty() || !options_.uiTest.empty()) return runRecording();
Uint64 lastTicks = SDL_GetTicksNS();
while (running_) {
Uint64 now = SDL_GetTicksNS();
@@ -728,6 +797,7 @@ void App::runCommand(const std::string& name, const Args& args) {
if (name == "save_project") storeProjectSettings();
CommandResult r = commands_.execute(doc_, name, args);
status_ = r.message;
+ lastCommandOk_ = r.ok;
if (r.ok && name != "export_glb" && name != "export_lods" && name != "export_usd" && name != "export_fbx" &&
name != "export_unreal" && name.rfind("unreal_", 0) != 0 && name != "save_obj" && name != "save_project" &&
name != "mesh_info" && name.rfind("brush_", 0) != 0 && name.rfind("splat_", 0) != 0 && name != "mesh_to_splats" &&
@@ -1058,8 +1128,7 @@ void App::drawLayersPanel() {
const float scale = uiScale_;
const ImGuiViewport* vp = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + vp->Size.x - 290 * scale, vp->Pos.y + 34 * scale), ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(280 * scale, 0), ImVec2(280 * scale, FLT_MAX));
- if (!ImGui::Begin("Layers / Blend Shapes", nullptr, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Layers / Blend Shapes", nullptr, 280 * scale)) {
ImGui::End();
return;
}
@@ -1146,8 +1215,7 @@ void App::drawGameExportPanel() {
const ImGuiViewport* vp = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + vp->Size.x - 290 * scale, vp->Pos.y + 330 * scale),
ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(280 * scale, 0), ImVec2(280 * scale, FLT_MAX));
- if (!ImGui::Begin("Game Ready", nullptr, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Game Ready", nullptr, 280 * scale)) {
ImGui::End();
return;
}
@@ -1294,6 +1362,19 @@ void App::drawRecipeEditor(BrushRecipe& recipe) {
nullptr, false);
}
+bool App::beginPanel(const char* name, bool* open, float width) {
+ // Auto-sized panels grow with their content (an opened section, a long chat):
+ // never taller than the screen (they scroll instead), and never off its bottom edge.
+ const ImGuiViewport* vp = ImGui::GetMainViewport();
+ const float margin = 6.0f * uiScale_;
+ ImGui::SetNextWindowSizeConstraints(ImVec2(width, 0), ImVec2(width, std::max(100.0f, vp->WorkSize.y - 2 * margin)));
+ const bool visible = ImGui::Begin(name, open, ImGuiWindowFlags_AlwaysAutoResize);
+ const ImVec2 pos = ImGui::GetWindowPos(), size = ImGui::GetWindowSize();
+ const float bottom = vp->WorkPos.y + vp->WorkSize.y - margin;
+ if (pos.y + size.y > bottom) ImGui::SetWindowPos(ImVec2(pos.x, std::max(vp->WorkPos.y + margin, bottom - size.y)));
+ return visible;
+}
+
void App::drawAiSettings() {
using P = ai::AiSettings::Provider;
const char* providers[] = {"Free - no account or key", "Anthropic (Claude) - your key",
@@ -1361,28 +1442,35 @@ void App::drawAiSettings() {
textField("API key", aiSettings_.apiKey, ImGuiInputTextFlags_Password);
}
if (aiSettings_.provider == P::OpenAICompatible && modelsChecked_) {
- if (localModels_.error.empty())
- ImGui::TextColored(ImVec4(0.45f, 0.8f, 0.5f, 1), "Connected - %d model%s installed",
- int(localModels_.models.size()), localModels_.models.size() == 1 ? "" : "s");
+ const bool ok = localModels_.error.empty();
+ ImGui::PushStyleColor(ImGuiCol_Text, ok ? ImVec4(0.45f, 0.8f, 0.5f, 1) : ImVec4(0.95f, 0.6f, 0.4f, 1));
+ if (ok)
+ ImGui::TextWrapped("Connected - %d model%s installed", int(localModels_.models.size()),
+ localModels_.models.size() == 1 ? "" : "s");
else
- ImGui::TextColored(ImVec4(0.95f, 0.6f, 0.4f, 1), "%s", localModels_.error.c_str());
+ ImGui::TextWrapped("%s", localModels_.error.c_str());
+ ImGui::PopStyleColor();
}
if (aiSettings_.provider == P::OpenAICompatible && ImGui::TreeNode("Run a model on this computer")) {
// Steps for the platform we're on; the guide covers the others.
#if defined(_WIN32)
- ImGui::TextWrapped("1. Install Ollama: download it from ollama.com/download, or in PowerShell run\n"
- " winget install Ollama.Ollama\n"
- "2. In a terminal, run: ollama pull qwen3:4b-instruct\n"
+ ImGui::TextWrapped("1. Install Ollama from ollama.com/download, or in PowerShell:\n"
+ " winget install Ollama.Ollama\n"
+ "2. Download the model (in PowerShell):\n"
+ " ollama pull qwen3:4b-instruct\n"
"3. Ollama runs in the system tray. Click Ollama above, then Find models.");
#elif defined(__APPLE__)
- ImGui::TextWrapped("1. Install Ollama: download it from ollama.com/download and drag it to Applications.\n"
- "2. In Terminal, run: ollama pull qwen3:4b-instruct\n"
+ ImGui::TextWrapped("1. Install Ollama from ollama.com/download and drag it to Applications.\n"
+ "2. Download the model (in Terminal):\n"
+ " ollama pull qwen3:4b-instruct\n"
"3. Ollama runs in the menu bar. Click Ollama above, then Find models.");
#else
- ImGui::TextWrapped("1. Install Ollama: curl -fsSL https://ollama.com/install.sh | sh\n"
- " (or your package manager, e.g. sudo pacman -S ollama)\n"
- "2. Start it if needed: sudo systemctl enable --now ollama\n"
- "3. Run: ollama pull qwen3:4b-instruct\n"
+ ImGui::TextWrapped("1. Install Ollama (or use your package manager, e.g. sudo pacman -S ollama):\n"
+ " curl -fsSL https://ollama.com/install.sh | sh\n"
+ "2. Start it if needed:\n"
+ " sudo systemctl enable --now ollama\n"
+ "3. Download the model:\n"
+ " ollama pull qwen3:4b-instruct\n"
"4. Click Ollama above, then Find models.");
#endif
ImGui::TextWrapped("The 2.5 GB model needs about 4 GB of free memory and works without a graphics card "
@@ -1421,8 +1509,7 @@ void App::drawBrushLab() {
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + 270 * scale, std::max(vp->Pos.y + 34 * scale,
vp->Pos.y + vp->Size.y - 470 * scale)),
ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(420 * scale, 0), ImVec2(420 * scale, FLT_MAX));
- if (!ImGui::Begin("Brush Lab", &showBrushLab_, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Brush Lab", &showBrushLab_, 420 * scale)) {
ImGui::End();
return;
}
@@ -1591,8 +1678,7 @@ void App::drawImageTo3D() {
const float scale = uiScale_;
const ImGuiViewport* vp = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + vp->Size.x - 590 * scale, vp->Pos.y + 34 * scale), ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(290 * scale, 0), ImVec2(290 * scale, FLT_MAX));
- if (!ImGui::Begin("Generate 3D", &showImageTo3D_, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Generate 3D", &showImageTo3D_, 290 * scale)) {
ImGui::End();
return;
}
@@ -1766,8 +1852,7 @@ void App::drawImageTo3D() {
void App::drawToolPanel() {
const float scale = uiScale_;
ImGui::SetNextWindowPos(ImVec2(10 * scale, 34 * scale), ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(250 * scale, 0), ImVec2(250 * scale, FLT_MAX));
- if (!ImGui::Begin("Tools", nullptr, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Tools", nullptr, 250 * scale)) {
ImGui::End();
return;
}
@@ -1862,8 +1947,7 @@ void App::drawSplatSection() {
const float scale = uiScale_;
const ImGuiViewport* vp = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + vp->Size.x - 590 * scale, vp->Pos.y + 34 * scale), ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(280 * scale, 0), ImVec2(280 * scale, FLT_MAX));
- if (!ImGui::Begin("Gaussian Splats", &showSplatsPanel_, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Gaussian Splats", &showSplatsPanel_, 280 * scale)) {
ImGui::End();
return;
}
diff --git a/src/app/App.h b/src/app/App.h
index 1f6e3de7..48229463 100644
--- a/src/app/App.h
+++ b/src/app/App.h
@@ -40,6 +40,8 @@ struct AppOptions {
std::string demoAsset; // file the demo opens (image or model)
std::string demoOutput; // where the demo saves its result (optional)
int fps = 30;
+ std::string uiTest; // run this .sfui UI test script headless and exit (see UiTest.cpp)
+ std::string uiOutDir; // where UI tests save screenshots
};
class Demo;
@@ -106,13 +108,15 @@ private:
void openPath(const std::string& path);
void drawRecipeEditor(BrushRecipe& recipe);
void drawAiSettings();
+ bool beginPanel(const char* name, bool* open, float width); // ImGui::Begin for auto-sized side panels
void sendBrushRequest(const std::string& text);
void pollBrushRequest();
const BrushRecipe* activeRecipe() const;
void drawBrushCursor();
void updateTitle();
- int runRecording();
+ int runRecording(); // also runs UI tests (options_.uiTest)
+ int runUiTest(int width, int height, int fps);
std::unique_ptr<Demo> demo_;
float uiScale_ = 1.0f; // UI layout scale (fonts are rasterised at this scale)
ImFont* fontCaption_ = nullptr;
@@ -151,6 +155,7 @@ private:
glm::vec3 grabPlanePoint_{0.0f}, grabLast_{0.0f};
std::string status_;
+ bool lastCommandOk_ = true; // result of the last runCommand (UI tests check it)
bool showHelp_ = false;
bool showAbout_ = false;
diff --git a/src/app/Demo.cpp b/src/app/Demo.cpp
index 2a32d85d..e8e8f3f7 100644
--- a/src/app/Demo.cpp
+++ b/src/app/Demo.cpp
@@ -21,9 +21,22 @@
namespace {
+struct Placed {
+ ImRect rect;
+ ImRect clip; // the part of the screen the item's window shows
+};
+
struct ItemTable {
- std::map<ImGuiID, ImRect> rects;
- std::map<std::string, ImRect> byLabel;
+ std::map<ImGuiID, Placed> rects;
+ std::map<std::string, Placed> byLabel;
+ // Every item drawn this frame with the ID-stack seed it was created under, so
+ // items that never report a label (combo boxes) can be matched by hashing one.
+ struct Seeded {
+ ImGuiID id, seed;
+ std::string window;
+ Placed placed;
+ };
+ std::vector<Seeded> frame;
};
ItemTable& items() {
static ItemTable t;
@@ -32,17 +45,32 @@ ItemTable& items() {
} // namespace
-void ImGuiTestEngineHook_ItemAdd(ImGuiContext*, ImGuiID id, const ImRect& bb, const ImGuiLastItemData*) {
- items().rects[id] = bb;
+void ImGuiTestEngineHook_ItemAdd(ImGuiContext* ctx, ImGuiID id, const ImRect& bb, const ImGuiLastItemData*) {
+ ImRect clip = bb;
+ if (ctx && ctx->CurrentWindow) {
+ clip = ctx->CurrentWindow->ClipRect;
+ clip.ClipWith(ImRect(ImVec2(0, 0), ctx->IO.DisplaySize));
+ }
+ items().rects[id] = {bb, clip};
+ if (id && ctx && ctx->CurrentWindow && !ctx->CurrentWindow->IDStack.empty()) {
+ std::string window = ctx->CurrentWindow->Name;
+ if (const size_t hash = window.find("##"); hash != std::string::npos) window.resize(hash);
+ items().frame.push_back({id, ctx->CurrentWindow->IDStack.back(), std::move(window), {bb, clip}});
+ }
}
-void ImGuiTestEngineHook_ItemInfo(ImGuiContext*, ImGuiID id, const char* label, ImGuiItemStatusFlags) {
+void ImGuiTestEngineHook_ItemInfo(ImGuiContext* ctx, ImGuiID id, const char* label, ImGuiItemStatusFlags) {
auto it = items().rects.find(id);
if (!label || it == items().rects.end()) return;
std::string text(label);
- items().byLabel[text] = it->second;
- if (const size_t hash = text.find("##"); hash != std::string::npos && hash > 0)
- items().byLabel.try_emplace(text.substr(0, hash), it->second);
+ std::string window = ctx && ctx->CurrentWindow ? ctx->CurrentWindow->Name : "";
+ if (const size_t hash = window.find("##"); hash != std::string::npos) window.resize(hash);
+ auto add = [&](const std::string& key) {
+ items().byLabel[key] = it->second;
+ if (!window.empty()) items().byLabel[window + "/" + key] = it->second;
+ };
+ add(text);
+ if (const size_t hash = text.find("##"); hash != std::string::npos && hash > 0) add(text.substr(0, hash));
}
void ImGuiTestEngineHook_Log(ImGuiContext*, const char*, ...) {}
@@ -69,13 +97,44 @@ glm::vec3 onSphere(float latDeg, float lonDeg, float r = 1.0f) {
} // namespace
-void Demo::beginFrame() { items().byLabel.clear(); }
+void Demo::beginFrame() {
+ items().byLabel.clear();
+ items().frame.clear();
+}
-bool Demo::findItem(const std::string& label, ImVec2& center) const {
+std::vector<std::string> Demo::similarItems(const std::string& label) {
+ auto lower = [](std::string s) {
+ for (auto& c : s) c = char(std::tolower(static_cast<unsigned char>(c)));
+ return s;
+ };
+ std::string want = lower(label);
+ if (const size_t hash = want.find_first_not_of('#'); hash != std::string::npos) want = want.substr(hash);
+ std::vector<std::string> out;
+ for (const auto& [name, rect] : items().byLabel)
+ if (lower(name).find(want) != std::string::npos && out.size() < 8) out.push_back(name);
+ return out;
+}
+
+bool Demo::findItem(const std::string& label, ImVec2& center, bool* visible, ImVec4* clipOut) const {
+ auto found = [&](const Placed& p) {
+ center = p.rect.GetCenter();
+ if (visible) *visible = p.clip.Contains(center);
+ if (clipOut) *clipOut = ImVec4(p.clip.Min.x, p.clip.Min.y, p.clip.Max.x, p.clip.Max.y);
+ return true;
+ };
auto it = items().byLabel.find(label);
- if (it == items().byLabel.end()) return false;
- center = it->second.GetCenter();
- return true;
+ if (it != items().byLabel.end()) return found(it->second);
+ // Unlabelled items: hash the label the way ImGui's GetID() would.
+ std::string window, name = label;
+ if (const size_t slash = label.find('/'); slash != std::string::npos && slash > 0 && label.compare(0, 2, "##") != 0) {
+ window = label.substr(0, slash);
+ name = label.substr(slash + 1);
+ }
+ for (auto s = items().frame.rbegin(); s != items().frame.rend(); ++s) {
+ if (!window.empty() && s->window != window) continue;
+ if (ImHashStr(name.c_str(), 0, s->seed) == s->id) return found(s->placed);
+ }
+ return false;
}
std::vector<std::string> Demo::names() { return {"showcase", "sculpt", "image-to-3d", "brush-lab", "game-ready", "splats"}; }
diff --git a/src/app/Demo.h b/src/app/Demo.h
index f66e875f..5527a272 100644
--- a/src/app/Demo.h
+++ b/src/app/Demo.h
@@ -8,13 +8,21 @@
// real buttons rather than calling functions behind the UI's back.
//
// sculptforge --demo sculpt --record sculpt.mp4 --size 1920x1080
+//
+// The same machinery runs UI tests: a .sfui script of clicks, typing, strokes
+// and expectations against the real interface, with screenshots (UiTest.cpp).
+//
+// sculptforge --ui-test tests/ui/brush_lab.sfui --ui-out shots/
#pragma once
#include <glm/glm.hpp>
#include <imgui.h>
+#include <SDL3/SDL.h>
+
#include <functional>
#include <string>
+#include <utility>
#include <vector>
namespace sf {
@@ -33,9 +41,21 @@ public:
bool finished() const { return step_ >= steps_.size(); }
int frameStride() const { return stride_; } // >1 while fast-forwarding through waits
- // Screen rect of the most recent UI item with this label (text before "##" also matches).
- bool findItem(const std::string& label, ImVec2& center) const;
+ // Screen rect of the most recent UI item with this label (text before "##" also matches;
+ // "Window/label" picks the item in one window).
+ bool findItem(const std::string& label, ImVec2& center, bool* visible = nullptr, ImVec4* clip = nullptr) const;
static void beginFrame(); // clears the item table (called before ImGui::NewFrame)
+ static std::vector<std::string> similarItems(const std::string& label); // for test failure messages
+
+ // UI tests (UiTest.cpp). Steps that fail stop the run; failures() lists why.
+ bool loadScript(const std::string& path, std::string& error);
+ bool testing() const { return testing_; }
+ const std::vector<std::string>& failures() const { return failures_; }
+ int stepsRun() const { return int(step_); }
+ // Every piece of text drawn in the last frame (ImGui log capture), for expect_text.
+ void setFrameText(std::string text) { frameText_ = std::move(text); }
+ // A screenshot requested by a `shot` step: the frame loop saves the next frame there.
+ std::string takeShotRequest() { return std::exchange(shotRequest_, std::string()); }
private:
using Step = std::function<bool(float t)>; // returns true when done; t = seconds since the step began
@@ -52,6 +72,14 @@ private:
void run(std::function<void()> action);
void waitUntil(std::function<bool()> done, float timeout, int stride);
+ // UI test steps.
+ void fail(int line, const std::string& message);
+ bool parseStep(int line, const std::vector<std::string>& words, std::string& error);
+ void testClick(int line, const std::string& label, int button, bool doubleClick);
+ void testKey(int line, const std::string& combo);
+ void testKeyNow(SDL_Keycode key, SDL_Keymod mods);
+ double query(const std::string& name, bool& known) const;
+
void buildShowcase();
void buildSculpt();
void buildImageTo3D();
@@ -82,6 +110,11 @@ private:
};
std::vector<Caption> captions_;
float clock_ = 0.0f;
+
+ bool testing_ = false;
+ std::vector<std::string> failures_;
+ std::string frameText_, shotRequest_, shotDir_, scriptName_, lineText_;
+ SDL_Keymod held_ = SDL_KMOD_NONE; // modifiers held by `hold` (Ctrl to mask, Ctrl+Shift to hide...)
};
} // namespace sf
diff --git a/src/app/PanelPolypaint.cpp b/src/app/PanelPolypaint.cpp
index 229f013e..a86c165e 100644
--- a/src/app/PanelPolypaint.cpp
+++ b/src/app/PanelPolypaint.cpp
@@ -73,8 +73,7 @@ void App::drawPolypaintPanel() {
const float scale = uiScale_;
const ImGuiViewport* vp = ImGui::GetMainViewport();
ImGui::SetNextWindowPos(ImVec2(vp->Pos.x + 270 * scale, vp->Pos.y + 34 * scale), ImGuiCond_FirstUseEver);
- ImGui::SetNextWindowSizeConstraints(ImVec2(250 * scale, 0), ImVec2(250 * scale, FLT_MAX));
- if (!ImGui::Begin("Polypaint & Materials", &showPolypaintPanel_, ImGuiWindowFlags_AlwaysAutoResize)) {
+ if (!beginPanel("Polypaint & Materials", &showPolypaintPanel_, 250 * scale)) {
ImGui::End();
return;
}
diff --git a/src/app/UiTest.cpp b/src/app/UiTest.cpp
new file mode 100644
index 00000000..a74904e9
--- /dev/null
+++ b/src/app/UiTest.cpp
@@ -0,0 +1,487 @@
+// SculptForge - open source digital sculpting
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// UI test scripts (.sfui): drive the real interface the way a person does and
+// check what it shows. One step per line, '#' starts a comment, quote words
+// containing spaces. Items are found by their ImGui label ("Find models",
+// "Brush Lab/Save settings" for the one in that window).
+//
+// click LABEL / double_click LABEL / right_click LABEL / hover LABEL
+// type LABEL TEXT click a text field and type into it
+// key COMBO e.g. enter, escape, ctrl+z, ctrl+shift+z, 3
+// hold MODS ctrl / shift / alt / ctrl+shift ... or none (for strokes and drags)
+// stroke U0 V0 U1 V1 [S] brush stroke across the model (fractions of its on-screen bounds)
+// drag X0 Y0 X1 Y1 [S] left-drag in window fractions (rectangle hide, sliders...)
+// orbit DX DY right-drag on the background, in pixels
+// run COMMANDS sculptforge-cli commands, e.g. run new_sphere subdivisions=4
+// wait SECONDS / wait_idle [TIMEOUT] (AI requests and background jobs) / wait_for LABEL [TIMEOUT]
+// expect LABEL / expect_not LABEL
+// expect_text TEXT / expect_no_text TEXT any text drawn this frame contains TEXT
+// expect_status TEXT the status bar message contains TEXT
+// expect_value NAME OP N triangles, vertices, layers, brushes, masked, hidden, groups, colored,
+// can_undo, dirty, splats, show_polygroups, show_mask, wireframe;
+// OP is == != < <= > >=
+// shot NAME save a screenshot NAME.png (to --ui-out)
+#include "app/App.h"
+#include "app/Demo.h"
+
+#include "core/Script.h"
+
+#include <imgui_internal.h>
+
+#include <algorithm>
+#include <cctype>
+#include <chrono>
+#include <cmath>
+#include <filesystem>
+#include <fstream>
+#include <future>
+#include <memory>
+#include <set>
+#include <sstream>
+
+namespace sf {
+
+namespace {
+
+// Splits a line into words; "double quoted" words may contain spaces.
+std::vector<std::string> splitWords(const std::string& line) {
+ std::vector<std::string> out;
+ size_t i = 0;
+ while (i < line.size()) {
+ while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
+ if (i >= line.size() || line[i] == '#') break;
+ std::string w;
+ if (line[i] == '"') {
+ ++i;
+ while (i < line.size() && line[i] != '"') w += line[i++];
+ ++i;
+ } else {
+ while (i < line.size() && !std::isspace(static_cast<unsigned char>(line[i]))) w += line[i++];
+ }
+ out.push_back(w);
+ }
+ return out;
+}
+
+// Everything after the first `skip` words, verbatim (for `run` and `type`).
+std::string restOf(const std::string& line, int skip) {
+ size_t i = 0;
+ for (int k = 0; k < skip; ++k) {
+ while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
+ if (i < line.size() && line[i] == '"') {
+ i = line.find('"', i + 1);
+ i = i == std::string::npos ? line.size() : i + 1;
+ } else {
+ while (i < line.size() && !std::isspace(static_cast<unsigned char>(line[i]))) ++i;
+ }
+ }
+ while (i < line.size() && std::isspace(static_cast<unsigned char>(line[i]))) ++i;
+ std::string rest = line.substr(i);
+ if (rest.size() >= 2 && rest.front() == '"' && rest.back() == '"') rest = rest.substr(1, rest.size() - 2);
+ return rest;
+}
+
+SDL_Keymod parseMods(const std::string& text, std::string* key = nullptr) {
+ SDL_Keymod mods = SDL_KMOD_NONE;
+ std::stringstream ss(text);
+ std::string part, last;
+ while (std::getline(ss, part, '+')) {
+ std::string p = part;
+ std::transform(p.begin(), p.end(), p.begin(), [](unsigned char c) { return char(std::tolower(c)); });
+ if (p == "ctrl" || p == "control") mods |= SDL_KMOD_LCTRL;
+ else if (p == "shift") mods |= SDL_KMOD_LSHIFT;
+ else if (p == "alt") mods |= SDL_KMOD_LALT;
+ else if (p == "cmd" || p == "gui" || p == "super") mods |= SDL_KMOD_LGUI;
+ else last = part;
+ }
+ if (key) *key = last;
+ return mods;
+}
+
+template <class T> bool busy(const std::future<T>& f) {
+ return f.valid() && f.wait_for(std::chrono::seconds(0)) != std::future_status::ready;
+}
+
+bool compare(double a, const std::string& op, double b) {
+ if (op == "==") return std::abs(a - b) < 1e-6;
+ if (op == "!=") return std::abs(a - b) >= 1e-6;
+ if (op == "<") return a < b;
+ if (op == "<=") return a <= b;
+ if (op == ">") return a > b;
+ if (op == ">=") return a >= b;
+ return false;
+}
+
+std::string notFound(const std::string& label) {
+ std::string msg = "no UI item labelled \"" + label + "\"";
+ const auto similar = Demo::similarItems(label);
+ for (size_t i = 0; i < similar.size(); ++i) msg += (i ? ", \"" : " (similar: \"") + similar[i] + "\"";
+ if (!similar.empty()) msg += ")";
+ return msg;
+}
+
+std::string number(double v) {
+ std::ostringstream ss;
+ ss << v;
+ return ss.str();
+}
+
+} // namespace
+
+void Demo::fail(int line, const std::string& message) {
+ failures_.push_back(scriptName_ + ":" + std::to_string(line) + ": " + message);
+ SDL_Log("FAIL %s", failures_.back().c_str());
+ if (!shotDir_.empty()) shotRequest_ = shotDir_ + "/FAIL-line-" + std::to_string(line) + ".png";
+ step_ = steps_.size(); // stop: later steps depend on this one
+ // The frame loop still renders one more frame, so the failure screenshot shows the state.
+}
+
+double Demo::query(const std::string& name, bool& known) const {
+ const Mesh& m = app_.doc_.mesh;
+ known = true;
+ if (name == "triangles") return double(m.triangleCount());
+ if (name == "vertices") return double(m.vertexCount());
+ if (name == "layers") return double(m.layers.size());
+ if (name == "brushes") return double(app_.doc_.brushes.size());
+ if (name == "colored") return m.hasColors() ? 1.0 : 0.0;
+ if (name == "can_undo") return app_.doc_.undo.canUndo() ? 1.0 : 0.0;
+ if (name == "dirty") return app_.doc_.dirty() ? 1.0 : 0.0;
+ if (name == "splats") return double(app_.doc_.splats.size());
+ if (name == "show_polygroups") return app_.renderSettings_.showPolygroups ? 1.0 : 0.0;
+ if (name == "show_mask") return app_.renderSettings_.showMask ? 1.0 : 0.0;
+ if (name == "wireframe") return app_.renderSettings_.wireframe ? 1.0 : 0.0;
+ if (name == "masked") {
+ size_t n = 0;
+ for (float v : m.mask) n += v > 0.5f;
+ return double(n);
+ }
+ if (name == "hidden") {
+ size_t n = 0;
+ for (uint8_t h : m.hidden) n += h != 0;
+ return double(n);
+ }
+ if (name == "groups") {
+ std::set<uint32_t> ids(m.polygroups.begin(), m.polygroups.end());
+ return double(std::max<size_t>(ids.size(), m.triangleCount() ? 1 : 0));
+ }
+ known = false;
+ return 0.0;
+}
+
+void Demo::testClick(int line, const std::string& label, int button, bool doubleClick) {
+ // Find the item (give the UI a moment to appear), glide there, press and release.
+ steps_.push_back([this, line, label](float t) {
+ ImVec2 to;
+ bool visible = false;
+ if (!findItem(label, to, &visible)) {
+ if (t > 3.0f) fail(line, notFound(label));
+ return t > 3.0f;
+ }
+ if (!visible) {
+ // Scrolled out of its panel: wheel the panel towards it, as a person would.
+ ImVec4 clip;
+ findItem(label, to, &visible, &clip);
+ if (clip.z > clip.x && clip.w > clip.y && t <= 2.0f) {
+ mouseMotion((clip.x + clip.z) * 0.5f, (clip.y + clip.w) * 0.5f);
+ SDL_Event e{};
+ e.type = SDL_EVENT_MOUSE_WHEEL;
+ e.wheel.windowID = SDL_GetWindowID(app_.window_);
+ e.wheel.y = to.y > clip.w ? -1.0f : 1.0f;
+ e.wheel.mouse_x = mouse_.x;
+ e.wheel.mouse_y = mouse_.y;
+ app_.handleEvent(e);
+ return false;
+ }
+ // Off the screen, or the panel won't scroll: a person couldn't click it either.
+ if (t > 1.0f) fail(line, "\"" + label + "\" is not visible (off screen or scrolled out of view)");
+ return t > 1.0f;
+ }
+ mouseMotion(to.x, to.y);
+ return true;
+ });
+ steps_.push_back([this, button, doubleClick](float t) {
+ // A frame of hover first, so ImGui registers the item as hovered before the press.
+ if (t == 0.0f) return false;
+ mouseButton(true, button);
+ mouseButton(false, button);
+ if (doubleClick) {
+ SDL_Event e{};
+ e.type = SDL_EVENT_MOUSE_BUTTON_DOWN;
+ e.button.windowID = SDL_GetWindowID(app_.window_);
+ e.button.button = Uint8(button);
+ e.button.down = true;
+ e.button.clicks = 2;
+ e.button.x = mouse_.x;
+ e.button.y = mouse_.y;
+ app_.handleEvent(e);
+ e.type = SDL_EVENT_MOUSE_BUTTON_UP;
+ e.button.down = false;
+ app_.handleEvent(e);
+ }
+ return true;
+ });
+ wait(0.1f);
+}
+
+void Demo::testKey(int line, const std::string& combo) {
+ std::string keyName;
+ const SDL_Keymod mods = parseMods(combo, &keyName);
+ const SDL_Keycode key = SDL_GetKeyFromName(keyName.c_str());
+ if (key == SDLK_UNKNOWN) {
+ run([this, line, keyName] { fail(line, "unknown key \"" + keyName + "\""); });
+ return;
+ }
+ steps_.push_back([this, mods, key](float) {
+ const SDL_Keymod before = SDL_GetModState();
+ SDL_SetModState(mods | held_);
+ SDL_Event e{};
+ e.type = SDL_EVENT_KEY_DOWN;
+ e.key.windowID = SDL_GetWindowID(app_.window_);
+ e.key.key = key;
+ e.key.scancode = SDL_GetScancodeFromKey(key, nullptr);
+ e.key.mod = mods | held_;
+ e.key.down = true;
+ app_.handleEvent(e);
+ e.type = SDL_EVENT_KEY_UP;
+ e.key.down = false;
+ e.key.mod = held_; // the combo's modifiers are released with the key
+ app_.handleEvent(e);
+ SDL_SetModState(before);
+ return true;
+ });
+ wait(0.1f);
+}
+
+bool Demo::parseStep(int line, const std::vector<std::string>& w, std::string& error) {
+ const std::string& verb = w[0];
+ auto need = [&](size_t n) {
+ if (w.size() >= n + 1) return true;
+ error = "'" + verb + "' needs " + std::to_string(n) + " argument" + (n == 1 ? "" : "s");
+ return false;
+ };
+ auto num = [&](size_t i, float fallback) { return i < w.size() ? std::strtof(w[i].c_str(), nullptr) : fallback; };
+
+ if (verb == "click" || verb == "double_click" || verb == "right_click") {
+ if (!need(1)) return false;
+ testClick(line, w[1], verb == "right_click" ? SDL_BUTTON_RIGHT : SDL_BUTTON_LEFT, verb == "double_click");
+ } else if (verb == "hover") {
+ if (!need(1)) return false;
+ const std::string label = w[1];
+ steps_.push_back([this, line, label](float t) {
+ ImVec2 to;
+ if (findItem(label, to)) {
+ mouseMotion(to.x, to.y);
+ return true;
+ }
+ if (t > 3.0f) fail(line, notFound(label));
+ return t > 3.0f;
+ });
+ wait(0.6f); // tooltips appear after a short delay
+ } else if (verb == "type") {
+ if (!need(2)) return false;
+ testClick(line, w[1], SDL_BUTTON_LEFT, false);
+ auto text = std::make_shared<std::string>(restOf(lineText_, 2));
+ steps_.push_back([this, text](float) {
+ // Select what's there, then type over it like a person would.
+ testKeyNow(SDLK_A, SDL_KMOD_LCTRL);
+ SDL_Event e{};
+ e.type = SDL_EVENT_TEXT_INPUT;
+ e.text.windowID = SDL_GetWindowID(app_.window_);
+ e.text.text = text->c_str();
+ app_.handleEvent(e);
+ return true;
+ });
+ wait(0.1f);
+ } else if (verb == "key") {
+ if (!need(1)) return false;
+ testKey(line, w[1]);
+ } else if (verb == "hold") {
+ if (!need(1)) return false;
+ const SDL_Keymod mods = w[1] == "none" ? SDL_KMOD_NONE : parseMods(w[1]);
+ run([this, mods] {
+ held_ = mods;
+ SDL_SetModState(mods);
+ });
+ } else if (verb == "stroke") {
+ if (!need(4)) return false;
+ const float u0 = num(1, 0), v0 = num(2, 0), u1 = num(3, 0), v1 = num(4, 0), seconds = num(5, 0.6f);
+ auto ends = std::make_shared<std::pair<ImVec2, ImVec2>>();
+ run([this, ends, u0, v0, u1, v1] { *ends = {onModel(u0, v0), onModel(u1, v1)}; });
+ stroke([ends](float u) {
+ return ImVec2(ends->first.x + (ends->second.x - ends->first.x) * u,
+ ends->first.y + (ends->second.y - ends->first.y) * u);
+ }, seconds);
+ run([this] { SDL_SetModState(held_); });
+ wait(0.1f);
+ } else if (verb == "drag") {
+ if (!need(4)) return false;
+ const float x0 = num(1, 0), y0 = num(2, 0), x1 = num(3, 0), y1 = num(4, 0), seconds = num(5, 0.4f);
+ steps_.push_back([this, x0, y0, x1, y1, seconds](float t) {
+ int ww = 0, wh = 0;
+ SDL_GetWindowSize(app_.window_, &ww, &wh);
+ const ImVec2 a(x0 * float(ww), y0 * float(wh)), b(x1 * float(ww), y1 * float(wh));
+ if (t == 0.0f) {
+ mouseMotion(a.x, a.y);
+ return false;
+ }
+ if (!buttonDown_ && t < seconds) mouseButton(true, SDL_BUTTON_LEFT);
+ const float u = std::min(t / seconds, 1.0f);
+ mouseMotion(a.x + (b.x - a.x) * u, a.y + (b.y - a.y) * u);
+ if (t >= seconds) {
+ mouseButton(false, SDL_BUTTON_LEFT);
+ return true;
+ }
+ return false;
+ });
+ wait(0.1f);
+ } else if (verb == "orbit") {
+ if (!need(2)) return false;
+ orbit(num(1, 0), num(2, 0), 0.4f);
+ } else if (verb == "run") {
+ if (!need(1)) return false;
+ std::vector<ScriptStatement> statements;
+ if (!parseScript(restOf(lineText_, 1), statements, error)) return false;
+ run([this, line, statements] {
+ for (const auto& st : statements) {
+ app_.runCommand(st.command, st.args);
+ if (!app_.lastCommandOk_) {
+ fail(line, st.command + " failed: " + app_.status_);
+ return;
+ }
+ }
+ });
+ } else if (verb == "wait") {
+ if (!need(1)) return false;
+ wait(num(1, 0));
+ } else if (verb == "wait_idle") {
+ const float timeout = num(1, 120.0f);
+ steps_.push_back([this, line, timeout](float t) {
+ const bool idle = !busy(app_.pendingBrush_) && !busy(app_.pendingGenerator_) && !busy(app_.pendingModels_) &&
+ !busy(app_.pendingUnreal_);
+ if (idle) return true;
+ SDL_Delay(10); // real work runs in real time
+ if (t > timeout) fail(line, "still busy after " + number(timeout) + " s");
+ return t > timeout;
+ });
+ wait(0.2f); // let the app pick up the results
+ } else if (verb == "wait_for") {
+ if (!need(1)) return false;
+ const std::string label = w[1];
+ const float timeout = num(2, 10.0f);
+ steps_.push_back([this, line, label, timeout](float t) {
+ ImVec2 at;
+ if (findItem(label, at)) return true;
+ SDL_Delay(10);
+ if (t > timeout) fail(line, "\"" + label + "\" did not appear within " + number(timeout) + " s");
+ return t > timeout;
+ });
+ } else if (verb == "expect" || verb == "expect_not") {
+ if (!need(1)) return false;
+ const std::string label = w[1];
+ const bool want = verb == "expect";
+ // Expectations look at the frame drawn after the previous step settled.
+ steps_.push_back([this, line, label, want](float t) {
+ if (t == 0.0f) return false;
+ ImVec2 at;
+ if (findItem(label, at) != want)
+ fail(line, want ? "expected UI item \"" + label + "\"" : "UI item \"" + label + "\" should not be shown");
+ return true;
+ });
+ } else if (verb == "expect_text" || verb == "expect_no_text") {
+ if (!need(1)) return false;
+ const std::string text = restOf(lineText_, 1);
+ const bool want = verb == "expect_text";
+ steps_.push_back([this, line, text, want](float t) {
+ if (t == 0.0f) return false;
+ if ((frameText_.find(text) != std::string::npos) != want)
+ fail(line, want ? "no text \"" + text + "\" on screen" : "text \"" + text + "\" is on screen");
+ return true;
+ });
+ } else if (verb == "expect_status") {
+ if (!need(1)) return false;
+ const std::string text = restOf(lineText_, 1);
+ run([this, line, text] {
+ if (app_.status_.find(text) == std::string::npos)
+ fail(line, "status is \"" + app_.status_ + "\", expected it to contain \"" + text + "\"");
+ });
+ } else if (verb == "expect_value") {
+ if (!need(3)) return false;
+ bool known = false;
+ query(w[1], known);
+ if (!known) {
+ error = "unknown value '" + w[1] + "'";
+ return false;
+ }
+ const std::string name = w[1], op = w[2];
+ const double want = num(3, 0);
+ run([this, line, name, op, want] {
+ bool k = false;
+ const double v = query(name, k);
+ if (!compare(v, op, want)) fail(line, name + " is " + number(v) + ", expected " + op + " " + number(want));
+ });
+ } else if (verb == "shot") {
+ if (!need(1)) return false;
+ const std::string name = w[1];
+ steps_.push_back([this, name](float t) {
+ if (t == 0.0f) return false; // a settled frame
+ if (!shotDir_.empty()) shotRequest_ = shotDir_ + "/" + name + ".png";
+ return true;
+ });
+ wait(0.05f);
+ } else {
+ error = "unknown step '" + verb + "'";
+ return false;
+ }
+ return true;
+}
+
+void Demo::testKeyNow(SDL_Keycode key, SDL_Keymod mods) {
+ SDL_Event e{};
+ e.type = SDL_EVENT_KEY_DOWN;
+ e.key.windowID = SDL_GetWindowID(app_.window_);
+ e.key.key = key;
+ e.key.scancode = SDL_GetScancodeFromKey(key, nullptr);
+ e.key.mod = mods;
+ e.key.down = true;
+ app_.handleEvent(e);
+ e.type = SDL_EVENT_KEY_UP;
+ e.key.down = false;
+ e.key.mod = held_;
+ app_.handleEvent(e);
+}
+
+bool Demo::loadScript(const std::string& path, std::string& error) {
+ std::ifstream f(std::filesystem::path(std::u8string(path.begin(), path.end())));
+ if (!f) {
+ error = "Cannot read " + path;
+ return false;
+ }
+ testing_ = true;
+ scriptName_ = std::filesystem::path(std::u8string(path.begin(), path.end())).filename().string();
+ shotDir_ = app_.options_.uiOutDir;
+ if (!shotDir_.empty()) {
+ std::error_code ec;
+ std::filesystem::create_directories(std::filesystem::path(std::u8string(shotDir_.begin(), shotDir_.end())), ec);
+ }
+ mouse_ = ImVec2(float(app_.options_.width) * 0.5f, float(app_.options_.height) * 0.5f);
+ wait(0.2f); // first frames: windows find their places
+ std::string line;
+ int n = 0;
+ while (std::getline(f, line)) {
+ ++n;
+ if (!line.empty() && line.back() == '\r') line.pop_back();
+ auto words = splitWords(line);
+ if (words.empty()) continue;
+ lineText_ = line;
+ std::string err;
+ if (!parseStep(n, words, err)) {
+ error = scriptName_ + ":" + std::to_string(n) + ": " + err;
+ return false;
+ }
+ }
+ wait(0.1f);
+ return true;
+}
+
+} // namespace sf
diff --git a/src/app/main.cpp b/src/app/main.cpp
index 52de9f93..efa0f836 100644
--- a/src/app/main.cpp
+++ b/src/app/main.cpp
@@ -4,8 +4,10 @@
#include <SDL3/SDL_main.h>
+#include <chrono>
#include <cstdio>
#include <cstdlib>
+#include <filesystem>
#include <string>
namespace {
@@ -26,20 +28,49 @@ void usage() {
" --record out.mp4 Record the demo offscreen to a video (needs ffmpeg) and exit\n"
" --demo-asset FILE Image or model the demo opens\n"
" --demo-output FILE Save the demo's result (e.g. creature.glb)\n"
- " --fps N Recording frame rate (default 30)");
+ " --fps N Recording frame rate (default 30)\n"
+ " --ui-test FILE.sfui Run a UI test script headless and exit (0 = pass); settings are isolated\n"
+ " --ui-out DIR Where UI tests save screenshots");
+}
+
+// UI tests must never read or change the user's real settings, recent files or
+// autosaves: point the per-user data directories at a fresh temporary folder.
+void isolateSettings() {
+ std::error_code ec;
+ const auto dir = std::filesystem::temp_directory_path(ec) /
+ ("sculptforge-ui-test-" + std::to_string(std::chrono::steady_clock::now().time_since_epoch().count()));
+ std::filesystem::create_directories(dir, ec);
+ const std::string d = dir.string();
+#if defined(_WIN32)
+ _putenv_s("APPDATA", d.c_str());
+#else
+ setenv("XDG_DATA_HOME", d.c_str(), 1);
+ setenv("XDG_CONFIG_HOME", d.c_str(), 1);
+#if defined(__APPLE__)
+ setenv("HOME", d.c_str(), 1);
+#endif
+#endif
+ for (const char* key : {"ANTHROPIC_API_KEY", "OPENAI_API_KEY", "HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "FAL_KEY", "MESHY_API_KEY"}) {
+#if defined(_WIN32)
+ _putenv_s(key, "");
+#else
+ unsetenv(key);
+#endif
+ }
}
} // namespace
int main(int argc, char** argv) {
sf::AppOptions options;
+ bool sizeGiven = false;
for (int i = 1; i < argc; ++i) {
std::string a = argv[i];
auto next = [&]() -> std::string { return i + 1 < argc ? argv[++i] : std::string(); };
if (a == "--run") options.script += next() + "\n";
else if (a == "--render") options.renderPath = next();
else if (a == "--turntable") options.turntable = std::atoi(next().c_str());
- else if (a == "--size") std::sscanf(next().c_str(), "%dx%d", &options.width, &options.height);
+ else if (a == "--size") sizeGiven = std::sscanf(next().c_str(), "%dx%d", &options.width, &options.height) == 2;
else if (a == "--view") std::sscanf(next().c_str(), "%f,%f", &options.yawDegrees, &options.pitchDegrees);
else if (a == "--wireframe") options.wireframe = true;
else if (a == "--polygroups") options.polygroups = true;
@@ -49,6 +80,8 @@ int main(int argc, char** argv) {
else if (a == "--demo-asset") options.demoAsset = next();
else if (a == "--demo-output") options.demoOutput = next();
else if (a == "--fps") options.fps = std::atoi(next().c_str());
+ else if (a == "--ui-test") options.uiTest = next();
+ else if (a == "--ui-out") options.uiOutDir = next();
else if (a == "-h" || a == "--help") {
usage();
return 0;
@@ -59,6 +92,10 @@ int main(int argc, char** argv) {
return 1;
}
}
+ if (!options.uiTest.empty()) {
+ if (!sizeGiven) options.width = 1600, options.height = 960;
+ isolateSettings();
+ }
sf::App app;
if (!app.init(options)) {
app.shutdown();
diff --git a/tests/ui/ai_provider.sfui b/tests/ui/ai_provider.sfui
new file mode 100644
index 00000000..af200447
--- /dev/null
+++ b/tests/ui/ai_provider.sfui
@@ -0,0 +1,28 @@
+# Brush Lab's AI provider panel: Free by default, local-model helpers for OpenAI-compatible.
+expect "Brush Lab"
+click "AI provider"
+expect_text Free - no account or key
+expect_text Pollinations.ai
+expect_not "Endpoint"
+shot ai-free
+
+click "##provider"
+click "OpenAI-compatible (OpenAI, Ollama, LM Studio...)"
+expect "Ollama"
+expect "LM Studio"
+expect "Find models"
+expect "Endpoint"
+click "Run a model on this computer"
+expect_text ollama pull qwen3:4b-instruct
+shot ai-local-help
+
+# Nothing listens on this port: the panel must say so instead of hanging.
+type "Endpoint" http://127.0.0.1:9/v1/chat/completions
+click "Find models"
+wait_idle 15
+expect_text Nothing is answering
+shot ai-not-running
+
+click "LM Studio"
+click "Ollama"
+expect_no_text Nothing is answering
diff --git a/tests/ui/sculpt_basics.sfui b/tests/ui/sculpt_basics.sfui
new file mode 100644
index 00000000..546d39d9
--- /dev/null
+++ b/tests/ui/sculpt_basics.sfui
@@ -0,0 +1,38 @@
+# Core loop on the real UI: sculpt, undo/redo, masking, polygroups, visibility.
+run new_sphere subdivisions=5
+expect_value can_undo == 0
+click "2 Clay"
+stroke 0.35 0.4 0.65 0.6
+expect_value can_undo == 1
+expect_value dirty == 1
+shot sculpted
+key ctrl+z
+expect_value can_undo == 0
+key ctrl+shift+z
+expect_value can_undo == 1
+
+# Ctrl paints the mask, the Masking buttons edit it.
+hold ctrl
+stroke 0.3 0.3 0.7 0.3
+hold none
+expect_value masked > 50
+click "Invert##mask"
+expect_value masked > 1000
+click "Clear##mask"
+expect_value masked == 0
+
+# Polygroups by normals on a cube-ish shape, then hide one with Ctrl+Shift+click.
+run new_sphere subdivisions=1
+click "By normals"
+expect_value groups > 1
+expect_value show_polygroups == 1 # grouping turns the colours on
+shot polygroups
+click "Show polygroups"
+expect_value show_polygroups == 0
+click "Show all"
+expect_value hidden == 0
+
+# Menus open panels.
+click "View"
+click "Polypaint & Materials"
+expect "Polypaint & Materials"