Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

22.6 KB
Raw Blame
"""
Tests for the v2 Checkpoint 2 content-quality scripts:
    scripts/content_quality.py
    scripts/content_humanize.py
    scripts/content_verify.py
    scripts/seo_updates.py
    data/google-updates.json

domain_history.py is covered by integration smoke (it hits the system
``whois`` binary) and is not unit-tested here to avoid flaking when
network or whois egress is unavailable.
"""

from __future__ import annotations

import json
import os
import subprocess
import sys
from datetime import date
from pathlib import Path
from urllib.parse import urlsplit

import pytest

_SCRIPTS = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts")
if _SCRIPTS not in sys.path:
    sys.path.insert(0, _SCRIPTS)

import content_humanize  # noqa: E402
import content_quality  # noqa: E402
import content_verify  # noqa: E402
import seo_updates  # noqa: E402

# ---------------------------------------------------------------------------
# content_quality
# ---------------------------------------------------------------------------


def test_content_quality_empty_input() -> None:
    result = content_quality.analyse("")
    assert result["flags"] == ["empty-input"]
    assert result["overall_quality"] == 0


def test_content_quality_filler_heavy_text_scores_low() -> None:
    text = (
        "In today's fast-paced world, when it comes to SEO, "
        "it's important to note that delving into the ever-evolving "
        "landscape requires us to leverage the power of cutting-edge "
        "tools. In essence, this guide will dive into the rich tapestry "
        "of optimization strategies. Needless to say, at the end of the "
        "day, the bottom line is that we need to revolutionize the way "
        "we approach search."
    )
    result = content_quality.analyse(text)
    assert result["overall_quality"] < 40, result
    assert "filler" in result["flags"]
    assert "ai-patterns" in result["flags"]
    assert result["filler_score"] >= 50
    assert result["ai_pattern_score"] >= 40


def test_longer_filler_phrase_is_not_scored_twice() -> None:
    """``let's dive in`` is a prefix of ``let's dive into``. One sentence
    must not count as both, which pushes filler_score from 25 to 50 and
    raises the filler flag.
    """
    text = "Let's dive into the details of this topic today. " * 40
    result = content_quality.analyse(text)
    assert result["matches"]["filler"] == ["let's dive into"]
    assert result["filler_score"] == 25
    assert "filler" not in result["flags"]

    shorter = "Let's dive in and review the details of this topic today. " * 40
    short_result = content_quality.analyse(shorter)
    assert short_result["matches"]["filler"] == ["let's dive in"]


def test_content_quality_rich_content_scores_high() -> None:
    # 300+ tokens with specific numbers, named entities, no filler.
    text = (
        "On 2025-08-21 Google extended AI Mode to 180 countries. "
        "The Hreflang spec has not changed since RFC 1034 was clarified "
        "in 1987 by Paul Mockapetris. Stanford's CRFM published a 312 "
        "page report measuring 47 vendor models on 18 evaluation tasks. "
        "John Mueller confirmed via Bluesky on 2025-04-12 that llms.txt "
        "is not consumed by any Google system. SE Ranking analysed "
        "300000 domains and found one llms.txt among the top 50 "
        "most-cited domains, putting the adoption rate at 0.1 percent. "
        "Robby Stein, Google VP of Search, demonstrated AI Mode "
        "executing 4 restaurant reservations across Resy and OpenTable "
        "in a single session. Forrester analysts updated their B2B "
        "Marketing Wave on 2026-02-04, downgrading 3 vendors that "
        "previously held Leader positions in the 2024 edition." * 2
    )
    result = content_quality.analyse(text)
    assert result["overall_quality"] >= 50, result
    assert "filler" not in result["flags"]
    assert result["information_density"] > 0.2


def test_content_quality_thin_content_flag() -> None:
    text = "Hello world. This is a short page."
    result = content_quality.analyse(text)
    assert "thin-content" in result["flags"]


@pytest.mark.parametrize(
    "phrase",
    [
        "delve into",
        "ever-evolving landscape",
        "tapestry of",
        "leverage the power of",
        "leveraging the power of",
        "unlock the potential",
        "in essence,",
    ],
)
def test_content_quality_detects_known_ai_patterns(phrase: str) -> None:
    # Wrap in enough other text that the score doesn't reject as thin.
    text = (phrase + " example sentence. ") * 30
    result = content_quality.analyse(text)
    assert result["ai_pattern_score"] > 0
    assert phrase.lower() in [m.lower() for m in result["matches"]["ai_patterns"]]

