test: add server-free unit tests for note, path and cursor logic

.github/workflows/phpunit-unit.yml

@@ -0,0 +1,74 @@
+# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: MIT
+
+name: PHPUnit unit
+
+on: pull_request
+
+permissions:
+  contents: read
+
+concurrency:
+  group: phpunit-unit-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  matrix:
+    runs-on: ubuntu-latest-low
+    outputs:
+      php-versions: ${{ steps.versions.outputs.php-versions }}
+    steps:
+      - name: Checkout app
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Get version matrix
+        id: versions
+        uses: icewind1991/nextcloud-version-matrix@8a7bac6300b2f0f3100088b297995a229558ddba # v1.0.0
+
+  unit-tests:
+    runs-on: ubuntu-latest
+    needs: matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        php-versions: ${{fromJson(needs.matrix.outputs.php-versions)}}
+
+    name: unit-tests (php ${{ matrix.php-versions }})
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up php ${{ matrix.php-versions }}
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: ctype, curl, dom, fileinfo, iconv, intl, json, libxml, mbstring, openssl, posix, simplexml, xmlreader, xmlwriter, zip, zlib
+          coverage: none
+          ini-file: development
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress
+
+      - name: Run unit tests
+        run: composer run test:unit
+
+  summary:
+    permissions:
+      contents: none
+    runs-on: ubuntu-latest-low
+    needs: unit-tests
+
+    if: always()
+
+    name: unit-tests-summary
+
+    steps:
+      - name: Summary status
+        run: if ${{ needs.unit-tests.result != 'success' && needs.unit-tests.result != 'skipped' }}; then exit 1; fi

.gitignore

@@ -8,6 +8,8 @@ report
 coverage/
 clover.xml
 .php-cs-fixer.cache
+.phpunit.cache/
+.phpunit.result.cache
 appinfo/info.xsd
 
 # just sane ignores

AGENTS.md

@@ -47,14 +47,16 @@ Setup: `make dev-setup` (runs `composer install` + `npm install`). Requires PHP
 - `npm run stylelint` / `npm run stylelint:fix`
 
 ### PHP
+- `composer run test:unit` — PHPUnit unit tests (`make test-unit`)
 - `composer run cs:check` / `composer run cs:fix` — php-cs-fixer (Nextcloud coding standard)
 - `composer run psalm` — static analysis
 - `composer run phan` — static analysis (CI uses `make lint-php-phan`)
 - `make lint` runs everything (PHP + JS + CSS + info.xml); `make lint-fix` auto-fixes
 
 ### Tests
-There are no PHP unit tests. Three suites exist:
+Four suites exist:
 
+- **PHP unit tests** (`tests/unit/`): PHPUnit against mocked OCP interfaces, no server, no database. `make test-unit` (or `composer run test:unit`). Only for logic reachable without a running Nextcloud — tree walking, path and title handling, cursor encoding. Run a single test: `./vendor/bin/phpunit -c tests/unit/phpunit.xml --filter testMethodName`
 - **JS unit tests** (`src/tests/`): vitest in jsdom, no server needed. `npm run test` (or `test:coverage`). For plain modules only — testing a component would need `@vitejs/plugin-vue` adding to `vitest.config.js`.
 - **API tests** (`tests/api/`): PHPUnit tests that make HTTP requests via Guzzle against a **running Nextcloud server at `http://localhost:8080`** with the app enabled and a user `test`/`test`. Run with `make test-api`. Run a single test: `phpunit --bootstrap vendor/autoload.php --filter testMethodName tests/api/APIv1Test.php`
 - **Playwright e2e** (`playwright/e2e/`): `npm run test:e2e` (or `test:e2e:ui`). Automatically starts a Nextcloud Docker container on port 8089 (requires Docker; up to 5 min for first start). Tests run with a single worker on purpose — the bundled server uses SQLite and flakes under parallel logins.

Makefile

@@ -6,7 +6,7 @@ app_name=notes
 project_dir=$(CURDIR)/../$(app_name)
 build_dir=$(CURDIR)/build/artifacts
 cert_dir=$(HOME)/.nextcloud/certificates
-php_dirs=appinfo/ lib/ tests/api/
+php_dirs=appinfo/ lib/ tests/api/ tests/unit/
 
 
 all: dev-setup build
@@ -87,7 +87,10 @@ watch-js:
 
 ##### Testing #####
 
-test: test-api
+test: test-unit test-api
+
+test-unit:
+	composer run test:unit
 
 test-api:
 	phpunit --bootstrap vendor/autoload.php --testdox tests/api/

composer.json

@@ -1,17 +1,21 @@
 {
 	"require-dev": {
+		"doctrine/dbal": "^4",
 		"guzzlehttp/guzzle": "^8",
 		"nextcloud/coding-standard": "^1.0",
 		"nextcloud/ocp": "dev-stable33",
 		"phan/phan": "^6",
 		"php-cs-fixer/shim": "3.95.23",
+		"phpunit/phpunit": "^10",
 		"psalm/phar": "^5.26",
 		"squizlabs/php_codesniffer": "^4",
 		"staabm/annotate-pull-request-from-checkstyle": "^1.1.0"
 	},
 	"autoload-dev": {
 		"psr-4": {
+			"OCA\\Notes\\": "lib/",
 			"OCA\\Notes\\Tests\\API\\": "tests/api/",
+			"OCA\\Notes\\Tests\\Unit\\": "tests/unit/",
 			"OCP\\": "vendor/nextcloud/ocp/OCP/",
 			"OC\\": "vendor/nextcloud/ocp/OC/"
 		}