Integration Testing

This guide explains how to run end-to-end integration tests for each backend. These tests verify that your credentials and permissions are set up correctly and that all backend functionality works as expected.

Overview

Integration tests are located in chatom/tests/integration/ and are designed to be run as standalone scripts. They require:

1. Real credentials for the target platform

2. A test channel/room where the bot can send messages

3. Human interaction to verify the bot’s behavior

Each test will:

• Connect to the platform

• Test all available functionality

• Send messages to the test channel

• Report which tests passed/failed

Running Tests

Tests are run as standalone Python scripts:

python -m chatom.tests.integration.e2e.<backend>

For example:

python -m chatom.tests.integration.e2e.discord
python -m chatom.tests.integration.e2e.slack
python -m chatom.tests.integration.e2e.symphony

---

Discord Integration Test

Prerequisites

1. Create a Discord Application at Discord Developer Portal

2. Create a Bot under the application

3. Copy the Bot Token

4. Enable Required Intents:

   • Presence Intent (optional, for presence tests)

   • Server Members Intent (optional, for member tests)

   • Message Content Intent (required for reading message content)

5. Invite the bot to your test server with appropriate permissions

Required Scopes and Permissions

When creating the invite URL, include:

Scopes:

• bot

• applications.commands (if using slash commands)

Bot Permissions:

• Send Messages

• Read Message History

• Add Reactions

• Manage Messages (for reaction removal)

• Create Public Threads (for thread tests)

Environment Variables

export DISCORD_BOT_TOKEN="your-bot-token"
export DISCORD_TEST_CHANNEL_ID="123456789012345678"
export DISCORD_TEST_USER_ID="987654321098765432"
export DISCORD_TEST_GUILD_ID="111222333444555666"  # Optional

Variable	Required	Description
DISCORD_BOT_TOKEN	Yes	Bot token from Developer Portal
DISCORD_TEST_CHANNEL_ID	Yes	Text channel ID for tests
DISCORD_TEST_USER_ID	Yes	Your user ID for mention tests
DISCORD_TEST_GUILD_ID	No	Guild ID for guild-specific tests

Getting IDs

Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode), then right-click on channels/users/servers to copy their IDs.

Run

python -m chatom.tests.integration.e2e.discord

What’s Tested

Feature	Test Description
Connection	Connect to Discord gateway
Plain Messages	Send simple text messages
Formatted Messages	Bold, italic, code blocks
Fetch User	Look up user by ID
Fetch Channel	Look up channel by ID
Mentions	User and channel mentions
Reactions	Add and remove emoji reactions
Threads	Create threads and reply
Rich Content	Tables rendered in Discord markdown
Message History	Fetch recent messages
Presence	Set bot status

---

Slack Integration Test

Prerequisites

1. Create a Slack App at Slack API

2. Install to Workspace

3. Copy the Bot Token (starts with xoxb-)

4. Add Required Scopes

Required OAuth Scopes

Add these under OAuth & Permissions:

Scope	Purpose
chat:write	Send messages
channels:read	Read channel info
channels:history	Read message history (public channels)
groups:history	Read message history (private channels)
users:read	Read user info
reactions:write	Add reactions
reactions:read	Read reactions
im:write	Create DMs
users.profile:write	Set status (optional, requires user token)
connections:write	Socket Mode (optional, for inbound messages)

Environment Variables

export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_TEST_CHANNEL_NAME="test-channel"  # Channel name without #
export SLACK_TEST_USER_NAME="john.doe"  # Username without @
export SLACK_APP_TOKEN="xapp-your-app-token"  # Optional, for Socket Mode

