429 lines
17 KiB
Python
429 lines
17 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""文档与 pytest 配置守护：防止模板标准退化。"""
|
|
from __future__ import annotations
|
|
|
|
import configparser
|
|
import os
|
|
import re
|
|
import unittest
|
|
|
|
from _support import get_skill_root
|
|
|
|
|
|
FORBIDDEN_README_DESCRIPTION_TERMS_EN = (
|
|
"cli",
|
|
"schema",
|
|
"references",
|
|
"development",
|
|
"playwright",
|
|
"python",
|
|
"dom",
|
|
"rpa",
|
|
)
|
|
|
|
FORBIDDEN_README_DESCRIPTION_TERMS_ZH = (
|
|
"Agent 参考索引",
|
|
"契约",
|
|
"数据结构",
|
|
"开发规范",
|
|
)
|
|
|
|
|
|
def _description_has_forbidden_term(description: str) -> str | None:
|
|
lowered = description.lower()
|
|
for term in FORBIDDEN_README_DESCRIPTION_TERMS_EN:
|
|
if term in lowered:
|
|
return term
|
|
for term in FORBIDDEN_README_DESCRIPTION_TERMS_ZH:
|
|
if term in description:
|
|
return term
|
|
return None
|
|
|
|
|
|
def _extract_workflow_uses_line(text: str) -> str | None:
|
|
for line in text.splitlines():
|
|
stripped = line.strip()
|
|
if stripped.startswith("uses:"):
|
|
return stripped
|
|
return None
|
|
|
|
|
|
class TestDocsStandards(unittest.TestCase):
|
|
def _read(self, rel_path: str) -> str:
|
|
path = os.path.join(get_skill_root(), rel_path)
|
|
with open(path, encoding="utf-8") as f:
|
|
return f.read()
|
|
|
|
def _parse_frontmatter(self, text: str) -> str:
|
|
parts = text.split("---", 2)
|
|
if len(parts) < 2:
|
|
return ""
|
|
return parts[1]
|
|
|
|
def test_root_readme_has_yaml_frontmatter(self) -> None:
|
|
text = self._read("README.md")
|
|
self.assertTrue(text.startswith("---"), "README.md must start with YAML frontmatter")
|
|
parts = text.split("---", 2)
|
|
self.assertGreaterEqual(len(parts), 3, "README.md frontmatter must be closed")
|
|
|
|
def test_root_readme_frontmatter_has_description(self) -> None:
|
|
frontmatter = self._parse_frontmatter(self._read("README.md"))
|
|
self.assertIn("description:", frontmatter, "README.md frontmatter must include description")
|
|
|
|
def test_root_readme_description_avoids_technical_index_terms(self) -> None:
|
|
frontmatter = self._parse_frontmatter(self._read("README.md"))
|
|
match = re.search(r"description:\s*(.+)", frontmatter)
|
|
self.assertIsNotNone(match, "README.md description field not found")
|
|
description = match.group(1).strip().strip("\"'")
|
|
forbidden = _description_has_forbidden_term(description)
|
|
self.assertIsNone(
|
|
forbidden,
|
|
msg=f"README.md description must not contain technical index term {forbidden!r}",
|
|
)
|
|
|
|
def test_description_forbidden_terms_are_case_insensitive_for_english(self) -> None:
|
|
fail_cases = (
|
|
"CLI 契约说明",
|
|
"cli 工具入口",
|
|
"SCHEMA 定义",
|
|
"Schema 映射",
|
|
"schema 字段",
|
|
"Playwright 自动化",
|
|
"python 脚本",
|
|
"RPA 流程",
|
|
)
|
|
pass_cases = (
|
|
"用用户能理解的方式说明这个技能能做什么、适合什么场景，以及如何开始使用。",
|
|
"帮你自动整理订单并生成处理报告",
|
|
"适合每天需要重复核对的业务场景",
|
|
)
|
|
for description in fail_cases:
|
|
with self.subTest(description=description):
|
|
self.assertIsNotNone(
|
|
_description_has_forbidden_term(description),
|
|
msg=f"expected forbidden term in {description!r}",
|
|
)
|
|
for description in pass_cases:
|
|
with self.subTest(description=description):
|
|
self.assertIsNone(
|
|
_description_has_forbidden_term(description),
|
|
msg=f"expected no forbidden term in {description!r}",
|
|
)
|
|
|
|
def test_references_readme_has_no_yaml_frontmatter(self) -> None:
|
|
text = self._read("references/README.md")
|
|
self.assertFalse(
|
|
text.lstrip().startswith("---"),
|
|
"references/README.md must not contain YAML frontmatter",
|
|
)
|
|
|
|
def test_references_readme_has_no_description_field(self) -> None:
|
|
text = self._read("references/README.md")
|
|
self.assertNotRegex(
|
|
text,
|
|
r"(?m)^description\s*:",
|
|
msg="references/README.md must not contain description field",
|
|
)
|
|
|
|
def test_skill_md_requires_read_readme_first_rule(self) -> None:
|
|
text = self._read("SKILL.md")
|
|
self.assertIn("README.md", text)
|
|
self.assertTrue(
|
|
"优先读取" in text or "优先读" in text,
|
|
msg="SKILL.md must require reading README.md first for user-facing questions",
|
|
)
|
|
|
|
def test_skill_md_states_readme_is_for_users(self) -> None:
|
|
text = self._read("SKILL.md")
|
|
self.assertIn("README.md", text)
|
|
self.assertTrue(
|
|
any(marker in text for marker in ("面向用户", "普通用户", "用户市场")),
|
|
msg="SKILL.md must state README.md is user-facing documentation",
|
|
)
|
|
|
|
def test_naming_md_exists_and_covers_standards(self) -> None:
|
|
text = self._read("development/NAMING.md")
|
|
self.assertIn("verb-noun-platform", text)
|
|
self.assertIn("48", text)
|
|
self.assertTrue("LEGACY" in text or "历史" in text)
|
|
self.assertTrue("verbs.txt" in text or "动词白名单" in text)
|
|
self.assertTrue("platforms.txt" in text or "平台白名单" in text)
|
|
self.assertTrue("仅适用于新创建" in text or "新技能" in text)
|
|
|
|
def test_release_workflow_uses_main_channel(self) -> None:
|
|
text = self._read(".github/workflows/release_skill.yaml")
|
|
uses_line = _extract_workflow_uses_line(text)
|
|
self.assertIsNotNone(uses_line, "release_skill.yaml must contain a uses: line")
|
|
self.assertIn(
|
|
"client-jiangchang/jiangchang-platform-kit/.github/workflows/reusable-release-skill.yaml",
|
|
uses_line,
|
|
)
|
|
self.assertRegex(
|
|
uses_line,
|
|
r"reusable-release-skill\.yaml@main\b",
|
|
msg="workflow uses must reference reusable-release-skill.yaml@main",
|
|
)
|
|
|
|
def test_rpa_md_covers_video_and_playwright_standards(self) -> None:
|
|
text = self._read("development/RPA.md")
|
|
self.assertIn("title", text)
|
|
self.assertIn("closing_title", text)
|
|
self.assertIn("中文", text)
|
|
self.assertIn("--no-sandbox", text)
|
|
self.assertIn("--disable-blink-features=AutomationControlled", text)
|
|
self.assertIn("RpaVideoSession", text)
|
|
self.assertIn("1.0.17", text)
|
|
|
|
def test_rpa_md_forbids_rpa_helpers_import(self) -> None:
|
|
text = self._read("development/RPA.md")
|
|
self.assertIn("rpa_helpers", text)
|
|
self.assertTrue(
|
|
"不要 import" in text or "不要" in text and "import" in text,
|
|
msg="RPA.md must document forbidding rpa_helpers import",
|
|
)
|
|
|
|
def test_rpa_md_covers_simulator_playwright_layering(self) -> None:
|
|
text = self._read("development/RPA.md")
|
|
self.assertTrue(
|
|
"simulator_playwright" in text
|
|
or ("薄 adapter" in text and "playwright.py" in text),
|
|
msg="RPA.md must describe thin adapter + *_playwright.py layering",
|
|
)
|
|
|
|
def test_rpa_md_covers_industry_simulator_portal(self) -> None:
|
|
text = self._read("development/RPA.md")
|
|
self.assertTrue(
|
|
any(marker in text for marker in ("jc2009", "行业仿真", "门户")),
|
|
msg="RPA.md must mention jc2009 / industry simulator / portal gate",
|
|
)
|
|
|
|
def test_simulator_example_readme_covers_async_and_account_manager(self) -> None:
|
|
text = self._read("examples/simulator_browser_rpa/README.md")
|
|
self.assertIn("async", text.lower())
|
|
self.assertTrue(
|
|
"account-manager" in text.lower() or "pick-web" in text or "pick_web_account" in text,
|
|
msg="simulator_browser_rpa README must mention async and account-manager",
|
|
)
|
|
|
|
def test_development_md_documents_scaffold_and_git_cleanup(self) -> None:
|
|
text = self._read("development/DEVELOPMENT.md")
|
|
self.assertTrue(
|
|
"scaffold_skill" in text or "scaffold_skill.ps1" in text,
|
|
msg="DEVELOPMENT.md must document scaffold_skill",
|
|
)
|
|
self.assertTrue(
|
|
("Remove-Item" in text and ".git" in text)
|
|
or ("删除" in text and ".git" in text),
|
|
msg="DEVELOPMENT.md must document deleting .git",
|
|
)
|
|
|
|
def test_naming_md_copy_flow_documents_scaffold_or_git_cleanup(self) -> None:
|
|
text = self._read("development/NAMING.md")
|
|
self.assertTrue(
|
|
"scaffold" in text.lower() or ("清理" in text and ".git" in text),
|
|
msg="NAMING.md §9 must mention scaffold or Git cleanup",
|
|
)
|
|
|
|
def test_scaffold_ps1_exists(self) -> None:
|
|
path = os.path.join(get_skill_root(), "tools", "scaffold_skill.ps1")
|
|
self.assertTrue(os.path.isfile(path), msg="tools/scaffold_skill.ps1 must exist")
|
|
|
|
def test_guarded_docs_do_not_reference_amazon_implementation(self) -> None:
|
|
forbidden = (
|
|
"download-settlement-report-amazon",
|
|
"amazon_sim",
|
|
"#amz-email",
|
|
)
|
|
guarded_docs = (
|
|
"development/RPA.md",
|
|
"development/ADAPTER.md",
|
|
"development/DEVELOPMENT.md",
|
|
"development/CONFIG.md",
|
|
"development/TESTING.md",
|
|
"examples/README.md",
|
|
"examples/simulator_browser_rpa/README.md",
|
|
)
|
|
for rel in guarded_docs:
|
|
text = self._read(rel)
|
|
for fragment in forbidden:
|
|
self.assertNotIn(
|
|
fragment,
|
|
text,
|
|
msg=f"{rel} must not reference Amazon implementation {fragment!r}",
|
|
)
|
|
|
|
def test_adapter_md_covers_four_tiers_and_config_get(self) -> None:
|
|
text = self._read("development/ADAPTER.md")
|
|
for marker in (
|
|
"mock",
|
|
"simulator_rpa",
|
|
"real_api",
|
|
"real_rpa",
|
|
"config.get",
|
|
"sibling_bridge",
|
|
):
|
|
self.assertIn(marker, text, msg=f"ADAPTER.md missing {marker!r}")
|
|
self.assertNotIn("ALLOW_REAL_API", text)
|
|
self.assertNotIn("ALLOW_WRITE_ACTIONS", text)
|
|
|
|
def test_cli_md_mentions_shared_python_runtime(self) -> None:
|
|
text = self._read("references/CLI.md")
|
|
self.assertIn("python-runtime", text)
|
|
self.assertIn("uv run python", text)
|
|
|
|
def test_testing_md_mentions_pytest_txt_collection_guard(self) -> None:
|
|
text = self._read("development/TESTING.md")
|
|
self.assertIn(".txt", text)
|
|
self.assertIn("pytest.ini", text)
|
|
|
|
def test_docs_do_not_claim_1_0_11_as_current_standard(self) -> None:
|
|
for rel in (
|
|
"SKILL.md",
|
|
"development/RUNTIME.md",
|
|
"development/RPA.md",
|
|
"development/CONFIG.md",
|
|
"development/TESTING.md",
|
|
):
|
|
text = self._read(rel)
|
|
self.assertNotIn(
|
|
">=1.0.11",
|
|
text.replace(" ", ""),
|
|
msg=f"{rel} still claims 1.0.11 as current minimum",
|
|
)
|
|
|
|
def test_scripts_has_no_legacy_example_artifacts(self) -> None:
|
|
scripts_dir = os.path.join(get_skill_root(), "scripts")
|
|
service_dir = os.path.join(scripts_dir, "service")
|
|
self.assertFalse(
|
|
os.path.isfile(os.path.join(service_dir, "example_browser_rpa.py")),
|
|
"scripts/service/example_browser_rpa.py must not exist",
|
|
)
|
|
self.assertFalse(
|
|
os.path.isdir(os.path.join(service_dir, "example_adapter")),
|
|
"scripts/service/example_adapter/ must not exist",
|
|
)
|
|
|
|
def test_gitignore_covers_python_runtime_artifacts(self) -> None:
|
|
text = self._read(".gitignore")
|
|
self.assertIn("__pycache__", text)
|
|
self.assertIn(".pytest_cache", text)
|
|
self.assertTrue(
|
|
"py[cod]" in text or ".pyc" in text,
|
|
msg=".gitignore must ignore Python bytecode (e.g. *.py[cod])",
|
|
)
|
|
|
|
def test_scripts_runtime_artifacts_not_tracked_by_git(self) -> None:
|
|
import subprocess
|
|
|
|
try:
|
|
out = subprocess.run(
|
|
["git", "ls-files", "scripts"],
|
|
cwd=get_skill_root(),
|
|
capture_output=True,
|
|
text=True,
|
|
check=True,
|
|
)
|
|
except (FileNotFoundError, subprocess.CalledProcessError):
|
|
self.skipTest("git not available or not a git repo")
|
|
tracked = out.stdout.splitlines()
|
|
for rel in tracked:
|
|
lowered = rel.replace("\\", "/").lower()
|
|
self.assertNotIn("__pycache__", lowered, msg=f"tracked cache path: {rel}")
|
|
self.assertNotIn(".pytest_cache", lowered, msg=f"tracked cache path: {rel}")
|
|
self.assertFalse(lowered.endswith(".pyc"), msg=f"tracked .pyc file: {rel}")
|
|
|
|
def test_examples_top_level_modes_present(self) -> None:
|
|
examples_dir = os.path.join(get_skill_root(), "examples")
|
|
for mode in ("real_api", "real_browser_rpa", "simulator_api", "simulator_browser_rpa"):
|
|
self.assertTrue(
|
|
os.path.isdir(os.path.join(examples_dir, mode)),
|
|
msg=f"examples/{mode}/ must exist",
|
|
)
|
|
|
|
def test_examples_are_not_full_skill_repos(self) -> None:
|
|
examples_dir = os.path.join(get_skill_root(), "examples")
|
|
for mode in os.listdir(examples_dir):
|
|
mode_path = os.path.join(examples_dir, mode)
|
|
if not os.path.isdir(mode_path):
|
|
continue
|
|
self.assertFalse(
|
|
os.path.isfile(os.path.join(mode_path, "SKILL.md")),
|
|
msg=f"examples/{mode}/SKILL.md must not exist",
|
|
)
|
|
self.assertFalse(
|
|
os.path.isdir(os.path.join(mode_path, "references")),
|
|
msg=f"examples/{mode}/references/ must not exist",
|
|
)
|
|
self.assertFalse(
|
|
os.path.isdir(os.path.join(mode_path, "development")),
|
|
msg=f"examples/{mode}/development/ must not exist",
|
|
)
|
|
self.assertFalse(
|
|
os.path.isdir(os.path.join(mode_path, ".github")),
|
|
msg=f"examples/{mode}/.github/ must not exist",
|
|
)
|
|
|
|
def test_examples_readme_states_copy_boundary(self) -> None:
|
|
text = self._read("examples/README.md")
|
|
self.assertIn("不是完整 skill 仓库", text)
|
|
self.assertIn("核心实现案例", text)
|
|
self.assertTrue(
|
|
"不要整包照搬" in text or "不要整包" in text,
|
|
msg="examples/README.md must warn against copying whole example tree",
|
|
)
|
|
self.assertTrue(
|
|
"scripts" in text and ("复制" in text or "copy map" in text.lower()),
|
|
msg="examples/README.md must describe copying into scripts/",
|
|
)
|
|
|
|
def test_placeholder_api_examples_are_not_implementation_references(self) -> None:
|
|
for rel in ("examples/real_api/README.md", "examples/simulator_api/README.md"):
|
|
text = self._read(rel)
|
|
self.assertTrue(
|
|
"占位" in text or "规划" in text,
|
|
msg=f"{rel} must state placeholder/planned status",
|
|
)
|
|
self.assertTrue(
|
|
"尚未沉淀" in text or "不可作为实现参考" in text or "不可" in text,
|
|
msg=f"{rel} must warn not to use as implementation reference",
|
|
)
|
|
|
|
def test_docs_do_not_reference_scripts_legacy_examples(self) -> None:
|
|
forbidden_fragments = (
|
|
"scripts/service/example_browser_rpa",
|
|
"scripts/service/example_adapter",
|
|
"example_browser_rpa.py",
|
|
"example_adapter/",
|
|
)
|
|
doc_paths = []
|
|
for root, _dirs, files in os.walk(get_skill_root()):
|
|
rel_root = os.path.relpath(root, get_skill_root())
|
|
if rel_root.startswith(".git"):
|
|
continue
|
|
for name in files:
|
|
if name.endswith(".md"):
|
|
doc_paths.append(os.path.join(rel_root, name).replace("\\", "/"))
|
|
for rel in doc_paths:
|
|
text = self._read(rel)
|
|
for fragment in forbidden_fragments:
|
|
self.assertNotIn(
|
|
fragment,
|
|
text,
|
|
msg=f"{rel} must not reference legacy scripts example path {fragment!r}",
|
|
)
|
|
|
|
|
|
class TestPytestIniCollection(unittest.TestCase):
|
|
def test_pytest_ini_exists_and_limits_python_files(self) -> None:
|
|
ini_path = os.path.join(get_skill_root(), "pytest.ini")
|
|
self.assertTrue(os.path.isfile(ini_path), "pytest.ini must exist at repo root")
|
|
parser = configparser.ConfigParser()
|
|
parser.read(ini_path, encoding="utf-8")
|
|
python_files = parser.get("pytest", "python_files", fallback="")
|
|
self.assertIn("test_*.py", python_files)
|
|
self.assertIn("*_test.py", python_files)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
unittest.main()
|