Projects

Projects

One Plum server hosts one organisation and many projects. A project is a self-contained unit: its own tests folder, its own members, its own reports, schedules and integrations.

The framework choice

Each project picks Playwright or Cucumber when it is created, from a picker on the create form. This choice is permanent. The scaffold, the run command and the report format all depend on it, so there is no update path — to use the other framework, create another project. The Settings → Project page shows the framework as a read-only field.

• Your first project picks its framework right there on the setup page, the first time you open the UI. Every project after that defaults to whatever plum server start --framework set (Playwright unless you passed it), pre-selected on the create form.
• Existing projects that predate the split are treated as Cucumber.

Creating, switching, deleting

• Create — Settings → Project → New project (owner only). Give it a name and pick a framework. Plum derives a URL-safe slug from the name once; the slug never changes afterwards. The server immediately scaffolds projects/<slug>/tests/.
• Switch — the project picker in the top nav. Members see only the projects they belong to; the owner sees all.
• Default project — Settings → Account lets each person pick which of their projects loads on sign-in. It falls back to the first reachable project if that one is later removed or deleted.
• Delete — Settings → Project (owner only). Removes the project, its members, its reports and the projects/<slug>/ folder. Users are account-level and untouched. You cannot delete the last project.

On-disk layout

<instance>/
  projects/
    <slug>/
      tests/               the project's test folder (see Writing Tests)
        package.json        this project's own dependencies
        playwright.config.ts | cucumber.js
        specs/ | features/ + step_definitions/
        pages/
        .env
  data/                  everything that must survive a rebuild
    .plum-jwt-secret     signs sessions: losing it logs everyone out
    .plum-node-secret    what a node presents to register
    reports/             raw runner output, deleted once ingested
  docker-compose.yml
  .plum-server.json

The tests/ folder is exactly what a standalone plum init produces, so you can develop it in isolation and it drops straight into a server project.

Project settings

Settings → Project (owner, or an admin assigned to the project):

Field	What it does
Name / Logo URL / Timezone	Identity shown across the UI. The timezone is what schedule cron expressions fire on.
Test framework	Read-only. Fixed at creation.
Tests folder	Where tests live inside projects/<slug>/. Default tests; set e.g. apps/web/e2e when your repo nests them deeper. Resolved relative to the project folder so it works wherever you initialise Git.
Max retries	Auto-retry failed scenarios. See [[Retrying Flaky Tests
Default homepage	Which page members land on: Automated Tests or Test Repository.
Use as manual repository only	Hides Automated Tests, Reports, Scheduled and the run bar. The [[Test Repository

Connecting a GitHub repo

Optional, and set per project — during the one-time setup wizard's "Connect GitHub" step, or later from Settings → Project → New project (owner only). Needs a GitHub personal access token connected first. Three choices:

• I'll do this later — skip; the project works normally, git-free.
• Existing GitHub repo — give an owner/repo, the default branch, and (for a monorepo) the sub-path your tests actually live in, e.g. apps/web/e2e. Plum clones it and points Tests folder there.
• New GitHub repo — Plum scaffolds tests locally and, if you name a repo, creates it private and pushes the scaffold as its first commit. Leave the name blank to stay git-local only.

A connected repo is what the AI Agent clones its isolated workspace from when it fixes a test-code bug — it's the thing its pull request eventually gets opened against. If the repo connection itself fails partway (bad token, name already taken), the project is still created — the error surfaces on the create form so you can just try the repo connection again from Settings, without having to start over.

Re-creating a tests folder

plum project init "<project name>"

Only re-creates a projects/<slug>/tests/ folder that went missing. It does not touch an existing one.

Membership

Add people from Settings → Users (owner). Each non-owner is assigned to specific projects with a role — see Roles and Access.