def test_content_quality_tokenises_korean() -> None:
    """Hangul is space-delimited, so a run of syllables is one token.

    Before CJK support the Latin-only tokeniser matched nothing in Korean
    text, so ``tokens`` was 0, ``information_density`` collapsed to 0.0 and
    every Korean page scored an identical 65 regardless of content.
    """
    text = (
        "한국천문연구원 공표 절기를 기준으로 계산하는 정통 사주팔자 풀이입니다. "
        "생년월일시를 한 번만 입력하면 천간과 지지, 오행, 대운까지 확인할 수 있습니다."
    )
    result = content_quality.analyse(text)
    assert result["tokens"] > 0, result
    assert result["unique_tokens"] > 0, result


def test_content_quality_tokenises_japanese_and_chinese() -> None:
    """Japanese and Chinese are unspaced: one kana or ideograph is one token."""
    for text in ("無料四柱推命で日柱と五行がわかります。", "免费四柱推命,一分钟了解日柱与五行。"):
        result = content_quality.analyse(text)
        assert result["tokens"] > 0, (text, result)


def test_content_quality_cjk_distinguishes_documents() -> None:
    """Different Korean documents must not collapse to one identical score."""
    short = "사주는 자기 이해의 한 관점입니다."
    long = (
        "사주팔자는 태어난 연월일시를 천간과 지지로 옮긴 여덟 글자입니다. "
        "절기를 기준으로 월주를 정하고, 진태양시로 시주를 보정합니다. "
        "오행의 균형과 십신의 배치를 함께 살펴 전체 흐름을 읽습니다. "
        "대운은 10년 단위로 바뀌고 세운은 해마다 달라집니다."
    )
    assert content_quality.analyse(long)["tokens"] > content_quality.analyse(short)["tokens"]


def test_content_quality_latin_scoring_unchanged_by_cjk_support() -> None:
    """Regression guard: adding CJK ranges must not shift Latin tokenisation."""
    text = (
        "Traditional Korean four pillars astrology calculated from the KASI "
        "published solar terms. Enter your birth date and time once to see the "
        "heavenly stems, earthly branches, five elements and major luck cycles."
    )
    result = content_quality.analyse(text)
    assert result["tokens"] == len(
        [w for w in __import__("re").findall(r"[A-Za-z][A-Za-z'\-]*", text)]
    ), result


def test_content_quality_english_output_keys_and_values_unchanged() -> None:
    """English-language output must be byte-for-byte the same shape as before
    the CJK coverage note: no ``coverage`` key, same keys, same values."""
    text = (
        "In today's fast-paced world, when it comes to SEO, "
        "it's important to note that delving into the ever-evolving "
        "landscape requires us to leverage the power of cutting-edge "
        "strategies to unlock the potential of organic traffic."
    ) * 5
    result = content_quality.analyse(text)
    assert set(result.keys()) == {
        "filler_score",
        "ai_pattern_score",
        "information_density",
        "repetition_score",
        "overall_quality",
        "flags",
        "matches",
        "tokens",
        "unique_tokens",
    }
    assert "coverage" not in result


def test_content_quality_cjk_output_carries_coverage_object() -> None:
    """A CJK score must be flagged as partial coverage, not silently compared
    to an English score as if every signal were computed the same way."""
    text = (
        "사주팔자는 태어난 연월일시를 천간과 지지로 옮긴 여덟 글자입니다. "
        "절기를 기준으로 월주를 정하고, 진태양시로 시주를 보정합니다. "
        "오행의 균형과 십신의 배치를 함께 살펴 전체 흐름을 읽습니다."
    )
    result = content_quality.analyse(text)
    assert result["coverage"] == {
        "script": "cjk",
        "entity_density": "not_computed",
        "phrase_lists": "english_only",
    }


def test_content_quality_cjk_human_output_notes_partial_coverage() -> None:
    """The CLI's human-readable summary must call out partial CJK coverage."""
    script = Path(__file__).resolve().parents[1] / "scripts" / "content_quality.py"
    text = "사주팔자는 태어난 연월일시를 천간과 지지로 옮긴 여덟 글자입니다. " * 5
    # CJK input and output must not go through the Windows locale codec.
    env = {**os.environ, "PYTHONIOENCODING": "utf-8"}
    result = subprocess.run(
        [sys.executable, str(script)],
        input=text, capture_output=True, encoding="utf-8", errors="replace", env=env,
    )
    assert result.returncode in (0, 1)
    assert "not directly comparable" in result.stdout


