Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

24.1 KB
Raw Blame
# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========

import imaplib
import os
import smtplib
import unittest
from unittest.mock import MagicMock, patch

from camel.toolkits import IMAPMailToolkit


class TestIMAPMailToolkit(unittest.TestCase):
    r"""Test cases for IMAP Mail Toolkit."""

    def setUp(self):
        r"""Set up test fixtures."""
        # Mock environment variables
        self.env_patcher = patch.dict(
            os.environ,
            {
                'IMAP_SERVER': 'imap.test.com',
                'SMTP_SERVER': 'smtp.test.com',
                'EMAIL_USERNAME': '[email protected]',
                'EMAIL_PASSWORD': 'test_password',
            },
        )
        self.env_patcher.start()

        # Create toolkit instance
        self.toolkit = IMAPMailToolkit()

    def tearDown(self):
        r"""Clean up test fixtures."""
        self.env_patcher.stop()

    @patch('camel.toolkits.imap_mail_toolkit.imaplib.IMAP4_SSL')
    def test_get_imap_connection_success(self, mock_imap_ssl):
        r"""Test successful IMAP connection."""
        # Setup mock
        mock_imap = MagicMock()
        mock_imap_ssl.return_value = mock_imap

        # Call method
        result = self.toolkit._get_imap_connection()

        # Assertions
        self.assertEqual(result, mock_imap)
        mock_imap_ssl.assert_called_once_with('imap.test.com', 993)
        mock_imap.login.assert_called_once_with(
            '[email protected]', 'test_password'
        )

    @patch('camel.toolkits.imap_mail_toolkit.imaplib.IMAP4_SSL')
    def test_get_imap_connection_failure(self, mock_imap_ssl):
        r"""Test IMAP connection failure."""
        # Setup mock to raise exception
        mock_imap_ssl.side_effect = imaplib.IMAP4.error("Connection failed")

        # Call method and expect exception
        # (the actual exception, not ConnectionError)
        with self.assertRaises(imaplib.IMAP4.error):
            self.toolkit._get_imap_connection()

    @patch('camel.toolkits.imap_mail_toolkit.smtplib.SMTP')
    def test_get_smtp_connection_success(self, mock_smtp):
        r"""Test successful SMTP connection."""
        # Setup mock
        mock_smtp_instance = MagicMock()
        mock_smtp.return_value = mock_smtp_instance

        # Call method
        result = self.toolkit._get_smtp_connection()

        # Assertions
        self.assertEqual(result, mock_smtp_instance)
        mock_smtp.assert_called_once_with('smtp.test.com', 587)
        mock_smtp_instance.starttls.assert_called_once()
        mock_smtp_instance.login.assert_called_once_with(
            '[email protected]', 'test_password'
        )

    @patch('camel.toolkits.imap_mail_toolkit.smtplib.SMTP')
    def test_get_smtp_connection_failure(self, mock_smtp):
        r"""Test SMTP connection failure."""
        # Setup mock to raise exception
        mock_smtp.side_effect = smtplib.SMTPException("Connection failed")

        # Call method and expect exception
        with self.assertRaises(smtplib.SMTPException):
            self.toolkit._get_smtp_connection()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_fetch_emails_success(self, mock_get_imap):
        r"""Test successful email fetching."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])

        # Mock search results
        mock_imap.search.return_value = ("OK", [b"1"])
        mock_imap.fetch.return_value = ("OK", [(b"1", b"raw_email_data")])

        # Mock email message
        mock_message = MagicMock()
        mock_message.get.side_effect = lambda x, default="": {
            "Subject": "Test Subject",
            "From": "[email protected]",
            "To": "[email protected]",
            "Date": "Wed, 01 Jan 2024 00:00:00 +0000",
        }.get(x, default)

        with patch(
            'camel.toolkits.imap_mail_toolkit.email.message_from_bytes',
            return_value=mock_message,
        ):
            with patch.object(
                self.toolkit,
                '_extract_email_body',
                return_value={"plain": "Test body"},
            ):
                # Call method
                result = self.toolkit.fetch_emails(limit=1)

                # Assertions
                self.assertEqual(len(result), 1)
                self.assertEqual(result[0]["subject"], "Test Subject")
                self.assertEqual(result[0]["from"], "[email protected]")
                mock_imap.select.assert_called_once_with(
                    "INBOX", readonly=True
                )
                mock_imap.search.assert_called_once()
                mock_imap.fetch.assert_called_once_with(b"1", "(BODY.PEEK[])")

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_fetch_emails_with_filters(self, mock_get_imap):
        r"""Test email fetching with filters."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.search.return_value = ("OK", [b"1 2 3"])
        mock_imap.fetch.return_value = ("OK", [(b"1", b"raw_email_data")])

        # Mock email message
        mock_message = MagicMock()
        mock_message.get.return_value = "Test"

        with patch(
            'camel.toolkits.imap_mail_toolkit.email.message_from_bytes',
            return_value=mock_message,
        ):
            with patch.object(
                self.toolkit,
                '_extract_email_body',
                return_value={"plain": "Test body"},
            ):
                # Call method with filters
                result = self.toolkit.fetch_emails(
                    unread_only=True,
                    sender_filter="[email protected]",
                    subject_filter="Test Subject",
                )

                # Assertions
                self.assertIsInstance(result, list)
                mock_imap.select.assert_called_once_with(
                    "INBOX", readonly=True
                )
                # Check that search was called with proper criteria
                search_call = mock_imap.search.call_args[0]
                search_string = search_call[1]
                self.assertIn("UNSEEN", search_string)
                self.assertIn("FROM", search_string)
                self.assertIn("SUBJECT", search_string)

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_fetch_emails_search_failure(self, mock_get_imap):
        r"""Test email fetching with search failure."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.search.return_value = ("NO", [b"Error"])

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.fetch_emails()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_get_email_by_id_success(self, mock_get_imap):
        r"""Test successful email retrieval by ID."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.fetch.return_value = ("OK", [(b"1", b"raw_email_data")])

        # Mock email message
        mock_message = MagicMock()
        mock_message.get.side_effect = lambda x, default="": {
            "Subject": "Test Subject",
            "From": "[email protected]",
            "To": "[email protected]",
            "Date": "Wed, 01 Jan 2024 00:00:00 +0000",
            "Message-ID": "[email protected]",
            "In-Reply-To": "",
            "References": "",
            "X-Priority": "3",
        }.get(x, default)

        with patch(
            'camel.toolkits.imap_mail_toolkit.email.message_from_bytes',
            return_value=mock_message,
        ):
            with patch.object(
                self.toolkit,
                '_extract_email_body',
                return_value={"plain": "Test body"},
            ):
                # Call method
                result = self.toolkit.get_email_by_id("123")

                # Assertions
                self.assertEqual(result["id"], "123")
                self.assertEqual(result["subject"], "Test Subject")
                self.assertEqual(result["from"], "[email protected]")
                mock_imap.select.assert_called_once_with(
                    "INBOX", readonly=True
                )
                mock_imap.fetch.assert_called_once_with("123", "(BODY.PEEK[])")

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_get_email_by_id_fetch_failure(self, mock_get_imap):
        r"""Test email retrieval with fetch failure."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.fetch.return_value = ("NO", [b"Error"])

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.get_email_by_id("123")

    @patch.object(IMAPMailToolkit, '_get_smtp_connection')
    def test_send_email_success(self, mock_get_smtp):
        r"""Test successful email sending."""
        # Setup mock
        mock_smtp = MagicMock()
        mock_get_smtp.return_value = mock_smtp

        # Call method
        result = self.toolkit.send_email(
            to_recipients=["[email protected]"],
            subject="Test Subject",
            body="Test Body",
            html_body="<p>Test HTML</p>",
        )

        # Assertions
        self.assertIn("Email sent successfully", result)
        mock_smtp.send_message.assert_called_once()

    @patch.object(IMAPMailToolkit, '_get_smtp_connection')
    def test_send_email_with_cc_bcc(self, mock_get_smtp):
        r"""Test email sending with CC and BCC."""
        # Setup mock
        mock_smtp = MagicMock()
        mock_get_smtp.return_value = mock_smtp

        # Call method
        result = self.toolkit.send_email(
            to_recipients=["[email protected]"],
            subject="Test Subject",
            body="Test Body",
            cc_recipients=["[email protected]"],
            bcc_recipients=["[email protected]"],
        )

        # Assertions
        self.assertIn("Email sent successfully", result)
        # Check that send_message was called with all recipients
        call_args = mock_smtp.send_message.call_args
        self.assertIn("[email protected]", call_args[1]["to_addrs"])
        self.assertIn("[email protected]", call_args[1]["to_addrs"])
        self.assertIn("[email protected]", call_args[1]["to_addrs"])

    @patch.object(IMAPMailToolkit, '_get_smtp_connection')
    def test_send_email_failure(self, mock_get_smtp):
        r"""Test email sending failure."""
        # Setup mock to raise exception
        mock_get_smtp.side_effect = ConnectionError("SMTP connection failed")

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.send_email(
                to_recipients=["[email protected]"],
                subject="Test Subject",
                body="Test Body",
            )

    @patch.object(IMAPMailToolkit, 'get_email_by_id')
    @patch.object(IMAPMailToolkit, 'send_email')
    def test_reply_to_email_success(self, mock_send_email, mock_get_email):
        r"""Test successful email reply."""
        # Setup mocks
        mock_get_email.return_value = {
            "subject": "Original Subject",
            "from": "[email protected]",
            "message_id": "[email protected]",
        }
        mock_send_email.return_value = "Reply sent successfully"

        # Call method
        result = self.toolkit.reply_to_email(
            original_email_id="123", reply_body="Reply content"
        )

        # Assertions
        self.assertIn("Reply sent successfully", result)
        mock_get_email.assert_called_once_with("123", "INBOX")
        mock_send_email.assert_called_once()

    @patch.object(IMAPMailToolkit, 'get_email_by_id')
    def test_reply_to_email_no_original(self, mock_get_email):
        r"""Test email reply when original email not found."""
        # Setup mock to raise exception
        mock_get_email.side_effect = ConnectionError("Email not found")

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.reply_to_email(
                original_email_id="123", reply_body="Reply content"
            )

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_move_email_to_folder_success(self, mock_get_imap):
        r"""Test successful email moving."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.copy.return_value = ("OK", [b""])
        mock_imap.store.return_value = ("OK", [b""])
        mock_imap.expunge.return_value = ("OK", [b""])

        # Call method
        result = self.toolkit.move_email_to_folder(
            email_id="123", target_folder="Archive", source_folder="INBOX"
        )

        # Assertions
        self.assertIn("Email 123 moved from INBOX to Archive", result)
        mock_imap.select.assert_called_once_with("INBOX")
        mock_imap.copy.assert_called_once_with("123", "Archive")
        mock_imap.store.assert_called_once_with("123", '+FLAGS', '\\Deleted')
        mock_imap.expunge.assert_called_once()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_move_email_to_folder_failure(self, mock_get_imap):
        r"""Test email moving failure."""
        # Setup mock to raise exception
        mock_get_imap.side_effect = ConnectionError("IMAP connection failed")

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.move_email_to_folder(
                email_id="123", target_folder="Archive"
            )

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_delete_email_success(self, mock_get_imap):
        r"""Test successful email deletion."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.copy.return_value = ("OK", [b""])
        mock_imap.store.return_value = ("OK", [b""])
        mock_imap.expunge.return_value = ("OK", [b""])

        # Call method
        result = self.toolkit.delete_email("123", permanent=False)

        # Assertions
        self.assertIn("Email 123 moved to trash", result)
        mock_imap.select.assert_called_once_with("INBOX")
        mock_imap.store.assert_called_once_with("123", '+FLAGS', '\\Deleted')
        mock_imap.expunge.assert_called_once()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_delete_email_permanent(self, mock_get_imap):
        r"""Test permanent email deletion."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.store.return_value = ("OK", [b""])
        mock_imap.expunge.return_value = ("OK", [b""])

        # Call method
        result = self.toolkit.delete_email("123", permanent=True)

        # Assertions
        self.assertIn("Email 123 permanently deleted", result)
        mock_imap.select.assert_called_once_with("INBOX")
        mock_imap.store.assert_called_once_with("123", '+FLAGS', '\\Deleted')
        mock_imap.expunge.assert_called_once()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_delete_email_copy_failure_fallback(self, mock_get_imap):
        r"""Test soft delete fallback when trash copy fails."""
        # Setup mock
        mock_imap = MagicMock()
        mock_get_imap.return_value = mock_imap
        mock_imap.select.return_value = ("OK", [b""])
        mock_imap.copy.return_value = ("NO", [b"Error"])
        mock_imap.store.return_value = ("OK", [b""])
        mock_imap.expunge.return_value = ("OK", [b""])

        # Call method
        result = self.toolkit.delete_email("123", permanent=False)

        # Assertions
        self.assertIn("Email 123 marked as deleted", result)
        mock_imap.copy.assert_called_once_with("123", "Trash")
        mock_imap.store.assert_called_once_with("123", '+FLAGS', '\\Deleted')
        mock_imap.expunge.assert_called_once()

    @patch.object(IMAPMailToolkit, '_get_imap_connection')
    def test_delete_email_failure(self, mock_get_imap):
        r"""Test email deletion failure."""
        # Setup mock to raise exception
        mock_get_imap.side_effect = ConnectionError("IMAP connection failed")

        # Call method and expect exception
        with self.assertRaises(ConnectionError):
            self.toolkit.delete_email("123")

    def test_extract_email_body_plain_text(self):
        r"""Test email body extraction for plain text."""
        # Create mock email message
        mock_message = MagicMock()
        mock_message.is_multipart.return_value = False
        mock_message.get_content_type.return_value = "text/plain"
        mock_message.get_payload.return_value = b"Plain text content"

        # Call method
        result = self.toolkit._extract_email_body(mock_message)

        # Assertions
        self.assertEqual(result["plain"], "Plain text content")
        self.assertEqual(result["html"], "")

    def test_extract_email_body_html(self):
        r"""Test email body extraction for HTML."""
        # Create mock email message
        mock_message = MagicMock()
        mock_message.is_multipart.return_value = False
        mock_message.get_content_type.return_value = "text/html"
        mock_message.get_payload.return_value = b"<p>HTML content</p>"

        # Call method
        result = self.toolkit._extract_email_body(mock_message)

        # Assertions
        self.assertEqual(result["plain"], "")
        self.assertEqual(result["html"], "<p>HTML content</p>")

    def test_extract_email_body_multipart(self):
        r"""Test email body extraction for multipart message."""
        # Create mock email message
        mock_message = MagicMock()
        mock_message.is_multipart.return_value = True

        # Create mock parts
        mock_part1 = MagicMock()
        mock_part1.get_content_type.return_value = "text/plain"
        mock_part1.get.return_value = "inline"  # Not an attachment
        mock_part1.get_payload.return_value = b"Plain text content"

        mock_part2 = MagicMock()
        mock_part2.get_content_type.return_value = "text/html"
        mock_part2.get.return_value = "inline"  # Not an attachment
        mock_part2.get_payload.return_value = b"<p>HTML content</p>"

        # Mock the main message to have no content disposition
        mock_message.get.return_value = None
        mock_message.walk.return_value = [mock_message, mock_part1, mock_part2]

        # Call method
        result = self.toolkit._extract_email_body(mock_message)

        # Assertions
        self.assertEqual(result["plain"], "Plain text content")
        self.assertEqual(result["html"], "<p>HTML content</p>")

    def test_get_tools(self):
        r"""Test getting available tools."""
        # Call method
        tools = self.toolkit.get_tools()

        # Assertions
        self.assertIsInstance(tools, list)
        self.assertEqual(len(tools), 6)  # 6 public methods

        # Check that all expected tools are present
        tool_names = [tool.func.__name__ for tool in tools]
        expected_tools = [
            'fetch_emails',
            'get_email_by_id',
            'send_email',
            'reply_to_email',
            'move_email_to_folder',
            'delete_email',
        ]

        for expected_tool in expected_tools:
            self.assertIn(expected_tool, tool_names)

    def test_toolkit_initialization_with_credentials(self):
        r"""Test toolkit initialization with direct credentials."""
        # Create toolkit with direct credentials
        toolkit = IMAPMailToolkit(
            imap_server="custom.imap.com",
            smtp_server="custom.smtp.com",
            username="[email protected]",
            password="custom_password",
        )

        # Assertions
        self.assertEqual(toolkit.imap_server, "custom.imap.com")
        self.assertEqual(toolkit.smtp_server, "custom.smtp.com")
        self.assertEqual(toolkit.username, "[email protected]")
        self.assertEqual(toolkit.password, "custom_password")

    def test_get_imap_connection_missing_credentials(self):
        r"""Test IMAP connection with missing credentials."""
        # Test missing IMAP server - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server=None,
                smtp_server="smtp.test.com",
                username="[email protected]",
                password="test_password",
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_imap_connection()

            self.assertIn("IMAP server", str(context.exception))

        # Test missing username - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server="imap.test.com",
                smtp_server="smtp.test.com",
                username=None,
                password="test_password",
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_imap_connection()

            self.assertIn("username", str(context.exception))

        # Test missing password - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server="imap.test.com",
                smtp_server="smtp.test.com",
                username="[email protected]",
                password=None,
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_imap_connection()

            self.assertIn("password", str(context.exception))

    def test_get_smtp_connection_missing_credentials(self):
        r"""Test SMTP connection with missing credentials."""
        # Test missing SMTP server - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server="imap.test.com",
                smtp_server=None,
                username="[email protected]",
                password="test_password",
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_smtp_connection()

            self.assertIn("SMTP server", str(context.exception))

        # Test missing username - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server="imap.test.com",
                smtp_server="smtp.test.com",
                username=None,
                password="test_password",
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_smtp_connection()

            self.assertIn("username", str(context.exception))

        # Test missing password - must clear envs
        with patch.dict(os.environ, {}, clear=True):
            toolkit = IMAPMailToolkit(
                imap_server="imap.test.com",
                smtp_server="smtp.test.com",
                username="[email protected]",
                password=None,
            )

            with self.assertRaises(ValueError) as context:
                toolkit._get_smtp_connection()

            self.assertIn("password", str(context.exception))


if __name__ == '__main__':
    unittest.main()