From 47b9633a86e983b08b07a0673df670d5231c7ced Mon Sep 17 00:00:00 2001
From: jxxghp <jxxghp@gmail.com>
Date: Mon, 3 Aug 2026 22:17:56 +0800
Subject: [PATCH] Document test helpers and component stubs

---
 src/components/cards/__tests__/DownloadingCard.spec.ts |  1 +
 src/components/cards/__tests__/MediaCard.spec.ts       | 10 ++++++++++
 2 files changed, 11 insertions(+)

diff --git a/src/components/cards/__tests__/DownloadingCard.spec.ts b/src/components/cards/__tests__/DownloadingCard.spec.ts
index 181a1159..5f270e18 100644
--- a/src/components/cards/__tests__/DownloadingCard.spec.ts
+++ b/src/components/cards/__tests__/DownloadingCard.spec.ts
@@ -7,6 +7,7 @@ import { server } from '@tests/support/msw/server'
 import { defineComponent, h } from 'vue'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
+/** 扩展卡片会消费但公共下载类型尚未声明的站点字段。 */
 interface DownloadingCardInfo extends DownloadingInfo {
   site_name?: string
   trackers?: string[]
diff --git a/src/components/cards/__tests__/MediaCard.spec.ts b/src/components/cards/__tests__/MediaCard.spec.ts
index 68b83ce9..9ccc64eb 100644
--- a/src/components/cards/__tests__/MediaCard.spec.ts
+++ b/src/components/cards/__tests__/MediaCard.spec.ts
@@ -83,11 +83,13 @@ class IntersectionObserverMock implements IntersectionObserver {
   }
 }
 
+/** 渲染媒体卡片时可覆盖的用户权限状态。 */
 interface RenderCardOptions {
   permissions?: Record<string, boolean>
   superUser?: boolean
 }
 
+/** 使用指定媒体信息和用户权限渲染媒体卡片。 */
 async function renderCard(media: MediaInfo, options: RenderCardOptions = {}) {
   return renderWithProviders(MediaCard, {
     props: {
@@ -108,32 +110,38 @@ async function renderCard(media: MediaInfo, options: RenderCardOptions = {}) {
   })
 }
 
+/** 获取已渲染的媒体卡片根元素。 */
 function getCard(container: Element) {
   const card = container.querySelector<HTMLElement>('.media-card')
   expect(card).not.toBeNull()
   return card as HTMLElement
 }
 
+/** 获取负责桌面悬停和触摸交互的卡片区域。 */
 function getHoverArea(container: Element) {
   const area = container.querySelector<HTMLElement>('.media-card-hover-area')
   expect(area).not.toBeNull()
   return area as HTMLElement
 }
 
+/** 获取媒体卡片当前渲染的所有操作按钮。 */
 function getActionButtons(container: Element) {
   return [...container.querySelectorAll<HTMLButtonElement>('.media-card .v-card-text button')]
 }
 
+/** 获取媒体搜索操作按钮并确保其已渲染。 */
 function getSearchButton(container: Element) {
   const button = getActionButtons(container)[0]
   expect(button).toBeDefined()
   return button
 }
 
+/** 筛选用于触发媒体状态懒加载的观察器。 */
 function getStatusObservers() {
   return intersectionObservers.filter(observer => observer.thresholds.includes(0.1))
 }
 
+/** 安装站点列表及已选站点的搜索请求处理器。 */
 function installSearchHandlers(sites: Record<string, unknown>[], selected: number[]) {
   server.use(
     http.get(siteListUrl, () => HttpResponse.json(sites)),
@@ -529,6 +537,7 @@ describe('MediaCard', () => {
       name: 'VImg',
       emits: ['error', 'load'],
       props: { src: String },
+      /** 渲染可主动触发图片成功和失败事件的测试替身。 */
       setup(props, { emit, slots }) {
         return () =>
           h('div', { 'data-src': props.src }, [
@@ -567,6 +576,7 @@ describe('MediaCard', () => {
       name: 'VImg',
       emits: ['load'],
       props: { src: String },
+      /** 渲染可主动触发海报加载完成事件的测试替身。 */
       setup(_props, { emit, slots }) {
         return () =>
           h('div', [h('button', { 'aria-label': '图片加载成功', onClick: () => emit('load') }), slots.default?.()])