# ---------------------------------------------------------------------------
# content_humanize
# ---------------------------------------------------------------------------


def test_humanize_removes_canonical_ai_patterns() -> None:
    text = (
        "Let's dive into the ever-evolving landscape of SEO. "
        "When it comes to ranking, it's important to note that we should "
        "leverage the power of cutting-edge tools to unlock the potential "
        "of our content. In essence, this is a game-changer."
    )
    result = content_humanize.humanize(text)
    assert result["change_count"] >= 5
    cleaned_lower = result["cleaned"].lower()
    for forbidden in (
        "delve into",
        "ever-evolving",
        "leverage the power of",
        "cutting-edge",
        "unlock the potential",
        "in essence,",
        "game-changer",
    ):
        assert forbidden not in cleaned_lower, (
            f"{forbidden!r} should have been replaced; cleaned text: "
            f"{result['cleaned']!r}"
        )


def test_humanize_preserves_capitalization_at_sentence_start() -> None:
    text = "Delve into our guide."
    result = content_humanize.humanize(text)
    assert result["cleaned"].startswith("Explore"), result["cleaned"]


def test_humanize_idempotent_on_clean_text() -> None:
    text = (
        "Google released the December 2025 Core Update on 2025-12-11. "
        "The rollout took 18 days and showed a measurable eCommerce skew "
        "according to Amsive's analysis."
    )
    result = content_humanize.humanize(text)
    assert result["change_count"] == 0
    assert result["cleaned"] == text


def test_humanize_collapses_extra_spaces_from_deleted_phrases() -> None:
    text = "In essence, we ship features."
    result = content_humanize.humanize(text)
    # "In essence, " gets removed; result must not start with a space.
    assert not result["cleaned"].startswith(" ")
    assert "  " not in result["cleaned"]


# ---------------------------------------------------------------------------
# content_verify
# ---------------------------------------------------------------------------


def test_verify_extracts_basic_claim_kinds() -> None:
    text = (
        "47% of marketers report better results. "
        "The market reached $3.2 billion by 2025. "
        "Forrester said the trend will continue. "
        "The product is 3x faster than alternatives. "
        "In 2024, adoption doubled."
    )
    result = content_verify.verify(text)
    kinds = {c["kind"] for c in result["claims"]}
    assert {"statistic", "quantity", "authority", "temporal", "comparative"} <= kinds


def test_verify_flags_uncited_claims() -> None:
    text = "47% of marketers do X. 60% report success. 80% see growth."
    result = content_verify.verify(text)
    assert result["uncited_count"] == result["claim_count"]
    assert result["uncited_ratio"] == 1.0


def test_verify_accepts_markdown_link_as_citation() -> None:
    text = (
        "According to a recent study, 47% of marketers do X "
        "[Source](https://example.com/study)."
    )
    result = content_verify.verify(text)
    assert all(c["has_citation"] for c in result["claims"])


def test_verify_accepts_footnote_marker() -> None:
    text = "Adoption hit 60% in 2025 [^1]."
    result = content_verify.verify(text)
    assert all(c["has_citation"] for c in result["claims"])


def test_verify_empty_text_returns_zero_claims() -> None:
    result = content_verify.verify("")
    assert result["claim_count"] == 0
    assert result["uncited_ratio"] == 0.0


def test_verify_detects_a_bare_percentage_statistic() -> None:
    # A bare percentage not followed by "of ..." is the canonical unsourced
    # statistic this tool exists to flag. A trailing \b after "%" in the
    # pattern could never match (a percentage is followed by a space or
    # punctuation, both non-word), so these claims were silently missed.
    for text in ("The bounce rate hit 85%.", "Conversions rose by 30% overall.",
                 "Prices rose 3.5% this quarter."):
        result = content_verify.verify(text)
        assert result["claim_count"] == 1, text
        assert result["claims"][0]["kind"] == "statistic", text


def test_verify_bare_percentage_does_not_double_count_percent_of() -> None:
    # "47% of marketers" must still be one claim, not two (the longer
    # "% of ..." match wins over the bare-"%" match on the same span).
    result = content_verify.verify("47% of marketers report gains.")
    assert result["claim_count"] == 1


