test: setup component tests

.github/changes-filters.yml

@@ -15,3 +15,16 @@ backend:
   - 'phpunit.unit.xml'
   - '.php-cs-fixer.dist.php'
   - 'psalm.xml'
+frontend:
+  - '.github/workflows/**'
+  - 'src/**'
+  - 'appinfo/info.xml'
+  - 'package.json'
+  - 'package-lock.json'
+  - 'tsconfig.json'
+  - 'tests/javascript'
+  - '**.js'
+  - '**.mjs'
+  - '**.ts'
+  - '**.mts'
+  - '**.vue'

.github/workflows/component-test.yml

@@ -0,0 +1,109 @@
+# This workflow is provided via the organization template repository
+#
+# https://github.com/nextcloud/.github
+# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
+#
+# SPDX-FileCopyrightText: 2023-2024 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: MIT
+
+name: Component tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+      - stable*
+
+permissions:
+  contents: read
+
+concurrency:
+  group: component-tests-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest-low
+    permissions:
+      contents: read
+      pull-requests: read
+
+    outputs:
+      frontend: ${{ steps.changes.outputs.frontend }}
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          sparse-checkout: .github/changes-filters.yml
+          sparse-checkout-cone-mode: false
+
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: changes
+        continue-on-error: true
+        with:
+          filters: .github/changes-filters.yml
+
+  test:
+    runs-on: ubuntu-latest
+
+    needs: changes
+    if: needs.changes.outputs.frontend != 'false'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Read package.json node and npm engines version
+        uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
+        id: versions
+        with:
+          fallbackNode: '^24'
+          fallbackNpm: '^11.3'
+
+      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: ${{ steps.versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
+        run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'
+
+      - name: Install dependencies & build
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+        run: |
+          npm ci
+          npm run build --if-present
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run component tests
+        run: npm run test:component
+
+      - name: Upload component test reports
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          path: playwright-report
+          retention-days: 7
+          if-no-files-found: error
+
+  summary:
+    permissions:
+      contents: none
+    runs-on: ubuntu-latest-low
+    needs: [changes, test]
+
+    if: always()
+
+    name: component-test-summary
+
+    steps:
+      - name: Summary status
+        run: if ${{ needs.changes.outputs.frontend != 'false' && needs.test.result != 'success' }}; then exit 1; fi

.github/workflows/node-test.yml

@@ -31,32 +31,26 @@ jobs:
       pull-requests: read
 
     outputs:
-      src: ${{ steps.changes.outputs.src}}
+      frontend: ${{ steps.changes.outputs.frontend }}
 
     steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          sparse-checkout: .github/changes-filters.yml
+          sparse-checkout-cone-mode: false
+
       - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         id: changes
         continue-on-error: true
         with:
-          filters: |
-            src:
-              - '.github/workflows/**'
-              - '__tests__/**'
-              - '__mocks__/**'
-              - 'src/**'
-              - 'appinfo/info.xml'
-              - 'package.json'
-              - 'package-lock.json'
-              - 'tsconfig.json'
-              - '**.js'
-              - '**.ts'
-              - '**.vue'
+          filters: .github/changes-filters.yml
 
   test:
     runs-on: ubuntu-latest
 
     needs: changes
-    if: needs.changes.outputs.src != 'false'
+    if: needs.changes.outputs.frontend != 'false'
 
     steps:
       - name: Checkout
@@ -109,4 +103,4 @@ jobs:
 
     steps:
       - name: Summary status
-        run: if ${{ needs.changes.outputs.src != 'false' && needs.test.result != 'success' }}; then exit 1; fi
+        run: if ${{ needs.changes.outputs.frontend != 'false' && needs.test.result != 'success' }}; then exit 1; fi

.github/workflows/update-styling.yml

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: MIT
+
+# Periodically pull server styles into this repo for reproducible component tests.
+# Adapted from https://github.com/nextcloud-libraries/nextcloud-vue/blob/ac7e60606aee3d38f51b5385beb2f4e61a94c0ed/.github/workflows/server-styling-update.yml
+
+name: Update server styling
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 5 * * *"
+
+jobs:
+  server-styling-update:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        branch: ['main', 'stable6.6', 'stable6.5']
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          ref: ${{ matrix.branch }}
+
+      - name: Download CSS
+        # Removes sourceMappingURL from downloaded to avoid warning about missing source maps.
+        # Alternativly we could pull and check in all the source maps.
+        run: |
+          cd tests/javascript/component/gallery/assets/server
+          curl https://nextcloud.github.io/server/apps/theming/css/default.css > apps/theming/css/default.css
+          curl https://nextcloud.github.io/server/core/css/server.css |  sed 's|/\*# sourceMappingURL=[^*]*\*/||' > core/css/server.css
+          curl https://nextcloud.github.io/server/dist/icons.css > dist/icons.css 
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ secrets.COMMAND_BOT_PAT }}
+          author: nextcloud-command <nextcloud-command@users.noreply.github.com>
+          committer: nextcloud-command <nextcloud-command@users.noreply.github.com>
+          commit-message: "chore(tests): update component test styling from server"
+          signoff: true
+          branch: 'automated/${{ github.run_id }}/server-styling-update-${{ matrix.branch }}'
+          title: '[${{ matrix.branch }}] chore(docs): Automated styling update from server'
+          add-paths: styleguide/assets
+          body: |
+            Auto-generated update of our locally cached CSS styling from https://nextcloud.github.io
+          labels: |
+            dependencies
+            3. to review

