Skip to content

Meta Ads (Facebook/Instagram) MCP server for Claude, ChatGPT, Perplexity & Cursor — the Meta node of Pipeboard’s 5-platform family (+ Google, TikTok, Snap, Reddit). Hosted remote MCP, badged Meta Business Partner, free plan — no self-hosting required.

26.6 KB
Raw Blame
"""Tests for FLEX (DEGREES_OF_FREEDOM) creative features.

Tests for create_ad_creative and update_ad_creative support for:
- optimization_type="DEGREES_OF_FREEDOM" in asset_feed_spec
- Multiple image_hashes (up to 10)
- Multiple messages (primary text variants)
- Validation of mutual exclusivity and limits
- Backward compatibility (no optimization_type → same behavior as before)
"""

import pytest
import json
from unittest.mock import AsyncMock, patch
from meta_ads_mcp.core.ads import create_ad_creative, update_ad_creative


@pytest.mark.asyncio
class TestFlexCreatives:
    """Test cases for FLEX (Advantage+) creative features."""

    async def test_flex_creative_includes_optimization_type(self):
        """FLEX creative with optimization_type='DEGREES_OF_FREEDOM' includes it in asset_feed_spec."""
        sample_creative_data = {
            "id": "123456789",
            "name": "FLEX Creative",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="FLEX Creative",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                message="Test message",
                optimization_type="DEGREES_OF_FREEDOM",
                call_to_action_type="LEARN_MORE"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["optimization_type"] == "DEGREES_OF_FREEDOM"

    async def test_flex_creative_multiple_image_hashes(self):
        """Multiple image_hashes with DOF: call proceeds but includes a warning in the response."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Multi-Image FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Multi-Image FLEX",
                image_hashes=["hash1", "hash2", "hash3"],
                page_id="987654321",
                link_url="https://example.com",
                message="Test message",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True
            # Warning is present in the response
            assert "warning" in result_data
            assert "DEGREES_OF_FREEDOM" in result_data["warning"]

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["images"] == [
                {"hash": "hash1"},
                {"hash": "hash2"},
                {"hash": "hash3"}
            ]

    async def test_flex_creative_multiple_messages(self):
        """Multiple messages produces correct bodies array in asset_feed_spec."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Multi-Message FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Multi-Message FLEX",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                messages=["Primary text A", "Primary text B", "Primary text C"],
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["bodies"] == [
                {"text": "Primary text A"},
                {"text": "Primary text B"},
                {"text": "Primary text C"}
            ]

    async def test_validation_cannot_mix_image_hash_and_image_hashes(self):
        """Cannot specify both image_hash and image_hashes."""
        result = await create_ad_creative(
            access_token="test_token",
            account_id="act_123456789",
            name="Test",
            image_hash="abc123",
            image_hashes=["hash1", "hash2"],
            page_id="987654321"
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "Only one media source" in error_data["error"]
        else:
            assert "error" in result_data
            assert "Only one media source" in result_data["error"]

    async def test_validation_cannot_mix_message_and_messages(self):
        """Cannot specify both message and messages."""
        result = await create_ad_creative(
            access_token="test_token",
            account_id="act_123456789",
            name="Test",
            image_hash="abc123",
            page_id="987654321",
            message="Single text",
            messages=["Text A", "Text B"]
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "Cannot specify both 'message' and 'messages'" in error_data["error"]
        else:
            assert "error" in result_data
            assert "Cannot specify both 'message' and 'messages'" in result_data["error"]

    async def test_validation_max_10_image_hashes(self):
        """Maximum 10 image hashes allowed for FLEX creatives."""
        too_many = [f"hash{i}" for i in range(11)]

        result = await create_ad_creative(
            access_token="test_token",
            account_id="act_123456789",
            name="Test",
            image_hashes=too_many,
            page_id="987654321"
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "Maximum 10 image hashes" in error_data["error"]
        else:
            assert "error" in result_data
            assert "Maximum 10 image hashes" in result_data["error"]

    async def test_optimization_type_placement_accepted(self):
        """PLACEMENT optimization_type is accepted (not blocked)."""
        # optimization_type=PLACEMENT should be passed through to Meta API.
        # It will fail on link_url validation since we do not provide it here,
        # but it must NOT be rejected with "Invalid optimization_type".
        result = await create_ad_creative(
            access_token="test_token",
            account_id="act_123456789",
            name="Test",
            image_hash="abc123",
            page_id="987654321",
            optimization_type="PLACEMENT"
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            # Should NOT have "Invalid optimization_type" error
            if "error" in error_data:
                assert "Invalid optimization_type" not in error_data["error"]
        else:
            if "error" in result_data:
                assert "Invalid optimization_type" not in result_data["error"]

    async def test_flex_creative_single_image_uses_asset_feed_spec(self):
        """FLEX creative with single image still uses asset_feed_spec when optimization_type is set."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Single Image FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Single Image FLEX",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                message="Test message",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            # Should use asset_feed_spec even with single image when optimization_type is set
            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["images"] == [{"hash": "abc123"}]
            assert creative_data["asset_feed_spec"]["optimization_type"] == "DEGREES_OF_FREEDOM"
            # object_story_spec needs page_id + link_data with destination URL
            # (Meta rejects object_story_spec without link — error 2061015)
            # DOF link_data must include image_hash for Meta to find the image
            # (fix for subcode 2446388 "Could not get image for creative")
            assert creative_data["object_story_spec"] == {
                "page_id": "987654321",
                "link_data": {"link": "https://example.com", "image_hash": "abc123"}
            }

    async def test_no_optimization_type_unchanged_behavior(self):
        """Without optimization_type, single image+headline uses object_story_spec (backward compat)."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Simple Creative",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Simple Creative",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                message="Test message",
                headline="Single Headline"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            # Should use traditional object_story_spec with link_data
            assert "object_story_spec" in creative_data
            assert "link_data" in creative_data["object_story_spec"]
            assert creative_data["object_story_spec"]["link_data"]["image_hash"] == "abc123"
            assert "asset_feed_spec" not in creative_data

    async def test_flex_creative_full_combination(self):
        """FLEX creative with all plural params: image_hashes, messages, headlines, descriptions."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Full FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Full FLEX",
                image_hashes=["hash1", "hash2"],
                page_id="987654321",
                link_url="https://example.com",
                messages=["Text A", "Text B"],
                headlines=["Headline 1", "Headline 2"],
                descriptions=["Desc 1", "Desc 2"],
                optimization_type="DEGREES_OF_FREEDOM",
                call_to_action_type="SHOP_NOW"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            afs = creative_data["asset_feed_spec"]
            assert afs["optimization_type"] == "DEGREES_OF_FREEDOM"
            assert afs["images"] == [{"hash": "hash1"}, {"hash": "hash2"}]
            assert afs["bodies"] == [{"text": "Text A"}, {"text": "Text B"}]
            assert afs["titles"] == [{"text": "Headline 1"}, {"text": "Headline 2"}]
            assert afs["descriptions"] == [{"text": "Desc 1"}, {"text": "Desc 2"}]
            # DOF: CTA goes in object_story_spec.link_data, not in asset_feed_spec
            assert "call_to_action_types" not in afs
            # DOF: link_urls omitted, link goes in link_data.link
            assert "link_urls" not in afs

            # Multi-image: link_data must include image_hash as primary anchor.
            # Without it, Meta silently ignores asset_feed_spec.
            # CTA is placed in link_data for DOF creatives.
            assert creative_data["object_story_spec"] == {
                "page_id": "987654321",
                "link_data": {
                    "link": "https://example.com",
                    "image_hash": "hash1",
                    "call_to_action": {"type": "SHOP_NOW", "value": {"link": "https://example.com"}},
                },
            }

    async def test_image_hashes_without_optimization_type_uses_asset_feed(self):
        """image_hashes (plural) triggers asset_feed_spec even without optimization_type."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Multi Image",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="Multi Image",
                image_hashes=["hash1", "hash2"],
                page_id="987654321",
                link_url="https://example.com",
                message="Test message"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["images"] == [
                {"hash": "hash1"}, {"hash": "hash2"}
            ]
            # No optimization_type should be set
            assert "optimization_type" not in creative_data["asset_feed_spec"]

            # Non-DOF: object_story_spec must NOT contain link_data;
            # URLs, images, CTA live exclusively in asset_feed_spec.
            assert creative_data["object_story_spec"]["page_id"] == "987654321"
            assert "link_data" not in creative_data["object_story_spec"]

    async def test_no_image_hash_or_image_hashes_returns_error(self):
        """Must provide either image_hash, image_hashes, or video_id."""
        result = await create_ad_creative(
            access_token="test_token",
            account_id="act_123456789",
            name="Test",
            page_id="987654321"
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "no media provided" in error_data["error"].lower()
        else:
            assert "error" in result_data
            assert "no media provided" in result_data["error"].lower()


@pytest.mark.asyncio
class TestFlexCreativesUpdate:
    """Test cases for FLEX creative support in update_ad_creative."""

    async def test_update_with_optimization_type(self):
        """Update creative with optimization_type includes it in asset_feed_spec."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Updated FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await update_ad_creative(
                access_token="test_token",
                creative_id="123456789",
                optimization_type="DEGREES_OF_FREEDOM",
                headlines=["New Headline"]
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["optimization_type"] == "DEGREES_OF_FREEDOM"

    async def test_update_with_messages_plural(self):
        """Update creative with messages (plural) produces correct bodies array."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Updated",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await update_ad_creative(
                access_token="test_token",
                creative_id="123456789",
                messages=["Text A", "Text B"]
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["bodies"] == [
                {"text": "Text A"}, {"text": "Text B"}
            ]

    async def test_update_validation_cannot_mix_message_and_messages(self):
        """Cannot specify both message and messages in update."""
        result = await update_ad_creative(
            access_token="test_token",
            creative_id="123456789",
            message="Single",
            messages=["A", "B"]
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "Cannot specify both 'message' and 'messages'" in error_data["error"]
        else:
            assert "error" in result_data
            assert "Cannot specify both 'message' and 'messages'" in result_data["error"]

    async def test_update_validation_invalid_optimization_type(self):
        """Invalid optimization_type rejected in update."""
        result = await update_ad_creative(
            access_token="test_token",
            creative_id="123456789",
            optimization_type="BAD_VALUE"
        )

        result_data = json.loads(result)
        if "data" in result_data:
            error_data = json.loads(result_data["data"])
            assert "error" in error_data
            assert "Invalid optimization_type" in error_data["error"]
        else:
            assert "error" in result_data
            assert "Invalid optimization_type" in result_data["error"]

    async def test_update_optimization_type_alone_triggers_asset_feed(self):
        """Setting only optimization_type triggers asset_feed_spec path."""
        sample_creative_data = {
            "id": "123456789",
            "name": "FLEX",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await update_ad_creative(
                access_token="test_token",
                creative_id="123456789",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["optimization_type"] == "DEGREES_OF_FREEDOM"


@pytest.mark.asyncio
class TestSingularParamPromotion:
    """Test that singular headline/description/message are auto-promoted in asset_feed_spec path."""

    async def test_singular_headline_promoted_with_optimization_type(self):
        """Singular headline is auto-promoted to titles array when optimization_type forces asset_feed_spec."""
        sample_creative_data = {
            "id": "123456789",
            "name": "FLEX with singular headline",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="FLEX with singular headline",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                headline="My Single Headline",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["titles"] == [{"text": "My Single Headline"}]

    async def test_singular_description_promoted_with_optimization_type(self):
        """Singular description is auto-promoted to descriptions array when optimization_type forces asset_feed_spec."""
        sample_creative_data = {
            "id": "123456789",
            "name": "FLEX with singular description",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="FLEX with singular description",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                description="My Single Description",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["descriptions"] == [{"text": "My Single Description"}]

    async def test_all_singular_params_promoted_with_optimization_type(self):
        """All singular params (headline, description, message) promoted when optimization_type is set."""
        sample_creative_data = {
            "id": "123456789",
            "name": "FLEX all singular",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await create_ad_creative(
                access_token="test_token",
                account_id="act_123456789",
                name="FLEX all singular",
                image_hash="abc123",
                page_id="987654321",
                link_url="https://example.com",
                message="My message",
                headline="My headline",
                description="My description",
                optimization_type="DEGREES_OF_FREEDOM",
                call_to_action_type="LEARN_MORE"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            afs = creative_data["asset_feed_spec"]
            assert afs["optimization_type"] == "DEGREES_OF_FREEDOM"
            assert afs["titles"] == [{"text": "My headline"}]
            assert afs["descriptions"] == [{"text": "My description"}]
            assert afs["bodies"] == [{"text": "My message"}]
            # DOF: CTA goes in object_story_spec.link_data, not in asset_feed_spec
            assert "call_to_action_types" not in afs
            assert afs["images"] == [{"hash": "abc123"}]

            # CTA is placed in link_data for DOF creatives
            assert creative_data["object_story_spec"]["link_data"]["call_to_action"] == {
                "type": "LEARN_MORE", "value": {"link": "https://example.com"}
            }

    async def test_update_singular_headline_promoted_with_optimization_type(self):
        """Singular headline promoted in update_ad_creative when optimization_type is set."""
        sample_creative_data = {
            "id": "123456789",
            "name": "Updated",
            "status": "ACTIVE"
        }

        with patch('meta_ads_mcp.core.ads.make_api_request', new_callable=AsyncMock) as mock_api:
            mock_api.return_value = sample_creative_data

            result = await update_ad_creative(
                access_token="test_token",
                creative_id="123456789",
                headline="Updated Headline",
                optimization_type="DEGREES_OF_FREEDOM"
            )

            result_data = json.loads(result)
            assert result_data["success"] is True

            call_args_list = mock_api.call_args_list
            first_call = call_args_list[0]
            creative_data = first_call[0][2]

            assert "asset_feed_spec" in creative_data
            assert creative_data["asset_feed_spec"]["titles"] == [{"text": "Updated Headline"}]