trustcafe-api-wrapper/docs/DOCUMENTATION_TEST_REPORT.md

Documentation Test Report - Alpha Environment

Date: 2026-04-19
Tester: BarnacleBoy
Environment: alpha

---

Executive Summary

Most wrapper functions work correctly. Several wrappers hit API server errors (500/502) which suggests alpha API endpoints are not fully operational for social operations (follow, trust, react, update).

---

Test Results

Working Wrappers

Wrapper	Status	Notes
create_post	✅ Working	Verified - post created with Spongebob quotes
create_comment	✅ Working	Verified - comments attach to posts correctly

Wrappers with API Errors

Wrapper	Status	Error	Notes
follow	❌ Error	502 Bad Gateway	Endpoint /alpha/relfollow returns学师 Bad Gateway
react	❌ Error	500 Internal Server Error	Endpoint /alpha/reacttosomething returns 500
trust	❌ Error	500 Internal Server Error	Endpoint /alpha/reltrust returns 500
update_post	❌ Error	500 Internal Server Error	Endpoint /alpha/post/update returns 500

Wrappers with Unclear Behavior

Wrapper	Status	Notes
votecast	⚠️ Unclear	Returns empty dict {} - no error thrown but no data returned

---

Static Documentation Issues Found

1. APIClient.wrapped() Docstring (Code Bug)

File: src/trustcafeapiwrapper/apiclient.py lines 207, 209

Issue: Docstring says 'job' but code reads "job_function"

# Docstring says (incorrect):
wrapped_data (dict): A dictionary with 'job' (string) and 'payload' (dict) keys.

# But code reads:
return self.run_job(wrapped_data.get("job_function"), wrapped_data.get("payload", {}))

Impact: Low - all wrapper functions return {"job_function": ..., "payload": ...} which matches what wrapped() reads. Only the docstring is misleading.

Proposed Fix (code): Update docstring:

wrapped_data (dict): A dictionary with 'job_function' (string) and 'payload' (dict) keys.

---

2. update_post wrapper docstring (Code Bug)

File: src/trustcafeapiwrapper/wrappers/post/update_post.py line 16

Issue: Internal docstring references post_slug but parameter is post_path

def update_post(
    post_text:str, 
    post_path:str|None=None,  # Parameter is post_path
    ...
):
    """
    Args:
        post_slug (str): The slug of the post to update.  # Docstring says post_slug - WRONG
    """

Impact: Low - parameter names in function signature are correct. Only internal docstring is wrong.

Proposed Fix (code):

post_path (str, optional): The path of the post to update.

---

3. feed.followingfeed vs feed.following (Documentation Bug)

File: docs/API_REFERENCE.md line 688

Issue: Documents feed.followingfeed() but actual job function is feed.following

# Documentation says:
feed = API.run_job('feed.followingfeed')

# But actual job is:
feed = API.run_job('feed.following')

Impact: Medium - user will get AttributeError trying to use undocumented job name.

Proposed Fix (docs): Update line 688 from:

### feed.followingfeed()

to:

### feed.following()

And update example from:

following_feed = API.run_job('feed.followingfeed')

to:

following_feed = API.run_job('feed.following')

---

Recommendations

1. For Alpha API: Several social operations (follow, trust, react, update_post) are returning 500 errors. These need backend fixes before wrappers can be verified working.

2. For Documentation: Fix the three static issues above to match code reality.

3. For votecast: Verify if empty dict return is expected behavior or if there's a response that should be returned.

---

Test Assets Created

Five Spongebob-themed posts created for testing:

1. "I wumbo, you wumbo, he wumbo, we wumbo!"
2. "The best time to wear a sweater is all the time."
3. "I'm a Goofy Goober, yeah!"
4. "Life is fun. But fun is different."
5. "Patrick, you in danger, homie."

Post IDs saved to /home/agent/trustcafe-test-posts.json