Skip to content

Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.

10.7 KB
Raw Blame
"""Contract tests for the primary-source Google updates ledger."""

from __future__ import annotations

import importlib.util
import json
import sys
from datetime import date
from pathlib import Path
from urllib.parse import urlparse


REPO_ROOT = Path(__file__).resolve().parents[1]
LEDGER_PATH = REPO_ROOT / "data" / "google-updates.json"
GOOGLE_SKILL_PATH = REPO_ROOT / "skills" / "blog-google" / "SKILL.md"
GOOGLE_CURRENTNESS_PATH = (
    REPO_ROOT / "skills" / "blog-google" / "references" / "search-currentness.md"
)
SCHEMA_SKILL_PATH = REPO_ROOT / "skills" / "blog-schema" / "SKILL.md"
SCHEMA_REFERENCE_PATH = REPO_ROOT / "skills" / "blog" / "references" / "schema-stack.md"
CRAWLER_REFERENCE_PATH = (
    REPO_ROOT / "skills" / "blog" / "references" / "ai-crawler-guide.md"
)
BRAIN_LEDGER_PATH = REPO_ROOT / "brain" / "data" / "google-updates.json"
LANDSCAPE_PATH = (
    REPO_ROOT / "skills" / "blog" / "references" / "google-landscape-2026.md"
)
CURRENTNESS_SCRIPT_PATH = REPO_ROOT / "scripts" / "check_google_currentness.py"
CURRENTNESS_WORKFLOW_PATH = (
    REPO_ROOT / ".github" / "workflows" / "google-currentness.yml"
)


def _load_ledger() -> dict:
    return json.loads(LEDGER_PATH.read_text(encoding="utf-8"))


def _normalized(text: str) -> str:
    return " ".join(text.split())


def _load_currentness_module():
    spec = importlib.util.spec_from_file_location(
        "google_currentness_test", CURRENTNESS_SCRIPT_PATH
    )
    assert spec and spec.loader
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module


def test_google_updates_ledger_shape_and_currentness() -> None:
    ledger = _load_ledger()

    assert ledger["schema_version"] == 2
    assert date.fromisoformat(ledger["last_verified"]) >= date(2026, 8, 25)
    assert isinstance(ledger["verified"], list) and ledger["verified"]
    assert isinstance(ledger["unverified"], list)
    assert "must never change scoring" in ledger["policy"]
    assert "Event timing never proves site impact" in ledger["policy"]
    assert "Source conflicts remain explicit" in ledger["policy"]

    watches = {item["id"]: item for item in ledger["source_watch"]}
    assert watches["search-status"]["review_mode"] == "automated"
    assert watches["search-docs-updates"]["review_mode"] == "automated"
    assert watches["search-console-anomalies"]["review_mode"] == "manual"
    assert watches["google-ads-release-notes"]["review_mode"] == "manual"
    assert watches["google-ads-client-support"]["review_mode"] == "manual"


def test_verified_entries_use_unique_ids_and_google_owned_sources() -> None:
    ledger = _load_ledger()
    entries = ledger["verified"]
    ids = [entry["id"] for entry in entries]

    assert len(ids) == len(set(ids))
    for entry in entries:
        required = {
            "id",
            "event_date",
            "title",
            "source_url",
            "category",
            "applicability",
            "affected_components",
            "summary",
        }
        assert required <= set(entry)
        assert set(entry) <= required | {
            "additional_source_urls",
            "evidence_status",
        }
        date.fromisoformat(entry["event_date"])
        assert entry["affected_components"]
        source_urls = [entry["source_url"], *entry.get("additional_source_urls", [])]
        for source_url in source_urls:
            host = urlparse(source_url).hostname
            assert host in {
                "blog.google",
                "developers.google.com",
                "status.search.google.com",
                "support.google.com",
            }
        assert entry.get("evidence_status", "confirmed") in {
            "confirmed",
            "confirmed-data-anomaly",
            "confirmed-event-pending-impact",
            "confirmed-with-source-conflict",
        }


def test_ledger_covers_current_search_contracts() -> None:
    ledger_text = LEDGER_PATH.read_text(encoding="utf-8")

    for contract in (
        "FAQ rich results are no longer shown",
        "up to two weeks",
        "Instagram, TikTok, X, and YouTube",
        "no dedicated API",
        "not ranking factors",
        "first 2MB",
        "Back-button hijacking",
        "September 2026 spam update",
        "logging errors",
        "fake reviews",
        "Google Ads API v25.2",
    ):
        assert contract in ledger_text


def test_platform_availability_conflict_keeps_both_google_sources() -> None:
    ledger = _load_ledger()
    entry = next(
        item
        for item in ledger["verified"]
        if item["id"] == "search-console-platform-properties-2026-07-29"
    )

    assert entry["evidence_status"] == "confirmed-with-source-conflict"
    assert "globally available" in entry["summary"]
    assert "still says gradual rollout" in entry["summary"]
    assert entry["additional_source_urls"] == [
        "https://support.google.com/webmasters/answer/17148418?hl=en-GB"
    ]


def test_brain_ledger_is_an_exact_projection_of_the_canonical_ledger() -> None:
    assert BRAIN_LEDGER_PATH.read_bytes() == LEDGER_PATH.read_bytes()


