A project is one site or app under test. All project settings live as plain files in a separate folder: development tools can read them, the folder moves to another server by simple copying, and the edit history stays visible. Below is what exactly lives in the folder, what is stored in the database and how to create a new project.
A project is a folder
One site — one project — one folder. The folder holds everything that describes your checks, and nothing extra: settings files and small scripts. The projects folder can be copied to another server as a whole and work continues there — no export and no database migration is needed for that.
| What is in the folder | What it is for |
|---|---|
project.yml | the name, the site’s base address, the description, the timezone, the AI agent model for this project and the visual: block with visual-check settings |
project.yml → visual: | the preset, comparison thresholds, capture stabilization, branches, AI budgets, notifications and the continuous integration policy — details in the Visual Testing Settings section |
screen-types.yml | screen types: “login”, “payment”, “account” — each with an address pattern the type is recognized by |
rules/ | the checks themselves — one small file per rule |
actions/ | recorded and agent-written scenarios of working with the interface |
scripts/ | extension scripts: the scripts.yml manifest, <id>.py files and an optional requirements.txt — details in the Scripts & Extensibility section |
tests/ | tests: sequences of steps that are run together |
skills/ | knowledge for the agent: validator.md (what the agent has already understood about your interface) and navigation.md (how to move around it) |
comments/ | comments on screens — plain text, one file per screen |
It is convenient to keep all these files under version control — that is the name for a program that remembers the history of file changes (git, for example). Every edit then has an author and a time, and an unlucky edit can always be rolled back. Changes are committed by a person: the server never records history on its own, so no service entries appear in it without your knowledge.
What lives in the database
Part of the data lives not in the folder but in the product’s database: screen captures and visual builds, comparisons and difference images, baselines with their versions and variations, runs with their steps and results, issues, schedules, comment and failure analyses, test-healing campaigns, coverage and the app map, share links, credentials and API keys. The reason is simple: there is a lot of it, it changes every day, and keeping it in the project folder would be inconvenient both for the edit history and for the product itself. Settings and scripts, on the contrary, change rarely and matter as a document — that is why they are files. And what a script needs to work — a separate Python environment and working directories for intermediate files — lives in the product’s data, not in the project folder.
Screens are stored right in the database, not as separate images on disk. A pleasant consequence for the owner: the database and the projects folder are all you need to back up in order to lose nothing.
Separately — the credentials for different environments: they live in the database encrypted, and the encryption key sits as a separate file in the server’s data folder (keys/visual-creds.key). Secrets never get into the project files, so the folder can safely live in version history and move between servers.
Creating a project
- Name — how the project is called in the interface. Write it the way a person would: “Shop”, “Account”.
- Folder address — suggested automatically from the name: lowercase Latin letters, digits and hyphens, 3 to 63 characters. This is the folder that appears on disk.
- Base address — the address of the site under test. By it, the browser panel understands on its own which project an open page belongs to.
- Description — a couple of words for yourself and for the agent: what this system is.
- Timezone — schedules are computed by it. Get it wrong and runs arrive at the wrong time, so the product rejects an invalid value with an error at the field.
- Agent model — which model to use for analyzing comments in this particular project. Projects differ, and so do their model needs.
- Checklist and coverage goal — right after creation, the eight-step visual-testing setup checklist opens. The coverage goal — how many surfaces and states you want to protect — is set in the visual-testing settings, and progress toward it is visible in the “Coverage” section.
After creation the product immediately scaffolds the folder with all the files, the project card appears in the list without a page reload, and the visual-testing setup checklist comes onto the screen.
How to change settings
The name, base address, timezone and agent model are changed on the Settings tab in a plain form — the settings files are rewritten carefully, and an invalid value never leaves a file half-written. Rules, actions and tests can be viewed and edited through the “Project Files” dialog: if a file changed on disk, the list in the interface shows it at once, because it reads from the files and not from the product’s memory.
The separate scripts: block in project.yml governs extension scripts: the project’s script switch, the default timeout (60 seconds, ceiling 600), the number of concurrent runs, the output size limit, the journal retention period and the after-run hook (hooks.onRunFinalized). Every value is optional and takes effect immediately, without a restart: without this block the project runs on the default settings. What these scripts are — in the Scripts & Extensibility section.
Visual-check settings are gathered in a separate tab of the project settings: General (the coverage goal, the leaderboard), Capture, Stabilization, Checks (layers), Branches, AI, Notifications, Environments, Credentials, Variables, Setup / Teardown, API tokens, Users and Presets. Values are saved with validation: an invalid number or an unknown role will not be written. The “Effective configuration” panel shows the result — what is actually applied once defaults are counted in — and copies it in one click.
Environments and access
What you have to check is usually not one address but several: a test stand and production, and sometimes a staging one in between. Each such stand is described as an environment with its own base address, and one of the environments can be marked as protected — production. That is how the product tells a safe stand apart from production and keeps you from accidentally bypassing the protection. Details — in the Environments, Credentials & Variables section.
Logins and passwords for sign-ins are kept in credentials, encrypted, and are substituted into steps at execution time rather than lying in the project files. Variable sets spare you from repeating the same values across tests. And which user may do what is decided by roles: from the viewer, who can only read, to the owner. That is described in the Users & Roles section.
Project isolation
Projects do not see each other: the screen lists, rules and issues of one project never leak into another. That matters when you check several systems at once — a client’s site and an internal program, for example.
Deleting a project
Deleting a project removes the folder entirely, together with its rules, actions and tests; the project’s data leaves the database too — snapshots and builds, baselines with their versions, coverage and the app map, healing campaigns and share links. This cannot be undone — restoration has to come from your version history, if you keep one. If a project merely needs a pause, do not delete it: uncheck its schedules and no runs will fire, while the accumulated checks stay in place.
Next: how to install the Chrome addon and what its panel does — in the Chrome Extension section.