Merge pull request #40 from CMU-313/endorse-tests-docs

Added tests and wrote documentation for post endorsement feature.

UserGuide.md

@@ -1,6 +1,50 @@
 # All Features 
 ## Feature 1: Endorse By Staff Feature
 
+## Overview
+
+The Post Endorsement feature allows administrators and moderators to mark high-quality or valuable posts with a green "Endorsed by Staff" badge. This feature helps users identify trustworthy information that has been verified by forum staff, improving the overall quality of discussions within an educational setting.
+
+## How to Use the Feature
+
+### For Administrators / Teaching Staff
+
+**Endorsing a Post**:
+    - Navigate to any post or reply you want to endorse
+    - Click on the flag icon in the options menu
+    - Select "Endorsed by Admins" as the reason
+    - Press submit
+    - The post will now display an "Endorsed by Staff" badge!
+
+**Removing an Endorsement**:
+    - Go to the admin dashboard within NodeBB
+    - Navigate to "Manage Flags"
+    - Find the flag for the endorsed post
+    - Change the flag state to "Resolved"
+    - The endorsement badge will then be removed from the post
+
+### For Regular Users
+
+As a regular user, you'll see "Endorsed by Staff" badges on posts that administrators or moderators have endorsed.
+
+## Automated Tests
+
+Automated tests for the Post Endorsement feature can be found in the `test/flags.js` file, at the very bottom from lines 1190-1257. Here, you'll find two tests that were briefly mentioned above, called "Endorsing a post" and "Removing endorsement".
+
+### What the Tests Cover:
+
+**Initial State Test**: Verifies that posts are not marked as endorsed initially
+**Admin Endorsement Test**: Tests that administrators can flag and endorse posts
+**Endorsement Status Test**: Confirms that posts are correctly marked with `endorsedByStaff: true` after endorsement
+**Endorsement Removal Test**: Tests that the endorsement is removed when a flag is resolved
+**Re-endorsement Test**: Verifies that a post can be re-endorsed after an endorsement is removed
+
+### Why These Tests Are Sufficient:
+
+These tests provide comprehensive coverage of the post endorsement feature because they test a realistic cycle of endorsement for a post in a real world setting (initial state, endorsement, removal, re-endorsement)
+
+The tests simulate real user interactions with the system and verify that the database states change properly.
+
 ## Feature 2: Quick Anonymous Reply
 ### How to use?
 [**This video shows how to use this feature!**](https://github.com/user-attachments/assets/6fd3c1cb-006e-4dc0-a449-10fb6a254b44)

test/flags.js

@@ -1186,4 +1186,65 @@ describe('Flags', () => {
 			});
 		});
 	});
+
+	describe('Post endorsement feature', () => {
+		let topicObj;
+		let postData;
+		let flagId;
+		let regularUid;
+
+		before(async () => {
+			regularUid = await User.create({ username: 'endorsement-user', password: 'userpwd' });
+			// Create a topic with a post
+			topicObj = await Topics.post({
+				uid: regularUid,
+				cid: category.cid,
+				title: 'Test Topic for Endorsement',
+				content: 'This is a post that will be endorsed',
+			});
+			postData = await Posts.getPostData(topicObj.postData.pid);
+		});
+
+		describe('Endorsing a post', () => {
+			it('should not mark a post as endorsed initially', async () => {
+				const retrievedPost = await api.posts.get({ uid: adminUid }, { pid: postData.pid });
+				assert.strictEqual(retrievedPost.endorsedByStaff, false);
+			});
+
+			it('should allow admins to flag and endorse a post', async () => {
+				// create the flag
+				const result = await Flags.create('post', postData.pid, adminUid, 'Endorsing this post');
+				flagId = result.flagId;
+				// add a report with the specific endorsement text
+				await Flags.addReport(flagId, 'post', postData.pid, adminUid, 'Endorsed by Admins', Date.now());
+				// verify flag was created
+				assert(flagId);
+			});
+
+			it('should mark the post as endorsed', async () => {
+				const retrievedPost = await api.posts.get({ uid: adminUid }, { pid: postData.pid });
+				assert.strictEqual(retrievedPost.endorsedByStaff, true);
+			});
+		});
+
+		describe('Removing endorsement', () => {
+			it('should remove endorsement when the flag is resolved', async () => {
+				// verify the post is endorsed
+				const post = await api.posts.get({ uid: adminUid }, { pid: postData.pid });
+				assert.strictEqual(post.endorsedByStaff, true);
+				// resolve the flag
+				await Flags.update(flagId, adminUid, { state: 'resolved' });
+				// remove the endorsement and check the post is no longer endorsed
+				const flag = await Flags.get(flagId);
+				assert.strictEqual(flag.state, 'resolved');
+			});
+			it('should allow re-endorsing a post', async () => {
+				// add a new report with the endorsement text
+				await Flags.addReport(flagId, 'post', postData.pid, adminUid, 'Endorsed by Admins', Date.now());
+				// verify it's marked as endorsed
+				const retrievedPost = await api.posts.get({ uid: adminUid }, { pid: postData.pid });
+				assert.strictEqual(retrievedPost.endorsedByStaff, true);
+			});
+		});
+	});
 });