def test_verify_standalone_per_followed_by_a_common_word_is_not_a_citation() -> None:
    # The citation pattern requires "per" + a Proper Noun, but re.IGNORECASE
    # made the [A-Z] anchor match lowercase too, so "per week" and "per page"
    # were counted as citations. A claim near such a phrase was then wrongly
    # reported as cited.
    result = content_verify.verify("Fully 80% of users churned, measured per week.")
    assert result["claim_count"] == 1
    claim = result["claims"][0]
    assert claim["has_citation"] is False
    assert result["uncited_count"] == 1


def test_verify_per_followed_by_a_proper_noun_is_still_a_citation() -> None:
    result = content_verify.verify("Fully 80% of users churned, per Gartner.")
    assert result["claims"][0]["has_citation"] is True


@pytest.mark.parametrize(
    "attribution",
    [
        "according to a Stanford study",
        "according to the CDC",
        "Source: https://example.org/x",
        "(source: internal survey)",
        "cited by the World Bank",
        "via: nielsen.com",
    ],
)
def test_verify_attribution_prefixes_count_without_a_capitalised_next_word(
    attribution: str,
) -> None:
    # Only "per" needs a capitalised next word. The other attribution forms
    # are citations whatever follows them: an article, a URL, a lowercase
    # domain or a bracketed lowercase "source:".
    result = content_verify.verify(f"Fully 80% of users churned, {attribution}.")
    assert result["claims"][0]["kind"] == "statistic"
    assert result["claims"][0]["has_citation"] is True, attribution


def test_verify_per_is_case_insensitive_but_its_proper_noun_is_not() -> None:
    cited = content_verify.verify("Fully 80% of users churned. Per Gartner.")
    assert cited["claims"][0]["has_citation"] is True
    uncited = content_verify.verify("Fully 80% of users churned. Per week.")
    assert uncited["claims"][0]["has_citation"] is False


# ---------------------------------------------------------------------------
# seo_updates
# ---------------------------------------------------------------------------


def test_seo_updates_data_file_is_valid_json() -> None:
    data_path = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
    assert data_path.is_file()
    with data_path.open() as fh:
        data = json.load(fh)
    assert "updates" in data
    assert "source_of_truth" in data
    assert data["source_of_truth"].startswith("https://status.search.google.com/")


def test_seo_updates_every_entry_has_google_owned_source() -> None:
    """Policy: every entry must cite a Google-owned URL. Third-party-only
    claims belong in unverified[]."""
    data_path = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
    with data_path.open() as fh:
        data = json.load(fh)
    google_hosts = {
        "developers.google.com",
        "blog.google",
        "status.search.google.com",
        "web.dev",
        "developer.chrome.com",
        "static.googleusercontent.com",  # full Search Quality Rater Guidelines PDF
        "services.google.com",
        "support.google.com",
    }
    for entry in data["updates"]:
        url = entry.get("source", "")
        parsed = urlsplit(url)
        assert parsed.scheme == "https"
        assert parsed.hostname in google_hosts, (
            f"{entry['name']!r} cites non-Google URL: {url}. "
            "Move third-party-only entries to unverified[]."
        )
        assert parsed.username is None and parsed.password is None


def test_seo_updates_schema_and_order_are_enforced() -> None:
    data_path = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
    with data_path.open(encoding="utf-8") as fh:
        data = json.load(fh)

    allowed_kinds = {
        "core",
        "spam",
        "core+spam",
        "policy",
        "qrg",
        "product",
        "schema",
        "cwv",
        "discover",
        "documentation",
    }
    updates = data["updates"]
    dates = [entry["date"] for entry in updates]
    names = [entry["name"] for entry in updates]

    assert dates == sorted(dates), "updates[] must be chronological"
    assert len(names) == len(set(names)), "update names must be unique"
    assert set(seo_updates.KNOWN_KINDS) == allowed_kinds, "CLI --kind choices drifted from the schema"
    assert all(entry["kind"] in allowed_kinds for entry in updates)
    assert all(entry.get("notes", "").strip() for entry in updates)
    assert all(date.fromisoformat(value) for value in dates)

    verified = date.fromisoformat(data["last_verified"])
    assert verified >= date.fromisoformat(dates[-1])
    assert verified <= date.today()


