Development Guide

Development Guide

This page covers the conventions, patterns, and tooling used in the Vitruv-UI-Methodologist frontend codebase. It is the primary reference for contributors and HiWis getting started with the project.

---

Project conventions

Branches and commits

Use descriptive branch names tied to a GitHub Issue:

feature/123-add-viewtype-persistence
fix/456-edge-offset-bidirectional
refactor/789-extract-ocl-parser

Commit messages in imperative mood, referencing the issue:

Add ViewType persistence to localStorage (#123)
Fix bidirectional edge offset calculation (#456)

---

Code quality — SonarQube

SonarQube runs on every push and enforces a set of quality gates. Before submitting a PR, make sure no new violations are introduced.

---

Testing

The project uses Jest and React Testing Library. We cover components, hooks, and services.

Test file location

Tests live in src/__tests__/ mirroring the src/ folder structure:

src/__tests__/
├── auth.test.ts
└── components/
    ├── auth/
    │   ├── SignIn.test.tsx
    │   └── SignUp.test.tsx
    ├── canvas/
    │   ├── ModelDrawer.test.tsx
    │   └── CanvasProjectTabs.test.tsx
    └── flow/
        └── ...

One test file per source file. Do not mix tests for different components in one file.

Mocking pattern

Mock at the module level using jest.mock. Re-declare mock implementations in beforeEach after jest.clearAllMocks() so each test starts with a clean state.

// Module-level mock declarations
jest.mock('../../../contexts/AuthContext', () => ({
  useAuth: () => ({ signIn: mockSignIn }),
}));

jest.mock('../../../services/api', () => ({
  apiService: { forgotPassword: jest.fn() },
}));

const mockSignIn = jest.fn();

// Re-assign in beforeEach after clearAllMocks
beforeEach(() => {
  jest.clearAllMocks();
  // mockSignIn is already reset — re-apply specific implementations per test
});

To access the mock object for a module, use jest.requireMock (not jest.mock return value):

const { apiService } = jest.requireMock('../../../services/api') as {
  apiService: { forgotPassword: jest.Mock };
};

Running tests

npm test                  # interactive watch mode

Pull Request workflow

Every piece of work — no matter how small — follows this process from start to merge.

1. Create a branch

One branch per GitHub Issue. Branch off from develop, never from main:

git checkout develop
git pull
git checkout -b your-issue-title

2. Open a PR against develop

When your work is ready (or ready for early feedback), open a Pull Request targeting the develop branch — not main.

PR description should include:

• a one-line summary of what changed
• a link to the issue (Closes #123)

3. Pass all quality gates

Every PR triggers a SonarQube analysis and the full test suite. All of the following must be green before a merge is allowed:

Gate	Requirement
Test suite	All existing and new tests must pass — zero failures
Coverage on new code	≥ 30% line coverage on code introduced in this PR
Code duplication	< 3% duplication across the diff
SonarQube violations	No security or reliability related issues introduced

If any gate fails, fix the issues and push again — the checks re-run automatically.

4. Request a review

Once all gates are green, request a review via the GitHub PR interface.