def test_currentness_evaluator_distinguishes_current_and_refresh_required() -> None:
    module = _load_currentness_module()
    # Exercise evaluator behavior against a frozen review date. The canonical
    # ledger advances independently as new primary-source evidence is reviewed.
    ledger = _load_ledger()
    ledger["last_verified"] = "2026-08-25"

    current = module.evaluate(
        ledger,
        as_of=date(2026, 9, 24),
        max_age_days=31,
        source_dates={
            "search-docs-updates": date(2026, 8, 20),
            "search-status": date(2026, 8, 18),
        },
    )
    assert current["status"] == "current"

    newer_source = module.evaluate(
        ledger,
        as_of=date(2026, 8, 26),
        max_age_days=31,
        source_dates={"search-status": date(2026, 8, 26)},
    )
    assert newer_source["status"] == "refresh_required"
    assert "newer than" in newer_source["reasons"][0]

    stale = module.evaluate(
        ledger,
        as_of=date(2026, 9, 26),
        max_age_days=31,
        source_dates={},
    )
    assert stale["status"] == "refresh_required"
    assert "32 days old" in stale["reasons"][0]


def test_currentness_parsers_read_official_feed_shapes() -> None:
    module = _load_currentness_module()
    status_payload = json.dumps(
        [
            {
                "service_name": "Serving",
                "begin": "2026-08-24T00:00:00+00:00",
            },
            {
                "service_name": "Ranking",
                "begin": "2026-08-18T16:27:00+00:00",
            },
        ]
    ).encode()
    rss_payload = b"""<?xml version='1.0'?>
    <rss><channel><item>
      <pubDate>Thu, 20 Aug 2026 00:00:00 +0000</pubDate>
    </item></channel></rss>"""

    assert module.latest_ranking_incident(status_payload) == date(2026, 8, 18)
    assert module.latest_documentation_update(rss_payload) == date(2026, 8, 20)


def test_currentness_checker_rejects_untrusted_automated_source_urls() -> None:
    module = _load_currentness_module()
    ledger = _load_ledger()
    ledger["source_watch"][0]["url"] = "http://127.0.0.1/private"

    try:
        module._automated_sources(ledger)
    except ValueError as exc:
        assert "not allowlisted" in str(exc)
    else:
        raise AssertionError("untrusted automated source URL was accepted")


def test_scheduled_currentness_workflow_is_read_only() -> None:
    workflow = CURRENTNESS_WORKFLOW_PATH.read_text(encoding="utf-8")

    assert "schedule:" in workflow and "workflow_dispatch:" in workflow
    assert "contents: read" in workflow
    assert "check_google_currentness.py" in workflow
    assert "sync_google_updates.py --root . --check" in workflow
    assert "issues: write" not in workflow
    assert "contents: write" not in workflow


def test_unverified_entries_cannot_masquerade_as_verified() -> None:
    ledger = _load_ledger()
    verified_ids = {entry["id"] for entry in ledger["verified"]}
    unverified_ids = {entry["id"] for entry in ledger["unverified"]}

    assert verified_ids.isdisjoint(unverified_ids)


def test_schema_guidance_matches_current_google_contract() -> None:
    guidance = _normalized(
        "\n".join(
            (
                SCHEMA_SKILL_PATH.read_text(encoding="utf-8"),
                SCHEMA_REFERENCE_PATH.read_text(encoding="utf-8"),
            )
        )
    )

    assert "earns no SEO or AI-readiness credit" in guidance
    assert "one question with user-submitted answers" in guidance
    assert "Course Info" in guidance and "Course list" in guidance
    assert "PracticeProblem" in guidance
    assert "Dataset Search" in guidance
    assert "present in the rendered DOM" in guidance
    assert "40-60 words" not in guidance
    assert "AI citation support" not in guidance


def test_google_currentness_guidance_preserves_api_boundaries() -> None:
    guidance = _normalized(
        "\n".join(
            (
                GOOGLE_SKILL_PATH.read_text(encoding="utf-8"),
                GOOGLE_CURRENTNESS_PATH.read_text(encoding="utf-8"),
            )
        )
    )

    assert "Wait at least one full week" in guidance
    assert "Web Search, Images, Video mode, and News tab separately" in guidance
    assert "PENDING_REEVALUATION" in guidance
    assert "up to two weeks" in guidance
    assert "Do not promise clicks or queries" in guidance
    assert "Instagram, TikTok, X, and YouTube" in guidance
    assert "not a ranking signal" in guidance
    assert "SOURCE_CONFLICT" in guidance
    assert "PENDING_OBSERVATION" in guidance
    assert "fake reviews" in guidance
    assert "Google Ads API v25.2" in guidance
    assert "release notes and support table together" in guidance


def test_google_landscape_excludes_unsourced_market_and_recovery_claims() -> None:
    landscape = LANDSCAPE_PATH.read_text(encoding="utf-8")

    assert "machine-readable\nsource of truth" in landscape
    assert "Search Console Measurement Anomalies" in landscape
    assert "Review Integrity" in landscape
    assert "Source conflict" in landscape
    for unsupported in (
        "70.85%",
        "900M weekly users",
        "11.4% conversion rate",
        "Partial Helpful Content recoveries",
        "AI Overview Ads",
    ):
        assert unsupported not in landscape


def test_crawler_guidance_requires_behavioral_evidence_and_byte_visibility() -> None:
    guidance = _normalized(CRAWLER_REFERENCE_PATH.read_text(encoding="utf-8"))

    assert "first 2MB" in guidance
    assert "not a ranking factor" in guidance
    assert "Legitimate History API use is not a violation by itself" in guidance
    assert "Do not remove the hash" in guidance
    assert "do not force" in guidance
    assert "not injected via JavaScript" not in guidance