def test_seo_updates_primary_ledger_does_not_embed_third_party_sources() -> None:
    data_path = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
    with data_path.open(encoding="utf-8") as fh:
        data = json.load(fh)

    for entry in data["updates"]:
        assert "third_party_sources" not in entry
        assert "unconfirmed" not in entry["notes"].lower()
        assert "reported" not in entry["notes"].lower()


def test_seo_updates_unverified_entries_call_out_status() -> None:
    """Unverified entries must include a primary_source_check pointer."""
    data_path = Path(__file__).resolve().parents[1] / "data" / "google-updates.json"
    with data_path.open() as fh:
        data = json.load(fh)
    for entry in data.get("unverified", []):
        assert "primary_source_check" in entry
        assert "status" in entry
        assert entry["primary_source_check"].startswith(
            "https://status.search.google.com/"
        )


def test_seo_updates_filter_by_kind() -> None:
    data = seo_updates._load()
    cores = seo_updates._filter(data["updates"], kinds={"core"})
    assert all(u["kind"] in {"core", "core+spam"} for u in cores)
    assert any(u["kind"] == "core+spam" for u in cores)
    assert any("December 2025 Core Update" in u["name"] for u in cores)


def test_seo_updates_spam_filter_includes_combined_rollouts() -> None:
    """`--kind spam` used to skip the combined March 2024 core+spam rollout."""
    data = seo_updates._load()
    spam = seo_updates._filter(data["updates"], kinds={"spam"})
    assert all(u["kind"] in {"spam", "core+spam"} for u in spam)
    assert any(u["kind"] == "core+spam" for u in spam)
    policy = seo_updates._filter(data["updates"], kinds={"policy"})
    assert all(u["kind"] == "policy" for u in policy)


def test_seo_updates_filter_by_year() -> None:
    data = seo_updates._load()
    since_2025 = seo_updates._filter(data["updates"], since="2025")
    assert all(u["date"] >= "2025-01-01" for u in since_2025)


def test_seo_updates_since_accepts_a_non_zero_padded_month() -> None:
    # "2025-9" is 6 chars, so the old length-based dispatch fell through to
    # date.fromisoformat("2025-9") and raised ValueError. A non-padded month
    # is unambiguous September and must filter the same as "2025-09".
    data = seo_updates._load()
    padded = seo_updates._filter(data["updates"], since="2025-09")
    unpadded = seo_updates._filter(data["updates"], since="2025-9")
    assert [u["date"] for u in unpadded] == [u["date"] for u in padded]


def test_seo_updates_parse_since_rejects_garbage_cleanly() -> None:
    # An out-of-range month (length 7, so it used to reach date(2025, 13, 1)
    # and crash) and non-date text both raise a clear ValueError.
    for bad in ("2025-13", "garbage", "2025-02-30"):
        with pytest.raises(ValueError):
            seo_updates._parse_since(bad)


def test_seo_updates_cli_reports_a_bad_since_without_a_traceback() -> None:
    script = Path(__file__).resolve().parents[1] / "scripts" / "seo_updates.py"
    result = subprocess.run(
        [sys.executable, str(script), "--since", "2025-13", "--json"],
        capture_output=True, text=True,
    )
    assert result.returncode == 2
    assert "Traceback" not in result.stderr
    assert "invalid --since" in result.stderr


def test_seo_updates_cli_accepts_every_known_kind() -> None:
    """`--kind documentation` used to be rejected by argparse while the ledger used it."""
    script = Path(__file__).resolve().parents[1] / "scripts" / "seo_updates.py"
    for kind in seo_updates.KNOWN_KINDS:
        result = subprocess.run(
            [sys.executable, str(script), "--kind", kind, "--json", "--limit", "1"],
            capture_output=True, text=True,
        )
        assert result.returncode == 0, f"--kind {kind} failed: {result.stderr}"
        json.loads(result.stdout)


def test_seo_updates_freshness_flags_a_stale_ledger() -> None:
    from datetime import date

    fresh = seo_updates.freshness("2026-09-10", today=date(2026, 9, 23))
    assert fresh == {"age_days": 13, "stale": False, "warning": None}
    stale = seo_updates.freshness("2026-07-01", today=date(2026, 9, 23))
    assert stale["stale"] and "status.search.google.com" in stale["warning"]
    assert seo_updates.freshness("not-a-date")["stale"] is True