kahraman-storybook-testing 是一项面向 Storybook 交互测试与可移植故事（portable stories）的推荐编写风格，适用于编写、扩展、审查或调试此类测试。它强调把 Storybook 故事当作可执行的用户旅程：故事提供可复现的应用状态，测试则记录用户在该状态下能感知到什么、能做什么；倾向于少量清晰场景，而不是用一个测试分支覆盖多个互不相关的状态。该风格是推荐实践，并非要求所有项目采用同一套 Storybook 技术栈，其核心是 actor（以用户视角操作页面）和可访问性优先的定位器（locator）策略。
使用前提：该技能建立在已配置好的 Storybook 项目之上，不负责初始化 Storybook，也不决定故事架构。修改交互测试前，需确认已存在 .storybook/main.* 与 .storybook/preview.*（或等效配置目录，含浏览器测试执行能力）、至少一个可用的 *.stories.ts 或 *.stories.tsx 文件（确立仓库的 CSF 或 preview-factory 格式），以及已暴露给故事并用其 Storybook 上下文初始化的 kahraman。MSW 状态建模、响应式变体、路由/深链故事、视觉断言等可选集成，只有在项目已具备对应前置条件时才应用；若缺失，应说明缺哪一项，并询问是补充该集成还是省略该可选变体，而不是擅自搭建一套有倾向性的技术栈。
使用方式上，建议先阅读项目约定：若存在 .storybook/README.md 先读它，再对照 .storybook/main.、preview.、package 脚本、功能附近的交互故事与 actor 辅助函数核实；并复用项目既有的 Storybook API（preview.meta(...).story(...) 或 CSF Meta / StoryObj），不要混用模式。建议在配置旁维护项目本地的 .storybook/README.md，作为编写与审查交互故事的自治指南：保留该推荐风格的精髓，用经验证的项目事实替换通用设置说明，记录故事格式与 actor 初始化钩子、故事/夹具/页面 actor/mock 处理器/底层测试辅助的归属、可访问定位器与作用域/稳定/重试约定、包管理脚本、标签含义与 CI 约定、视口名称与断点、MSW 处理器注册与覆盖约定、路由参数、截图命名与评审策略等。只记录当前仓库代码或脚本支持的约定，使用精确的本地路径与命令。
主要能力与规范包括：优先使用 actor 的意图级方法（see、dontSee、click、fill、seeInField、seeChecked、seeDisabled、seeAttribute、seeNumberOfElements、clear、selectOption、press、grabTextFrom、grabTextFromAll、tryTo、retryTo、hopeThat 等）；用 I.extend(...) 构建可复用的页面级词汇，方法名使用用户/领域语言，避免不透明的完整流程助手；像用户一样寻址 UI，使用 role、heading、button、link、text 配合可访问名称，而非 CSS 选择器、test ID、DOM 遍历或文本内容匹配；用 locator 修饰符（wait、maybe、all、within、options）控制查询；将断言限定在被测区域内，避免全局导航与提示造成误匹配；基于可观察的生命周期信号（如等待加载状态退出）而非任意 sleep 来稳定测试；用 tryTo 仅处理真正可选的行为，用 hopeThat 汇总独立断言并以 I.hopeThat.noErrors() 收尾。可选方面：当项目已具备 MSW 前置条件时，可为成功、失败、持续加载分别建立故事，复用应用处理器并只覆盖受影响的 handler；可选开启 kahraman/preview 诊断注解，在完整应用挂载时精简 Testing Library 元素未找到的错误输出（通过 captureRoleListing、maxLength、getElementError 参数调节），或用 configureDiagnostics() 命令式安装；响应式变体仅在功能在该尺寸下确有值得验证的行为或布局时添加。
适用场景为已配置 Storybook 且使用 kahraman 的项目中，编写或审查集成交互测试、调试失败故事、维护本地测试指南。限制：不引导搭建 Storybook 技术栈；不编造预览导入、meta.story() API、别名、测试回调、处理器接线、视口名称或路由参数；截图失败、VITE_TEST_STEPS 等属于消费方运行器设置，需沿用项目约定而非默认开启。官方参考应用包括 apphane-dev/karkas/.storybook 与 reatom/reatom/packages/admin/.storybook，仅作参考而非模板。