Variable	Required	Description
SLACK_BOT_TOKEN	Yes	Bot OAuth token (xoxb-…)
SLACK_TEST_CHANNEL_NAME	Yes	Channel name for tests (without #)
SLACK_TEST_USER_NAME	Yes	Username for mention tests (without @)
SLACK_APP_TOKEN	No	App token for Socket Mode (enables inbound message test)

Finding Channel/User Names

• Channel Name: The channel name as shown in Slack (without the #)

• User Name: The username or display name as shown in user profiles

Run

python -m chatom.tests.integration.e2e.slack

What’s Tested

Feature	Test Description
Connection	Connect and authenticate
Channel/User Lookup	Look up by name to get IDs
Plain Messages	Send simple text messages
Formatted Messages	mrkdwn formatting (bold, italic, code)
Fetch User	Look up user by ID
Fetch Channel	Look up channel by ID
Mentions	User, channel, @here, @channel, @everyone
Reactions	Add and remove emoji reactions
Threads	Create threads and reply
Rich Content	Tables in mrkdwn format
Message History	Fetch recent messages
Presence	Get user status
DM Creation	Create direct messages
Inbound Messages	Receive and parse bot mentions (requires Socket Mode)

---

Symphony Integration Test

Prerequisites

1. Symphony Bot Account configured by your Symphony administrator

2. RSA Key Pair for authentication

3. Bot Service Account with appropriate entitlements

Required Entitlements

Your bot needs:

• Send messages to streams

• Read messages from streams

• Look up users

• Set presence

Environment Variables

export SYMPHONY_HOST="mycompany.symphony.com"
export SYMPHONY_BOT_USERNAME="my-bot"
export SYMPHONY_BOT_PRIVATE_KEY_PATH="/path/to/private-key.pem"
export SYMPHONY_TEST_ROOM_NAME="E2E Test Room"
export SYMPHONY_TEST_USER_NAME="jsmith"

Or use key content directly:

export SYMPHONY_BOT_PRIVATE_KEY_CONTENT="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"

Or use a combined certificate (key+cert in one PEM file):

export SYMPHONY_BOT_COMBINED_CERT_PATH="/path/to/combined.pem"
# or
export SYMPHONY_BOT_COMBINED_CERT_CONTENT="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"

Variable	Required	Description
SYMPHONY_HOST	Yes	Pod hostname
SYMPHONY_BOT_USERNAME	Yes	Bot service account name
SYMPHONY_BOT_PRIVATE_KEY_PATH	Yes*	Path to RSA private key
SYMPHONY_BOT_PRIVATE_KEY_CONTENT	Yes*	RSA key content (alternative)
SYMPHONY_BOT_COMBINED_CERT_PATH	Yes*	Path to combined cert file (key+cert in PEM)
SYMPHONY_BOT_COMBINED_CERT_CONTENT	Yes*	Combined cert content (key+cert in PEM)
SYMPHONY_TEST_ROOM_NAME	Yes	Room name for tests (looked up automatically)
SYMPHONY_TEST_USER_NAME	Yes	Username for mention tests (looked up automatically)
SYMPHONY_AGENT_HOST	No	Separate agent hostname
SYMPHONY_SESSION_AUTH_HOST	No	Separate session auth hostname
SYMPHONY_KEY_MANAGER_HOST	No	Separate key manager hostname

*One of private key (_PATH or _CONTENT) or combined cert (_PATH or _CONTENT) is required.

Getting Room Name

In Symphony, the room name is the display name shown in the room header. The test will automatically look up the room by name to get its stream ID.

Run

python -m chatom.tests.integration.e2e.symphony

What’s Tested

Feature	Test Description
Connection	Authenticate with RSA key or combined cert
Room Lookup	Search room by name to get stream ID
User Lookup	Search user by username to get user ID
Plain Messages	Send MessageML messages
MessageML Formatting	Native Symphony formatting
Format System	Convert FormattedMessage to MessageML
Fetch User	Look up user by ID
Mentions	<mention uid="..."/> tags
Hashtags	<hash tag="..."/> tags
Cashtags	<cash tag="..."/> (stock tickers)
Rich Content	Tables in MessageML
Message History	Fetch and parse PresentationML
Presence	Get/set presence status
DM/IM Creation	Create 1:1 DMs and multi-party IMs
Room Creation	Create private rooms
Inbound Messages	Receive messages via datafeed, detect bot mentions

---

Troubleshooting

Common Issues

“Module not found” errors

Ensure chatom is installed:

pip install -e .
# or
uv pip install -e .

Authentication failures

• Verify your credentials are correct

• Check that tokens haven’t expired

• Ensure the bot has been invited/added to the test channel

Permission errors

• Verify the bot has required permissions/scopes

• Check that the bot has access to the test channel

• Review the platform’s permission documentation

Rate limiting

• The tests include delays between operations

• If you see rate limit errors, wait and try again

• Consider using a less busy test channel

Debug Mode

Add verbose output by setting:

export CHATOM_DEBUG=1
python -m chatom.tests.integration.e2e.slack

Reporting Issues

If a test fails unexpectedly:

1. Check the error message for details

2. Verify environment variables are set correctly

3. Ensure the backend library is installed (e.g., discord.py, slack_sdk)

4. Check platform-specific documentation for changes

---

Writing Custom Integration Tests

You can use the existing tests as templates for your own integration tests. Key patterns:

import asyncio
from chatom.slack import SlackBackend, SlackConfig

async def my_custom_test():
    # Read config from environment
    config = SlackConfig(bot_token=os.environ["SLACK_BOT_TOKEN"])
    backend = SlackBackend(config=config)

    # Connect
    await backend.connect()

    try:
        # Your test code here
        await backend.send_message("C123", "Test message")
        messages = await backend.fetch_messages("C123", limit=5)

        for msg in messages:
            formatted = msg.to_formatted()
            print(formatted.render(Format.PLAINTEXT))
    finally:
        # Always disconnect
        await backend.disconnect()

if __name__ == "__main__":
    asyncio.run(my_custom_test())

---

Feature Comparison

Feature	Discord	Slack	Symphony
Messages	✅	✅	✅
Formatting	✅	✅	✅
Reactions	✅	✅	❌
Threads	✅	✅	❌
Mentions	✅	✅	✅
History	✅	✅	✅
Presence	✅	✅	✅
Attachments	✅	✅	✅
Real-time	✅	✅	✅

Legend:

• ✅ Fully supported

• ⚠️ Limited support

• ❌ Not supported