.gitignore

@@ -86,7 +86,7 @@ src/fonts
 *.clover
 
 # CSS extracted from the JS build (CssExtractRspackPlugin)
-css/
+/css/
 
 # just sane ignores
 .*.sw[po]

README.md

@@ -74,6 +74,33 @@ composer test
 npm run test
 ```
 
+Front-end tests are split into unit tests ([Vitest](https://vitest.dev/)), component tests and end-to-end tests (both [Playwright](https://playwright.dev/)):
+
+```sh
+npm run test:unit             # Vitest unit tests
+npm run test:component        # Playwright component tests
+```
+
+### Updating Playwright snapshots
+
+Component tests compare screenshots against committed baseline snapshots. If your change intentionally alters
+rendered output, regenerate them with:
+
+```sh
+npm run test:component:update-snapshots   # regenerate component test snapshots
+```
+
+### Running the Playwright GUI in a container/remote environment
+
+`npm run test:component:ui` and `npm run test:e2e:ui` open Playwright's UI mode, which normally launches a window on
+your local machine. When running inside a devcontainer, Codespace, SSH remote, or any other headless environment, use the
+`:remote` variants instead, which serve the UI over HTTP so it can be reached through a forwarded port in your local browser:
+
+```sh
+npm run test:component:ui:remote   # component tests UI, served on port 13000
+npm run test:e2e:ui:remote          # end-to-end tests UI, served on port 13000
+```
+
 ## :v: Code of conduct
 
 The Nextcloud community has core values that are shared between all members during conferences,

REUSE.toml

@@ -29,6 +29,13 @@ precedence = "aggregate"
 SPDX-FileCopyrightText = "2020 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
+[[annotations]]
+path = ["tests/javascript/component/snapshots/**", "tests/javascript/component/gallery/assets/server/dist/icons.css"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "Nextcloud GmbH and Nextcloud contributors"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+
 [[annotations]]
 path = ["screenshots/2.0/change-view.png", "screenshots/2.0/date-picker.png", "screenshots/2.0/edit-calendar-properties.png", "screenshots/2.0/event-editor-attendees.png", "screenshots/2.0/event-editor-details-categories.jpg", "screenshots/2.0/event-editor-details.png", "screenshots/2.0/event-editor-reminders.png", "screenshots/2.0/event-editor-repeat-day-of-month.png", "screenshots/2.0/event-editor-repeat-last-thursday.png", "screenshots/2.0/freebusy.png", "screenshots/2.0/month-view.png", "screenshots/2.0/new-calendar-selector.png", "screenshots/2.0/public-sharing-embed.png", "screenshots/2.0/public-sharing.png", "screenshots/2.0/share-calendar-publicly-embed-link.png", "screenshots/2.0/share-calendar-user.png", "screenshots/2.0/simple-event-popover.png", "screenshots/2.0/week-view.png"]
 precedence = "aggregate"

package.json

@@ -28,11 +28,17 @@
     "lint:fix": "eslint src --fix",
     "stylelint": "stylelint \"css/*.css\" \"css/*.scss\" \"src/**/*.scss\" \"src/**/*.vue\"",
     "stylelint:fix": "stylelint \"css/*.css\" \"css/*.scss\" \"src/**/*.scss\" \"src/**/*.vue\" --fix",
+    "test:component": "playwright test --config playwright-ct.config.mts",
+    "test:component:ui": "playwright test --config playwright-ct.config.mts --ui",
+    "test:component:ui:remote": "playwright test --config playwright-ct.config.mts --ui-host=0.0.0.0 --ui-port=13000",
+    "test:component:update-snapshots": "playwright test --config playwright-ct.config.mts --update-snapshots",
     "test:unit": "LANG=C vitest --run",
     "test:unit:watch": "LANG=C vitest --watch",
     "test:unit:coverage": "LANG=C vitest run --coverage",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
+    "test:e2e:ui:remote": "playwright test --ui-host=0.0.0.0 --ui-port=13000",
+    "test:e2e:update-snapshots": "playwright test --update-snapshots",
     "ts:check": "tsc --noEmit"
   },
   "dependencies": {
@@ -94,6 +100,7 @@
     "@rsdoctor/rspack-plugin": "^1.6.3",
     "@rspack/cli": "^2.2.2",
     "@rspack/core": "^2.2.2",
+    "@rspack/dev-server": "^2.2.1",
     "@rspack/plugin-node-polyfill": "^0.5.8",
     "@types/node": "^26.4.1",
     "@vitejs/plugin-vue": "^6.0.8",

playwright-ct.config.mts

@@ -0,0 +1,30 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { defineConfig, devices } from '@playwright/test'
+
+const GALLERY_URL = 'http://localhost:5173/index.html'
+
+export default defineConfig({
+	testDir: 'tests/javascript/component',
+	snapshotDir: 'tests/javascript/component/snapshots',
+	forbidOnly: !!process.env.CI,
+	fullyParallel: true,
+	workers: process.env.CI ? 1 : undefined,
+	reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'html',
+
+	use: {
+		...devices['Desktop Chrome'],
+		baseURL: GALLERY_URL,
+		serviceWorkers: 'block',
+		reuseContext: true,
+		trace: 'retain-on-failure',
+	},
+	webServer: {
+		command: 'npx rspack serve --config rspack-ct.config.mts',
+		url: GALLERY_URL,
+		reuseExistingServer: !process.env.CI,
+	},
+})