ci: run Go tests on Windows (#5380)

* ci(windows): add skeleton go-windows job (compile-only smoke test)

* ci(windows): fix comment to reference Task 7 not Task 6

* ci(windows): harden PATH visibility and set explicit bash shell

* ci(windows): enable full go test suite and ndpgen check

* test(gotaglib): skip Unix-only permission tests on Windows

* test(lyrics): skip Windows-incompatible tests

* test(utils): skip Windows-incompatible tests

* test(mpv): skip Windows-incompatible playback tests

Skip 3 subprocess-execution tests that rely on Unix-style mpv
invocation; .bat output includes \r-terminated lines that break
argument parsing (#TBD-mpv-windows).

* test(storage): skip Windows-incompatible tests

Skip relative-path test where filepath.Join uses backslash but the
storage implementation returns a forward-slash URL path
(#TBD-path-sep-storage).

* test(storage/local): skip Windows-incompatible tests

Skip 13 tests that fail because url.Parse("file://" + windowsPath)
treats the drive letter colon as an invalid port; also skip the
Windows drive-letter path test that exposes a backslash vs
forward-slash normalisation bug (#TBD-path-sep-storage-local).

* test(playlists): skip Windows-incompatible tests

* test(model): skip Windows-incompatible tests

* test(model/metadata): skip Windows-incompatible tests

* test(core): skip Windows-incompatible tests

AbsolutePath uses filepath.Join which produces OS-native path separators;
skip the assertion test on Windows until the production code is fixed
(#TBD-path-sep-core).

* test(artwork): skip Windows-incompatible tests

Artwork readers produce OS-native path separators on Windows while tests
assert forward-slash paths; skip 11 affected tests pending a fix in
production code (#TBD-path-sep-artwork).

* test(persistence): skip Windows-incompatible tests

Skip flaky timestamp comparison (#TBD-flake-persistence) and path-separator
real-bugs (#TBD-path-sep-persistence) in FolderRepository.GetFolderUpdateInfo
which uses filepath.Clean/os.PathSeparator converting stored forward-slash paths
to backslashes on Windows.

* test(scanner): skip Windows-incompatible tests

Skip symlink tests (Unix-assumption), ndignore path-separator bugs
(#TBD-path-sep-scanner) in processLibraryEvents/resolveFolderPath where
filepath.Rel/filepath.Split return backslash paths incompatible with fs.FS
forward-slash expectations, error message mismatch on Windows, and file
format upgrade detection (#TBD-path-sep-scanner).

* test(plugins): skip Windows-incompatible tests

Add //go:build !windows tags to test files that reference the suite
bootstrap (testManager, testdataDir, createTestManager) which is only
compiled on non-Windows. Add a Windows-only suite stub that skips all
specs via BeforeEach to prevent [build failed] on Windows CI.

* test(server): skip Windows-incompatible tests

Skip createUnixSocketFile tests that rely on Unix file permission bits
(chmod/fchmod) which are not supported on Windows.

* test(nativeapi): skip Windows-incompatible tests

Skip the i18n JSON validation test that uses filepath.Join to build
embedded-FS paths; filepath.Join produces backslashes on Windows which
breaks fs.Open (embedded FS always uses forward slashes).

* test(e2e): skip Windows-incompatible tests

On Windows, SQLite holds file locks that prevent the Ginkgo TempDir
DeferCleanup from deleting the DB file. Register an explicit db.Close
DeferCleanup (LIFO before TempDir cleanup) on Windows so the file lock
is released before the temp directory is removed.

* test(windows): fix e2e AfterSuite and skip remaining scanner path test

* test(scanner): skip another Windows path-sep test (#TBD-path-sep-scanner)

* test(subsonic): skip timing-flaky test on Windows (#TBD-flake-time-resolution-subsonic)

* test(scanner): skip 'detects file moved to different folder' on Windows

* test(scanner): consolidate 'Library changes' Windows skips into BeforeEach

* test(scanner): close DB before TempDir cleanup to fix Windows file lock

* test(scanner): skip ScanFolders suite on Windows instead of closing shared DB

* ci: retrigger for Windows soak run 2/3

* ci: retrigger for Windows soak run 3/3

* ci: retrigger for Windows soak run 3/3 (take 2)

* test(scanner): skip Multi-Library suite on Windows (SQLite file lock)

* ci(windows): promote go-windows to blocking status check

* test(plugins): run platform-neutral specs on Windows, drop blanket Skip

* test(windows): make tests cross-platform instead of skipping

- subsonic: back-date submissionTime baseline by 1s so
  BeTemporally(">") passes under millisecond clock resolution
- persistence: sleep briefly between Put calls so UpdatedAt is
  strictly after CreatedAt on low-resolution clocks
- utils/files: close tempFile before os.Remove so the test works on
  Windows (where an open handle holds a file lock)
- tests.TempFile: close the handle before returning; metadata tests
  no longer leak the open file into Ginkgo's TempDir cleanup

Resolves Copilot review comments on #5380.

* test(tests): add SkipOnWindows helper to reduce boilerplate

Introduces tests.SkipOnWindows(reason) that wraps the 3-line
runtime.GOOS guard pattern used in every Windows-skipped spec.

* test(adapters): use tests.SkipOnWindows helper

* test(core): use tests.SkipOnWindows helper

* test(model): use tests.SkipOnWindows helper

* test(persistence): use tests.SkipOnWindows helper

* test(scanner): use tests.SkipOnWindows helper

* test(server): use tests.SkipOnWindows helper

* test(plugins): run pure-Go unit tests on Windows

config_validation_test, manager_loader_test, and migrate_test have no
WASM/exec dependencies and don't rely on the make-built test plugins
from plugins_suite_test.go. Let them run on Windows too.

.github/workflows/pipeline.yml

@@ -120,6 +120,79 @@ jobs:
           go build -o ndpgen .
           ./ndpgen --help
 
+  go-windows:
+    name: Test Go code (Windows)
+    runs-on: windows-2022
+    env:
+      FFMPEG_VERSION: "7.1"
+      FFMPEG_REPOSITORY: navidrome/ffmpeg-windows-builds
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          install: mingw-w64-x86_64-gcc
+          update: false
+
+      - name: Add mingw64 to PATH
+        shell: bash
+        run: echo "C:/msys64/mingw64/bin" >> $GITHUB_PATH
+
+      - name: Cache ffmpeg
+        id: ffmpeg-cache
+        uses: actions/cache@v4
+        with:
+          path: C:\ffmpeg
+          key: ffmpeg-${{ env.FFMPEG_VERSION }}-win64
+
+      - name: Download ffmpeg
+        if: steps.ffmpeg-cache.outputs.cache-hit != 'true'
+        shell: pwsh
+        run: |
+          $asset = "ffmpeg-n${env:FFMPEG_VERSION}-latest-win64-gpl-${env:FFMPEG_VERSION}"
+          $url = "https://github.com/${env:FFMPEG_REPOSITORY}/releases/download/latest/$asset.zip"
+          Invoke-WebRequest -Uri $url -OutFile ffmpeg.zip
+          Expand-Archive ffmpeg.zip -DestinationPath C:\ffmpeg-extracted
+          New-Item -ItemType Directory -Force -Path C:\ffmpeg\bin | Out-Null
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffmpeg.exe"  C:\ffmpeg\bin
+          Copy-Item "C:\ffmpeg-extracted\$asset\bin\ffprobe.exe" C:\ffmpeg\bin
+
+      - name: Add ffmpeg to PATH
+        shell: bash
+        run: echo "C:/ffmpeg/bin" >> $GITHUB_PATH
+
+      - name: Verify toolchain
+        shell: pwsh
+        run: |
+          go version
+          where.exe gcc
+          gcc --version
+          ffmpeg -version
+          ffprobe -version
+
+      - name: Download dependencies
+        shell: bash
+        run: go mod download
+
+      - name: Test
+        shell: bash
+        env:
+          CGO_ENABLED: "1"
+        run: go test -shuffle=on -tags netgo,sqlite_fts5 ./... -v
+
+      - name: Test ndpgen
+        shell: pwsh
+        run: |
+          cd plugins\cmd\ndpgen
+          go test -shuffle=on -v
+          go build -o ndpgen.exe .
+          .\ndpgen.exe --help
+
   js:
     name: Test JS code
     runs-on: ubuntu-latest
@@ -184,7 +257,7 @@ jobs:
 
   build:
     name: Build
-    needs: [js, go, go-lint, i18n-lint, git-version, check-push-enabled]
+    needs: [js, go, go-windows, go-lint, i18n-lint, git-version, check-push-enabled]
     strategy:
       matrix:
         platform: [ linux/amd64, linux/arm64, linux/arm/v5, linux/arm/v6, linux/arm/v7, linux/386, linux/riscv64, darwin/amd64, darwin/arm64, windows/amd64, windows/386 ]

adapters/gotaglib/gotaglib_test.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"strings"
 
+	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
@@ -213,6 +214,7 @@ var _ = Describe("Extractor", func() {
 			// Only run permission tests if we are not root
 			RegularUserContext("when run without root privileges", func() {
 				BeforeEach(func() {
+					tests.SkipOnWindows("uses Unix file permission bits")
 					// Use root fs for absolute paths in temp directory
 					e = &extractor{fs: os.DirFS("/")}
 					accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")

core/artwork/artwork_internal_test.go

@@ -80,6 +80,7 @@ var _ = Describe("Artwork", func() {
 				})
 			})
 			It("returns embed cover", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				aw, err := newAlbumArtworkReader(ctx, aw, alOnlyEmbed.CoverArtID(), nil)
 				Expect(err).ToNot(HaveOccurred())
 				_, path, err := aw.Reader(ctx)
@@ -103,6 +104,7 @@ var _ = Describe("Artwork", func() {
 				})
 			})
 			It("returns external cover", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				folderRepo.result = []model.Folder{{
 					Path:       "tests/fixtures/artist/an-album",
 					ImageFiles: []string{"front.png"},
@@ -133,6 +135,7 @@ var _ = Describe("Artwork", func() {
 			})
 			DescribeTable("CoverArtPriority",
 				func(priority string, expected string) {
+					tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 					conf.Server.CoverArtPriority = priority
 					aw, err := newAlbumArtworkReader(ctx, aw, alMultipleCovers.CoverArtID(), nil)
 					Expect(err).ToNot(HaveOccurred())
@@ -210,6 +213,7 @@ var _ = Describe("Artwork", func() {
 			})
 			DescribeTable("ArtistArtPriority",
 				func(priority string, expected string) {
+					tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 					conf.Server.ArtistArtPriority = priority
 					aw, err := newArtistArtworkReader(ctx, aw, arMultipleCovers.CoverArtID(), nil)
 					Expect(err).ToNot(HaveOccurred())
@@ -247,6 +251,7 @@ var _ = Describe("Artwork", func() {
 				})
 			})
 			It("returns embed cover", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				aw, err := newMediafileArtworkReader(ctx, aw, mfWithEmbed.CoverArtID())
 				Expect(err).ToNot(HaveOccurred())
 				_, path, err := aw.Reader(ctx)
@@ -254,6 +259,7 @@ var _ = Describe("Artwork", func() {
 				Expect(path).To(Equal("tests/fixtures/test.mp3"))
 			})
 			It("returns embed cover if successfully extracted by ffmpeg", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				aw, err := newMediafileArtworkReader(ctx, aw, mfCorruptedCover.CoverArtID())
 				Expect(err).ToNot(HaveOccurred())
 				r, path, err := aw.Reader(ctx)

core/artwork/reader_artist_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -61,6 +62,7 @@ var _ = Describe("artistArtworkReader", func() {
 
 		When("artist has only one album", func() {
 			It("returns the parent folder", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				paths = []string{
 					filepath.FromSlash("/music/artist/album1"),
 				}
@@ -86,6 +88,7 @@ var _ = Describe("artistArtworkReader", func() {
 
 		When("the album paths contain same prefix", func() {
 			It("returns the common prefix", func() {
+				tests.SkipOnWindows("artwork path handling (#TBD-path-sep-artwork)")
 				paths = []string{
 					filepath.FromSlash("/music/artist/album1"),
 					filepath.FromSlash("/music/artist/album2"),

core/common_test.go

@@ -41,6 +41,7 @@ var _ = Describe("common.go", func() {
 		})
 
 		It("returns the absolute path when library exists", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-core)")
 			ctx := context.Background()
 			abs := AbsolutePath(ctx, ds, libId, path)
 			Expect(abs).To(Equal("/library/root/music/file.mp3"))

core/lyrics/lyrics_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/lyrics"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	"github.com/navidrome/navidrome/utils"
 	"github.com/navidrome/navidrome/utils/gg"
 	. "github.com/onsi/ginkgo/v2"
@@ -93,6 +94,7 @@ var _ = Describe("sources", func() {
 			var accessForbiddenFile string
 
 			BeforeEach(func() {
+				tests.SkipOnWindows("uses Unix file permission bits")
 				accessForbiddenFile = utils.TempFileName("access_forbidden-", ".mp3")
 
 				f, err := os.OpenFile(accessForbiddenFile, os.O_WRONLY|os.O_CREATE, 0222)

core/playback/mpv/mpv_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -199,6 +200,7 @@ var _ = Describe("MPV", func() {
 		})
 
 		It("executes MPV command and captures arguments correctly", func() {
+			tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
 
@@ -226,6 +228,7 @@ var _ = Describe("MPV", func() {
 		})
 
 		It("handles file paths with spaces", func() {
+			tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 			ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
 
@@ -253,6 +256,7 @@ var _ = Describe("MPV", func() {
 			})
 
 			It("passes all snapcast arguments correctly", func() {
+				tests.SkipOnWindows("mpv binary not available in CI (#TBD-mpv-windows)")
 				ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
 

core/playlists/import_test.go

@@ -183,6 +183,7 @@ var _ = Describe("Playlists - Import", func() {
 			})
 
 			It("rejects #EXTALBUMARTURL with absolute path outside library boundaries", func() {
+				tests.SkipOnWindows("relies on Unix /etc filesystem")
 				tmpDir := GinkgoT().TempDir()
 
 				m3u := "#EXTALBUMARTURL:/etc/passwd\ntest.mp3\n"
@@ -320,6 +321,7 @@ var _ = Describe("Playlists - Import", func() {
 				Expect(pls.Rules.Expression).To(BeAssignableToTypeOf(criteria.All{}))
 			})
 			It("returns an error if the playlist is not well-formed", func() {
+				tests.SkipOnWindows("line-ending differences affect JSON error offset")
 				_, err := ps.ImportFile(ctx, folder, "invalid_json.nsp")
 				Expect(err.Error()).To(ContainSubstring("line 19, column 1: invalid character '\\n'"))
 			})
@@ -347,6 +349,7 @@ var _ = Describe("Playlists - Import", func() {
 
 		DescribeTable("Playlist filename Unicode normalization (regression fix-playlist-filename-normalization)",
 			func(storedForm, filesystemForm string) {
+				tests.SkipOnWindows("/tmp hardcoded in test")
 				// Use Polish characters that decompose: ó (U+00F3) -> o + combining acute (U+006F + U+0301)
 				plsNameNFC := "Piosenki_Polskie_zółć" // NFC form (composed)
 				plsNameNFD := norm.NFD.String(plsNameNFC)
@@ -821,6 +824,7 @@ var _ = Describe("Playlists - Import", func() {
 		})
 
 		It("returns true if folder is in PlaylistsPath", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 			conf.Server.PlaylistsPath = "other/**:playlists/**"
 			Expect(playlists.InPath(folder)).To(BeTrue())
 		})

core/playlists/parse_m3u_test.go

@@ -15,6 +15,7 @@ var _ = Describe("libraryMatcher", func() {
 	ctx := context.Background()
 
 	BeforeEach(func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 		mockLibRepo = &tests.MockLibraryRepo{}
 		ds = &tests.MockDataStore{
 			MockedLibrary: mockLibRepo,
@@ -196,6 +197,7 @@ var _ = Describe("pathResolver", func() {
 	ctx := context.Background()
 
 	BeforeEach(func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-playlists)")
 		mockLibRepo = &tests.MockLibraryRepo{}
 		ds = &tests.MockDataStore{
 			MockedLibrary: mockLibRepo,

core/storage/local/local_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/model/metadata"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -44,6 +45,10 @@ var _ = Describe("LocalStorage", func() {
 	})
 
 	Describe("newLocalStorage", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with valid path", func() {
 			It("should create a localStorage instance with correct path", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -166,6 +171,10 @@ var _ = Describe("LocalStorage", func() {
 	})
 
 	Describe("localStorage.FS", func() {
+		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
+		})
+
 		Context("with existing directory", func() {
 			It("should return a localFS instance", func() {
 				u, err := url.Parse("file://" + tempDir)
@@ -199,6 +208,7 @@ var _ = Describe("LocalStorage", func() {
 		var testFile string
 
 		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// Create a test file
 			testFile = filepath.Join(tempDir, "test.mp3")
 			err := os.WriteFile(testFile, []byte("test data"), 0600)
@@ -380,6 +390,7 @@ var _ = Describe("LocalStorage", func() {
 
 	Describe("Storage registration", func() {
 		It("should register localStorage for file scheme", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage-local)")
 			// This tests the init() function indirectly
 			storage, err := storage.For("file://" + tempDir)
 			Expect(err).ToNot(HaveOccurred())

core/storage/storage_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -54,6 +55,7 @@ var _ = Describe("Storage", func() {
 			Expect(s.(*fakeLocalStorage).u.Path).To(Equal("/tmp"))
 		})
 		It("should return a file implementation for a relative folder", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-storage)")
 			s, err := For("tmp")
 			Expect(err).ToNot(HaveOccurred())
 			cwd, _ := os.Getwd()

model/folder_test.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -66,6 +67,7 @@ var _ = Describe("Folder", func() {
 
 		When("the folder has multiple subdirs", func() {
 			It("should return the correct folder ID", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 				folderPath := filepath.FromSlash("/music/rock/metal")
 				expectedID := id.NewHash("1:rock/metal")
 				Expect(model.FolderID(lib, folderPath)).To(Equal(expectedID))
@@ -75,6 +77,7 @@ var _ = Describe("Folder", func() {
 
 	Describe("NewFolder", func() {
 		It("should create a new SubFolder with the correct attributes", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 			folderPath := filepath.FromSlash("rock/metal")
 			folder := model.NewFolder(lib, folderPath)
 

model/mediafile_test.go

@@ -6,6 +6,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	. "github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -447,6 +448,9 @@ var _ = Describe("MediaFiles", func() {
 
 			DescribeTable("generates correct output",
 				func(absolutePaths bool, expectedContent string) {
+					if absolutePaths {
+						tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
+					}
 					result := mfs.ToM3U8("Multi Track", absolutePaths)
 					Expect(result).To(Equal(expectedContent))
 				},
@@ -467,6 +471,7 @@ var _ = Describe("MediaFiles", func() {
 
 		Context("path variations", func() {
 			It("handles different path structures", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 				mfs = MediaFiles{
 					{Title: "Root", Artist: "Artist", Duration: 60, Path: "song.mp3", LibraryPath: "/lib"},
 					{Title: "Nested", Artist: "Artist", Duration: 60, Path: "deep/nested/song.mp3", LibraryPath: "/lib"},

model/metadata/persistent_ids_test.go

@@ -6,6 +6,7 @@ import (
 	"github.com/navidrome/navidrome/conf"
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -79,6 +80,7 @@ var _ = Describe("getPID", func() {
 		})
 		When("field is folder", func() {
 			It("should return the pid", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-metadata)")
 				spec := "folder|title"
 				md.tags = map[model.TagName][]string{"title": {"title"}}
 				mf.Path = "/path/to/file.mp3"

model/playlist_test.go

@@ -2,6 +2,7 @@ package model_test
 
 import (
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -27,6 +28,7 @@ var _ = Describe("Playlist", func() {
 			}
 		})
 		It("generates the correct M3U format", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-model)")
 			expected := `#EXTM3U
 #PLAYLIST:Mellow sunset
 #EXTINF:378,Morcheeba feat. Kurt Wagner - What New York Couples Fight About

persistence/folder_repository_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
 	"github.com/navidrome/navidrome/model/request"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"github.com/pocketbase/dbx"
@@ -99,6 +100,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("includes all child folders when querying parent", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create a parent folder with multiple children
 				parent := model.NewFolder(testLib, "TestParent/Music")
 				child1 := model.NewFolder(testLib, "TestParent/Music/Rock/Queen")
@@ -120,6 +122,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes children from other libraries", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent in testLib
 				parent := model.NewFolder(testLib, "TestIsolation/Parent")
 				child := model.NewFolder(testLib, "TestIsolation/Parent/Child")
@@ -145,6 +148,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("excludes missing children when querying parent", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create parent and children, mark one as missing
 				parent := model.NewFolder(testLib, "TestMissingChild/Parent")
 				child1 := model.NewFolder(testLib, "TestMissingChild/Parent/Child1")
@@ -165,6 +169,7 @@ var _ = Describe("FolderRepository", func() {
 			})
 
 			It("handles mix of existing and non-existing target paths", func() {
+				tests.SkipOnWindows("path storage (#TBD-path-sep-persistence)")
 				// Create folders for one path but not the other
 				existingParent := model.NewFolder(testLib, "TestMixed/Exists")
 				existingChild := model.NewFolder(testLib, "TestMixed/Exists/Child")

persistence/library_repository_test.go

@@ -2,6 +2,7 @@ package persistence
 
 import (
 	"context"
+	"time"
 
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model"
@@ -64,6 +65,11 @@ var _ = Describe("LibraryRepository", func() {
 				originalID := lib.ID
 				originalCreatedAt := lib.CreatedAt
 
+				// Ensure the update's timestamp is strictly greater than the
+				// create's timestamp on platforms with coarse clock resolution
+				// (Windows' time.Now() is millisecond-granular).
+				time.Sleep(2 * time.Millisecond)
+
 				// Now update it
 				lib.Name = "Updated Library"
 				lib.Path = "/music/updated"

plugins/config_validation_test.go

@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (

plugins/manager_loader_test.go

@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (

plugins/manager_test.go

@@ -1,3 +1,5 @@
+//go:build !windows
+
 package plugins
 
 import (

plugins/manager_watcher_test.go

@@ -1,3 +1,5 @@
+//go:build !windows
+
 package plugins
 
 import (

plugins/metadata_agent_test.go

@@ -1,3 +1,5 @@
+//go:build !windows
+
 package plugins
 
 import (

plugins/migrate_test.go

@@ -1,5 +1,3 @@
-//go:build !windows
-
 package plugins
 
 import (

plugins/plugins_suite_windows_test.go

@@ -0,0 +1,23 @@
+//go:build windows
+
+package plugins
+
+import (
+	"testing"
+
+	"github.com/navidrome/navidrome/log"
+	"github.com/navidrome/navidrome/tests"
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+)
+
+// Runs the subset of plugin specs compiled on Windows (files without the
+// //go:build !windows tag): capabilities, manager_cache, manager_plugin,
+// manifest, package. WASM-runtime-dependent specs live in !windows-tagged
+// files and aren't reached here.
+func TestPlugins(t *testing.T) {
+	tests.Init(t, false)
+	log.SetLevel(log.LevelFatal)
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Plugins Suite")
+}

scanner/phase_4_playlists_test.go

@@ -111,6 +111,7 @@ var _ = Describe("phasePlaylists", func() {
 		})
 
 		It("reports an error if there is an error reading files", func() {
+			tests.SkipOnWindows("relies on Unix /etc filesystem")
 			progress := make(chan *ProgressInfo)
 			state.progress = progress
 			folder := &model.Folder{Path: "/invalid/path"}

scanner/scanner_multilibrary_test.go

@@ -43,6 +43,7 @@ var _ = Describe("Scanner - Multi-Library", Ordered, func() {
 	}
 
 	BeforeAll(func() {
+		tests.SkipOnWindows("SQLite file lock blocks TempDir cleanup (#TBD-path-sep-scanner)")
 		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "123", IsAdmin: true})
 		tmpDir := GinkgoT().TempDir()
 		conf.Server.DbPath = filepath.Join(tmpDir, "test-scanner-multilibrary.db?_journal_mode=WAL")

scanner/scanner_selective_test.go

@@ -34,6 +34,7 @@ var _ = Describe("ScanFolders", Ordered, func() {
 	var fsys storagetest.FakeFS
 
 	BeforeAll(func() {
+		tests.SkipOnWindows("SQLite file lock blocks TempDir cleanup (#TBD-path-sep-scanner)")
 		ctx = request.WithUser(GinkgoT().Context(), model.User{ID: "123", IsAdmin: true})
 		tmpDir := GinkgoT().TempDir()
 		conf.Server.DbPath = filepath.Join(tmpDir, "test-selective-scan.db?_journal_mode=WAL")

scanner/scanner_test.go

@@ -168,6 +168,7 @@ var _ = Describe("Scanner", Ordered, func() {
 			})
 
 			It("should update the album", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				Expect(runScanner(ctx, true)).To(Succeed())
 
 				albums, err := ds.Album(ctx).GetAll(model.QueryOptions{Filters: squirrel.Eq{"album.name": "Help!"}})
@@ -268,6 +269,7 @@ var _ = Describe("Scanner", Ordered, func() {
 		var beatlesMBID = uuid.NewString()
 
 		BeforeEach(func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 			By("Having two MP3 albums")
 			beatles := _t{
 				"artist":               "The Beatles",
@@ -872,6 +874,7 @@ var _ = Describe("Scanner", Ordered, func() {
 		})
 
 		It("should update artist stats during quick scans when new albums are added", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 			// Don't use the mocked artist repo for this test - we need the real one
 			ds.MockedArtist = nil
 

scanner/walk_dir_tree_test.go

@@ -12,6 +12,7 @@ import (
 	"github.com/navidrome/navidrome/conf/configtest"
 	"github.com/navidrome/navidrome/core/storage"
 	"github.com/navidrome/navidrome/model"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"golang.org/x/sync/errgroup"
@@ -229,6 +230,7 @@ var _ = Describe("walk_dir_tree", func() {
 
 			Context("with symlinks enabled", func() {
 				BeforeEach(func() {
+					tests.SkipOnWindows("symlink semantics")
 					conf.Server.Scanner.FollowSymlinks = true
 				})
 

scanner/watcher_test.go

@@ -389,6 +389,7 @@ var _ = Describe("Watcher", func() {
 			})
 
 			It("should NOT send notification when nested ignored folder is deleted", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				startEventProcessing()
 
 				// Simulate deletion of music/rock/artist/temp (matches **/temp)
@@ -402,6 +403,7 @@ var _ = Describe("Watcher", func() {
 			})
 
 			It("should send notification for non-ignored nested folder", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				startEventProcessing()
 
 				// Simulate change in music/rock/artist (doesn't match any pattern)
@@ -426,6 +428,7 @@ var _ = Describe("Watcher", func() {
 			})
 
 			It("should NOT send notification for file changes in ignored folders", func() {
+				tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 				startEventProcessing()
 
 				// Simulate file change in rock/_TEMP/file.mp3
@@ -464,11 +467,13 @@ var _ = Describe("resolveFolderPath", func() {
 	})
 
 	It("walks up to parent directory when given a file path", func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 		result := resolveFolderPath(mockFS, "artist1/album1/track1.mp3")
 		Expect(result).To(Equal("artist1/album1"))
 	})
 
 	It("walks up multiple levels if needed", func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 		result := resolveFolderPath(mockFS, "artist1/album1/nonexistent/file.mp3")
 		Expect(result).To(Equal("artist1/album1"))
 	})
@@ -489,6 +494,7 @@ var _ = Describe("resolveFolderPath", func() {
 	})
 
 	It("handles nested file paths correctly", func() {
+		tests.SkipOnWindows("path separator bug (#TBD-path-sep-scanner)")
 		result := resolveFolderPath(mockFS, "artist1/album2/song.flac")
 		Expect(result).To(Equal("artist1/album2"))
 	})

server/e2e/e2e_suite_test.go

@@ -470,6 +470,13 @@ var _ = BeforeSuite(func() {
 	Expect(os.WriteFile(snapshotPath, data, 0600)).To(Succeed())
 })
 
+// Close the database before the suite's TempDir cleanup runs. Required on
+// Windows where open SQLite handles hold file locks that block temp-dir
+// removal; harmless on other OSes.
+var _ = AfterSuite(func() {
+	db.Close(ctx)
+})
+
 // setupTestDB restores the database from the golden snapshot and creates the
 // Subsonic Router. Call this from BeforeEach/BeforeAll in each test container.
 func setupTestDB() {

server/nativeapi/translations_test.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/navidrome/navidrome/consts"
 	"github.com/navidrome/navidrome/resources"
+	"github.com/navidrome/navidrome/tests"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
@@ -16,6 +17,7 @@ import (
 var _ = Describe("Translations", func() {
 	Describe("I18n files", func() {
 		It("contains only valid json language files", func() {
+			tests.SkipOnWindows("path separator bug (#TBD-path-sep-nativeapi)")
 			fsys := resources.FS()
 			dir, _ := fsys.Open(consts.I18nFolder)
 			files, _ := dir.(fs.ReadDirFile).ReadDir(-1)

server/server_test.go

@@ -30,6 +30,7 @@ var _ = Describe("createUnixSocketFile", func() {
 
 	When("unixSocketPerm is valid", func() {
 		It("updates the permission of the unix socket file and returns nil", func() {
+			tests.SkipOnWindows("uses Unix file permission bits")
 			_, err := createUnixSocketFile(socketPath, "0777")
 			fileInfo, _ := os.Stat(socketPath)
 			actualPermission := fileInfo.Mode().Perm()
@@ -50,6 +51,7 @@ var _ = Describe("createUnixSocketFile", func() {
 
 	When("file already exists", func() {
 		It("recreates the file as a socket with the right permissions", func() {
+			tests.SkipOnWindows("uses Unix file permission bits")
 			_, err := os.Create(socketPath)
 			Expect(err).ToNot(HaveOccurred())
 			Expect(os.Chmod(socketPath, os.FileMode(0777))).To(Succeed())

server/subsonic/media_annotation_test.go

@@ -32,7 +32,9 @@ var _ = Describe("MediaAnnotationController", func() {
 
 	Describe("Scrobble", func() {
 		It("submit all scrobbles with only the id", func() {
-			submissionTime := time.Now()
+			// Back-date the baseline so the assertion still passes on platforms
+			// with millisecond clock resolution (e.g. Windows).
+			submissionTime := time.Now().Add(-time.Second)
 			r := newGetRequest("id=12", "id=34")
 
 			_, err := router.Scrobble(r)

tests/test_helpers.go

@@ -4,14 +4,25 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+	"runtime"
 
 	"github.com/navidrome/navidrome/db"
 	"github.com/navidrome/navidrome/log"
 	"github.com/navidrome/navidrome/model/id"
+	"github.com/onsi/ginkgo/v2"
 	"github.com/sirupsen/logrus"
 	"github.com/sirupsen/logrus/hooks/test"
 )
 
+// SkipOnWindows marks the current spec (or surrounding BeforeEach) as skipped
+// when running on Windows. The reason is included in the Ginkgo output so the
+// backlog of Windows-skipped tests stays auditable.
+func SkipOnWindows(reason string) {
+	if runtime.GOOS == "windows" {
+		ginkgo.Skip("not supported on Windows: " + reason)
+	}
+}
+
 type testingT interface {
 	TempDir() string
 }
@@ -20,10 +31,20 @@ func TempFileName(t testingT, prefix, suffix string) string {
 	return filepath.Join(t.TempDir(), prefix+id.NewRandom()+suffix)
 }
 
+// TempFile creates an empty file in t.TempDir() and returns the closed handle.
+// The handle is returned for backward compatibility, but is already closed so
+// callers don't need to. On Windows, leaving the handle open would hold a file
+// lock and block Ginkgo's TempDir cleanup.
 func TempFile(t testingT, prefix, suffix string) (*os.File, string, error) {
 	name := TempFileName(t, prefix, suffix)
 	f, err := os.Create(name)
-	return f, name, err
+	if err != nil {
+		return nil, name, err
+	}
+	if cerr := f.Close(); cerr != nil {
+		return f, name, cerr
+	}
+	return f, name, nil
 }
 
 // ClearDB deletes all tables and data from the database

utils/files_test.go

@@ -192,6 +192,10 @@ var _ = Describe("FileExists", func() {
 			filePath := tempFile.Name()
 			Expect(utils.FileExists(filePath)).To(BeTrue())
 
+			// Close the file before removing it. On Windows, an open handle
+			// holds a file lock and os.Remove fails; closing first makes the
+			// test cross-platform.
+			Expect(tempFile.Close()).To(Succeed())
 			err := os.Remove(filePath)
 			Expect(err).NotTo(HaveOccurred())
 			tempFile = nil // Prevent cleanup attempt