Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-12-04T04:18:34Z

Wagrocho: Add pull request section and link

This page contains the details of OSS project ''E2451: Reimplement feedback response map'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions, among other tasks. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

=== Project Overview ===

The goal of this project is to refactor the feedback_response_map.rb file from the Expertiza repository and integrate it into the reimplementation-back-end repository. Within Expertiza, when a user submits a review, an instance of the Response class is created, associated with a ResponseMap. Each ResponseMap links a reviewer (reviewer_id), reviewee (reviewee_id), and the reviewed item (reviewed_object_id). FeedbackResponseMap, a subclass of ResponseMap, represents the feedback provided by a reviewee on the feedback received for their submission.

This class has significant room for improvement, especially with respect to object-oriented principles. Refactoring feedback_response_map.rb will streamline functionality, enhance maintainability, and improve adherence to coding standards.

=== Current Implementation ===

The current feedback_response_map.rb in the Expertiza repository has several issues. It includes the following problems:

* Poor adherence to SOLID and DRY principles: The current code structure introduces unnecessary repetition and complexity.
* feedback_response_report Method Issues: This critical method is highly complex, relying on custom data structures and separate containers for each review round, resulting in a DRY violation.
* Improper Responsibility Assignment: The email method does not belong within this class and would benefit from refactoring out into a separate class using the Visitor pattern. This pattern is suggested to streamline functionality, though alternative design patterns may be considered if more suitable.
* Memory Inefficiencies: The method currently creates unnecessary memory through inefficient structures, including multiple separate arrays for different rounds of review, which could be simplified into a 2D array structure.
* Code Smells: The code has redundant methods, unclear variable names, inefficient loops, and overly long method names.

=== Objectives & Requirements ===
1. Refactor the feedback_response_report Method

* Address the DRY violation by consolidating the containers for review rounds.
* Generalize the code to handle both cases—when rubrics vary by round and when they do not—without duplicating code.
* Introduce efficient data structures, like a 2D array, to replace multiple arrays and reduce memory usage.

2. Separate Responsibilities Using Visitor Pattern (stretch goal)

* Extract the email method using the Visitor pattern to modularize email functionality. Alternatively, select a design pattern better suited to organizing this method if available. Note that the email method is not properly used in its current location and is better suited to the Response class rather than ResponseMap.

3. Eliminate Redundant Methods

* Remove methods that do not serve a clear purpose and improve method naming for clarity.
* Aim to address any redundant meta-review functionality, as indicated by the professor's preference to remove these from response_map.rb.

4. Refactor for Code Clarity and Efficiency

* Improve variable names, reduce unnecessary loops, and replace long method names with concise, intuitive alternatives.
* Ensure that each method has a single, clearly defined purpose, improving code readability.

5. Testing and Documentation

* Write comprehensive tests for all newly implemented and modified methods to ensure reliability.
* Add detailed comments to facilitate code maintenance and understanding for future developers.

== Design ==

=== Design Principles ===

* Single Responsibility Principle (SRP): Each method and class should have a single, well-defined purpose.
* Don’t Repeat Yourself (DRY): Eliminate redundancy by creating general solutions that handle multiple scenarios.
* Ruby Readability Guidelines (Week 9 Notes):
** Guideline: Variable names should be neither too short nor too long.
** Guideline: Names should not be redundant.
** Guideline: A method should do only one thing and do it well.
* Visitor Pattern: Utilize this pattern to separate emailing functionalities from the main class.

=== Implementation Plan ===

The refactoring will proceed as follows:

1. Analyze and Refactor Current Code Structure

* Review and understand the existing structure and dependencies within feedback_response_map.rb.
* Identify areas of redundancy, complexity, and inefficiency, particularly in feedback_response_report, to create a clear plan for refactoring.
* Try to reduce character count and improve readability with aliasing (this way we do not break any code that relies on being able to call specific methods).

2. Refactor the feedback_response_report Method

* Consolidate containers for each review round to address DRY violations. By using a single structure to store review data, we will eliminate hard-coded repetition.
* Generalize logic to accommodate both scenarios where rubrics vary by round and where they do not, without duplicating code paths.
* Replace inefficient structures, such as multiple arrays, with more flexible and memory-efficient options, like a 2D array or a hash, to reduce memory usage and improve scalability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

* Extract frequently used or complex code blocks into helper methods, reducing the size of primary methods and enhancing reusability.
* Use helper methods for specific actions, like handling rounds or retrieving assignment data, to make the code cleaner and better organized.
* Emphasis on adhering to the guideline: A method should do only one thing and do it well.

4. Research Future Refactoring for email Method

* The email method is convoluted and the functionality should be refactored into a different class in the future.
* This is because this visitor pattern violation is present in many classes, and is beyond the scope of a one-class re-implementation.

5. Improve Variable Naming and Structure

* Replace ambiguous variable names with clearer alternatives that convey purpose, such as renaming @temp_review_responses and @temp_response_map_ids to more meaningful names.
* Simplify long method names to make the code more readable and approachable for new contributors.

=== Implementation ===

1. Analyze and Refactor Current Code Structure

Before refactoring, the FeedbackResponseMap class contains 6 methods, with the majority of the code in self.feedback_response_report:

[[File:FeedbackResponseMap_before.png |250px]]

We aim to change that by splitting up this method into three helper methods, as seen in the following:

[[File:FeedbackResponseMap_after.png |350px]]

To go into more detail, here is the code for the feedback_response_report method, and how we intend to split it up:

[[File:E2451_after_code1.png |600px]]

[[File:E2451_after_code2.png |600px]]

The red section of code will be self.get_feedback_authors, yellow will be self.varying_rubrics_report, and green will be self.static_rubrics_report. Each separated group will be its own method, and self.varying_rubrics_report and self.static_rubrics_report (the yellow and green methods) will be returned at the end of the new feedback_response_report.

2. Refactor the feedback_response_report Method

The following are the original arrays used to statically represent the review rounds.

[[File:E2451-OriginalArrayRounds.png]]

We can take these multiple arrays, and use dictionaries instead, where each round is called by its key value (integer value).

[[File:E2451-UpdatedArraysMain.png | 600px]]

The code found in the feedback_response_report method that use the arrays were moved to the two helper methods, seen as follows:

[[File:E2451-UpdatedArrays1.png | 600px]]

[[File:E2451-UpdatedArrays2.png | 600px]]

Additionally, Rubocop was used to analyze the code and adhere to proper Ruby Guidelines. The command below was used to search for any code smells that we missed.

rubocop app/models/feedback_response_map.rb

Originally, there were only three offenses, but this largely grew as we continued to refactor the code. All of the offenses can be seen below:

[[File:E2451-Rubocop1.png | 600px]]

[[File:E2451-Rubocop2.png | 600px]]

[[File:E2451-Rubocop3.png | 600px]]

[[File:E2451-Rubocop4.png | 600px]]

All of these offenses were fixed. The following three offenses were the original ones. For the first and third offenses, the colon after the method headers were simply removed. For the second offense, the “return” keyword caused errors, thus, it was removed, because a ruby method will return its last statement. The two other private methods containing “return” also had that keyword removed.

[[File:E2451-RubocopOriginal.png | 600px]]

Lastly, commenting was added throughout the files, to improve readability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

As planned in step 1, the feedback_response_report method was split up into 3 private helper methods: get_feedback_authors(id), varying_rubrics_report(review_responses, response_map_ids), and static_rubrics_report(review_responses, response_map_ids). One change we made that was different from the UML diagram was the addition of an id parameter in the get_feedback_authors method, in order to access id, since it was a parameter given to feedback_response_report. Each helper method was planned in order to stick to the guideline of “A method should do only one thing and do it well.”

Final UML for FeedbackResponseMap

[[File:E2451_FeedbackResponseMap_final.drawio.png | 600px]]

Authors

This image contains comments showing what the implementation looked like before:

[[File:E2451_authors_before_1.png]]

This image shows the construction of the private method we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_authors_after_1.png]]

Report

This image contains comments showing what the implementation looked like before (this image is out of date, the return functionality for the varying rubric report rounds has since been generalized, please see the repo for the updated version) (The updated version does not include the old version comments, which is why this screenshot is used):

[[File:E2451_reports_before_1.png]]

These images show the construction of the private methods we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_reports_varying_1.png]]

[[File:E2451_report_static_1.png]]

Notice that in both the original self.feedback_response_report method and the private methods, comments are included to explain each non-obvious step of the process.

Complexity changes

Previously, Rubocop reported the following failures on behalf of the self.feedback_response_report method:

Metrics/PerceivedComplexity: Perceived complexity for feedback_response_report is too high. [14/8]
Metrics/CyclomaticComplexity: Cyclomatic complexity for feedback_response_report is too high. [12/7]
Metrics/AbcSize: Assignment Branch Condition size for feedback_response_report is too high. [<14, 46, 16> 50.68/20]

Now, neither self.feedback_response_report nor any of its associated private methods trigger any of these Metric violations!
(Note that the email method does trigger a AbcSize violation when the protective comments are removed, but adjusting that method is beyond the scope of this project for reasons listed in the Implementation Plan)

4. Research Future Refactoring for email Method

As discussed in the implementation plan, the email method was left as is. Any changes would require the addition of a new class and/or major refactoring for the functionality.

5. Improve Variable Naming and Structure

The two sets of variables discussed in the plan, @temp_response_map_ids and @temp_review_responses were modified as needed. First, the @temp_response_map_ids was moved to the helper methods varying_rubrics_report and static_rubrics_report, to be initialized, and changed to response_map_ids.

Secondly, @temp_review_responses was changed to review_responses in the helper methods that call it: varying_rubrics_report and static_rubrics_report

=== Testing ===

1. Adapt Existing Tests for Refactored Methods

* Any new helper methods will be private, and so by the "Magic Tricks of Testing" guide, should not be tested (both query and command messages sent to self are ignored in the test plan).
* Use mocks to isolate components during testing, especially for external dependencies like Mailer, to ensure that email functionality works as expected without direct integration.

2. Document Code for Clarity

* Write detailed comments explaining the purpose of each method, input and output, and any critical logic that might be complex for future developers to understand.
* Create or update documentation and diagrams to illustrate the newly designed structure, making it easier for new developers to contribute or modify functionality.

=== Documentation ===

Ensure all code is well-documented, with comments explaining purpose, inputs, outputs, and any complex logic. Maintain updated documentation for all modified and newly added classes and methods, allowing for ease of understanding and maintenance.

=== Files ===

The files that were added or modified to our repository are shown below.

==== Models ====

The following files were copied from the expertiza/expertiza repository:
* analytic/assignment_team_analytic.rb
* assignment_team.rb
* feedback_response_map.rb

Added assignment_team.rb and assignment_team_analytic.rb as the existing spec tests depended on those 2 files. No changes were made to these files other than commenting out include Scoring in assignment_team.rb

feedback_response_map.rb

Many comments were placed throughout the document in order to make code more readable.

The main changes were taking feedback_response_report method and scanning it, to find different functionalities that could be taken out of it and turned into the following private helper methods: get_feedback_authors, varying_rubrics_report, static_rubrics_report.

Additionally, the variable @temp_response_map_ids was changed into response_map_ids both inside and outside the helper methods that used this variable. The variable @temp_review_responses was not changed except for being called review_responses in the helper methods.

==== Database ====

migrate/20241203083135_add_missing_reponse_map_fields.rb

One class is added, called AddMissingResponseMapFields, with a change of adding columns to response_maps and type and calibrate_to.

db/schema.rb

The only things changed in this file were a version change, as well as the addition of a t.string of "type" and a t.integer of "calibrate_to".

==== Spec ====

factories.rb

This file was modified to use single quotation marks instead of double quotation marks to adhere to RuboCop.

factories/factories.rb

We populated the factory with necessary factories such as response, course, institution, and role, as well as fixing the factory formatting to function properly.

feedback_response_map.rb

The code was updated to adhere to RuboCop guidelines. Secondly, tests and parts of tests were commented out if they were reliant on functionality that was not yet implemented in reimplementation-back-end.

=== Video ===

https://youtu.be/SbmDoJNm4Q4

=== Pull Request ===

https://github.com/expertiza/reimplementation-back-end/pull/144

=== Conclusion ===

By refactoring feedback_response_map.rb, this project enhances Expertiza’s backend maintainability and readability, ensuring a modular, efficient, and more secure implementation.

== Team Information ==

=== Mentor ===

* Chaitanya Srusti (crsrusti@ncsu.edu)

=== Members ===

* Sarah Daniel (sdaniel8@ncsu.edu)

* William Grochocinski (wagrocho@ncsu.edu)

* Tipton Middleton (tgmiddl2@ncsu.edu)

* ChatGPT (Honorary Member)

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-12-04T03:17:29Z

Wagrocho: Fixed uneven equals in Video header

This page contains the details of OSS project ''E2451: Reimplement feedback response map'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions, among other tasks. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

=== Project Overview ===

The goal of this project is to refactor the feedback_response_map.rb file from the Expertiza repository and integrate it into the reimplementation-back-end repository. Within Expertiza, when a user submits a review, an instance of the Response class is created, associated with a ResponseMap. Each ResponseMap links a reviewer (reviewer_id), reviewee (reviewee_id), and the reviewed item (reviewed_object_id). FeedbackResponseMap, a subclass of ResponseMap, represents the feedback provided by a reviewee on the feedback received for their submission.

This class has significant room for improvement, especially with respect to object-oriented principles. Refactoring feedback_response_map.rb will streamline functionality, enhance maintainability, and improve adherence to coding standards.

=== Current Implementation ===

The current feedback_response_map.rb in the Expertiza repository has several issues. It includes the following problems:

* Poor adherence to SOLID and DRY principles: The current code structure introduces unnecessary repetition and complexity.
* feedback_response_report Method Issues: This critical method is highly complex, relying on custom data structures and separate containers for each review round, resulting in a DRY violation.
* Improper Responsibility Assignment: The email method does not belong within this class and would benefit from refactoring out into a separate class using the Visitor pattern. This pattern is suggested to streamline functionality, though alternative design patterns may be considered if more suitable.
* Memory Inefficiencies: The method currently creates unnecessary memory through inefficient structures, including multiple separate arrays for different rounds of review, which could be simplified into a 2D array structure.
* Code Smells: The code has redundant methods, unclear variable names, inefficient loops, and overly long method names.

=== Objectives & Requirements ===
1. Refactor the feedback_response_report Method

* Address the DRY violation by consolidating the containers for review rounds.
* Generalize the code to handle both cases—when rubrics vary by round and when they do not—without duplicating code.
* Introduce efficient data structures, like a 2D array, to replace multiple arrays and reduce memory usage.

2. Separate Responsibilities Using Visitor Pattern (stretch goal)

* Extract the email method using the Visitor pattern to modularize email functionality. Alternatively, select a design pattern better suited to organizing this method if available. Note that the email method is not properly used in its current location and is better suited to the Response class rather than ResponseMap.

3. Eliminate Redundant Methods

* Remove methods that do not serve a clear purpose and improve method naming for clarity.
* Aim to address any redundant meta-review functionality, as indicated by the professor's preference to remove these from response_map.rb.

4. Refactor for Code Clarity and Efficiency

* Improve variable names, reduce unnecessary loops, and replace long method names with concise, intuitive alternatives.
* Ensure that each method has a single, clearly defined purpose, improving code readability.

5. Testing and Documentation

* Write comprehensive tests for all newly implemented and modified methods to ensure reliability.
* Add detailed comments to facilitate code maintenance and understanding for future developers.

== Design ==

=== Design Principles ===

* Single Responsibility Principle (SRP): Each method and class should have a single, well-defined purpose.
* Don’t Repeat Yourself (DRY): Eliminate redundancy by creating general solutions that handle multiple scenarios.
* Ruby Readability Guidelines (Week 9 Notes):
** Guideline: Variable names should be neither too short nor too long.
** Guideline: Names should not be redundant.
** Guideline: A method should do only one thing and do it well.
* Visitor Pattern: Utilize this pattern to separate emailing functionalities from the main class.

=== Implementation Plan ===

The refactoring will proceed as follows:

1. Analyze and Refactor Current Code Structure

* Review and understand the existing structure and dependencies within feedback_response_map.rb.
* Identify areas of redundancy, complexity, and inefficiency, particularly in feedback_response_report, to create a clear plan for refactoring.
* Try to reduce character count and improve readability with aliasing (this way we do not break any code that relies on being able to call specific methods).

2. Refactor the feedback_response_report Method

* Consolidate containers for each review round to address DRY violations. By using a single structure to store review data, we will eliminate hard-coded repetition.
* Generalize logic to accommodate both scenarios where rubrics vary by round and where they do not, without duplicating code paths.
* Replace inefficient structures, such as multiple arrays, with more flexible and memory-efficient options, like a 2D array or a hash, to reduce memory usage and improve scalability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

* Extract frequently used or complex code blocks into helper methods, reducing the size of primary methods and enhancing reusability.
* Use helper methods for specific actions, like handling rounds or retrieving assignment data, to make the code cleaner and better organized.
* Emphasis on adhering to the guideline: A method should do only one thing and do it well.

4. Research Future Refactoring for email Method

* The email method is convoluted and the functionality should be refactored into a different class in the future.
* This is because this visitor pattern violation is present in many classes, and is beyond the scope of a one-class re-implementation.

5. Improve Variable Naming and Structure

* Replace ambiguous variable names with clearer alternatives that convey purpose, such as renaming @temp_review_responses and @temp_response_map_ids to more meaningful names.
* Simplify long method names to make the code more readable and approachable for new contributors.

=== Implementation ===

1. Analyze and Refactor Current Code Structure

Before refactoring, the FeedbackResponseMap class contains 6 methods, with the majority of the code in self.feedback_response_report:

[[File:FeedbackResponseMap_before.png |250px]]

We aim to change that by splitting up this method into three helper methods, as seen in the following:

[[File:FeedbackResponseMap_after.png |350px]]

To go into more detail, here is the code for the feedback_response_report method, and how we intend to split it up:

[[File:E2451_after_code1.png |600px]]

[[File:E2451_after_code2.png |600px]]

The red section of code will be self.get_feedback_authors, yellow will be self.varying_rubrics_report, and green will be self.static_rubrics_report. Each separated group will be its own method, and self.varying_rubrics_report and self.static_rubrics_report (the yellow and green methods) will be returned at the end of the new feedback_response_report.

2. Refactor the feedback_response_report Method

The following are the original arrays used to statically represent the review rounds.

[[File:E2451-OriginalArrayRounds.png]]

We can take these multiple arrays, and use dictionaries instead, where each round is called by its key value (integer value).

[[File:E2451-UpdatedArraysMain.png | 600px]]

The code found in the feedback_response_report method that use the arrays were moved to the two helper methods, seen as follows:

[[File:E2451-UpdatedArrays1.png | 600px]]

[[File:E2451-UpdatedArrays2.png | 600px]]

Additionally, Rubocop was used to analyze the code and adhere to proper Ruby Guidelines. The command below was used to search for any code smells that we missed.

rubocop app/models/feedback_response_map.rb

Originally, there were only three offenses, but this largely grew as we continued to refactor the code. All of the offenses can be seen below:

[[File:E2451-Rubocop1.png | 600px]]

[[File:E2451-Rubocop2.png | 600px]]

[[File:E2451-Rubocop3.png | 600px]]

[[File:E2451-Rubocop4.png | 600px]]

All of these offenses were fixed. The following three offenses were the original ones. For the first and third offenses, the colon after the method headers were simply removed. For the second offense, the “return” keyword caused errors, thus, it was removed, because a ruby method will return its last statement. The two other private methods containing “return” also had that keyword removed.

[[File:E2451-RubocopOriginal.png | 600px]]

Lastly, commenting was added throughout the files, to improve readability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

As planned in step 1, the feedback_response_report method was split up into 3 private helper methods: get_feedback_authors(id), varying_rubrics_report(review_responses, response_map_ids), and static_rubrics_report(review_responses, response_map_ids). One change we made that was different from the UML diagram was the addition of an id parameter in the get_feedback_authors method, in order to access id, since it was a parameter given to feedback_response_report. Each helper method was planned in order to stick to the guideline of “A method should do only one thing and do it well.”

Final UML for FeedbackResponseMap

[[File:E2451_FeedbackResponseMap_final.drawio.png | 600px]]

Authors

This image contains comments showing what the implementation looked like before:

[[File:E2451_authors_before_1.png]]

This image shows the construction of the private method we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_authors_after_1.png]]

Report

This image contains comments showing what the implementation looked like before (this image is out of date, the return functionality for the varying rubric report rounds has since been generalized, please see the repo for the updated version) (The updated version does not include the old version comments, which is why this screenshot is used):

[[File:E2451_reports_before_1.png]]

These images show the construction of the private methods we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_reports_varying_1.png]]

[[File:E2451_report_static_1.png]]

Notice that in both the original self.feedback_response_report method and the private methods, comments are included to explain each non-obvious step of the process.

Complexity changes

Previously, Rubocop reported the following failures on behalf of the self.feedback_response_report method:

Metrics/PerceivedComplexity: Perceived complexity for feedback_response_report is too high. [14/8]
Metrics/CyclomaticComplexity: Cyclomatic complexity for feedback_response_report is too high. [12/7]
Metrics/AbcSize: Assignment Branch Condition size for feedback_response_report is too high. [<14, 46, 16> 50.68/20]

Now, neither self.feedback_response_report nor any of its associated private methods trigger any of these Metric violations!
(Note that the email method does trigger a AbcSize violation when the protective comments are removed, but adjusting that method is beyond the scope of this project for reasons listed in the Implementation Plan)

4. Research Future Refactoring for email Method

As discussed in the implementation plan, the email method was left as is. Any changes would require the addition of a new class and/or major refactoring for the functionality.

5. Improve Variable Naming and Structure

The two sets of variables discussed in the plan, @temp_response_map_ids and @temp_review_responses were modified as needed. First, the @temp_response_map_ids was moved to the helper methods varying_rubrics_report and static_rubrics_report, to be initialized, and changed to response_map_ids.

Secondly, @temp_review_responses was changed to review_responses in the helper methods that call it: varying_rubrics_report and static_rubrics_report

=== Testing ===

1. Adapt Existing Tests for Refactored Methods

* Any new helper methods will be private, and so by the "Magic Tricks of Testing" guide, should not be tested (both query and command messages sent to self are ignored in the test plan).
* Use mocks to isolate components during testing, especially for external dependencies like Mailer, to ensure that email functionality works as expected without direct integration.

2. Document Code for Clarity

* Write detailed comments explaining the purpose of each method, input and output, and any critical logic that might be complex for future developers to understand.
* Create or update documentation and diagrams to illustrate the newly designed structure, making it easier for new developers to contribute or modify functionality.

=== Documentation ===

Ensure all code is well-documented, with comments explaining purpose, inputs, outputs, and any complex logic. Maintain updated documentation for all modified and newly added classes and methods, allowing for ease of understanding and maintenance.

=== Video ===

https://youtu.be/SbmDoJNm4Q4

=== Conclusion ===

By refactoring feedback_response_map.rb, this project will enhance Expertiza’s backend maintainability and readability, ensuring a modular, efficient, and more secure implementation.

== Team Information ==

=== Mentor ===

* Chaitanya Srusti (crsrusti@ncsu.edu)

=== Members ===

* Sarah Daniel (sdaniel8@ncsu.edu)

* William Grochocinski (wagrocho@ncsu.edu)

* Tipton Middleton (tgmiddl2@ncsu.edu)

* ChatGPT (Honorary Member)

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-12-04T03:16:54Z

Wagrocho: Added video section

This page contains the details of OSS project ''E2451: Reimplement feedback response map'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions, among other tasks. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

=== Project Overview ===

The goal of this project is to refactor the feedback_response_map.rb file from the Expertiza repository and integrate it into the reimplementation-back-end repository. Within Expertiza, when a user submits a review, an instance of the Response class is created, associated with a ResponseMap. Each ResponseMap links a reviewer (reviewer_id), reviewee (reviewee_id), and the reviewed item (reviewed_object_id). FeedbackResponseMap, a subclass of ResponseMap, represents the feedback provided by a reviewee on the feedback received for their submission.

This class has significant room for improvement, especially with respect to object-oriented principles. Refactoring feedback_response_map.rb will streamline functionality, enhance maintainability, and improve adherence to coding standards.

=== Current Implementation ===

The current feedback_response_map.rb in the Expertiza repository has several issues. It includes the following problems:

* Poor adherence to SOLID and DRY principles: The current code structure introduces unnecessary repetition and complexity.
* feedback_response_report Method Issues: This critical method is highly complex, relying on custom data structures and separate containers for each review round, resulting in a DRY violation.
* Improper Responsibility Assignment: The email method does not belong within this class and would benefit from refactoring out into a separate class using the Visitor pattern. This pattern is suggested to streamline functionality, though alternative design patterns may be considered if more suitable.
* Memory Inefficiencies: The method currently creates unnecessary memory through inefficient structures, including multiple separate arrays for different rounds of review, which could be simplified into a 2D array structure.
* Code Smells: The code has redundant methods, unclear variable names, inefficient loops, and overly long method names.

=== Objectives & Requirements ===
1. Refactor the feedback_response_report Method

* Address the DRY violation by consolidating the containers for review rounds.
* Generalize the code to handle both cases—when rubrics vary by round and when they do not—without duplicating code.
* Introduce efficient data structures, like a 2D array, to replace multiple arrays and reduce memory usage.

2. Separate Responsibilities Using Visitor Pattern (stretch goal)

* Extract the email method using the Visitor pattern to modularize email functionality. Alternatively, select a design pattern better suited to organizing this method if available. Note that the email method is not properly used in its current location and is better suited to the Response class rather than ResponseMap.

3. Eliminate Redundant Methods

* Remove methods that do not serve a clear purpose and improve method naming for clarity.
* Aim to address any redundant meta-review functionality, as indicated by the professor's preference to remove these from response_map.rb.

4. Refactor for Code Clarity and Efficiency

* Improve variable names, reduce unnecessary loops, and replace long method names with concise, intuitive alternatives.
* Ensure that each method has a single, clearly defined purpose, improving code readability.

5. Testing and Documentation

* Write comprehensive tests for all newly implemented and modified methods to ensure reliability.
* Add detailed comments to facilitate code maintenance and understanding for future developers.

== Design ==

=== Design Principles ===

* Single Responsibility Principle (SRP): Each method and class should have a single, well-defined purpose.
* Don’t Repeat Yourself (DRY): Eliminate redundancy by creating general solutions that handle multiple scenarios.
* Ruby Readability Guidelines (Week 9 Notes):
** Guideline: Variable names should be neither too short nor too long.
** Guideline: Names should not be redundant.
** Guideline: A method should do only one thing and do it well.
* Visitor Pattern: Utilize this pattern to separate emailing functionalities from the main class.

=== Implementation Plan ===

The refactoring will proceed as follows:

1. Analyze and Refactor Current Code Structure

* Review and understand the existing structure and dependencies within feedback_response_map.rb.
* Identify areas of redundancy, complexity, and inefficiency, particularly in feedback_response_report, to create a clear plan for refactoring.
* Try to reduce character count and improve readability with aliasing (this way we do not break any code that relies on being able to call specific methods).

2. Refactor the feedback_response_report Method

* Consolidate containers for each review round to address DRY violations. By using a single structure to store review data, we will eliminate hard-coded repetition.
* Generalize logic to accommodate both scenarios where rubrics vary by round and where they do not, without duplicating code paths.
* Replace inefficient structures, such as multiple arrays, with more flexible and memory-efficient options, like a 2D array or a hash, to reduce memory usage and improve scalability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

* Extract frequently used or complex code blocks into helper methods, reducing the size of primary methods and enhancing reusability.
* Use helper methods for specific actions, like handling rounds or retrieving assignment data, to make the code cleaner and better organized.
* Emphasis on adhering to the guideline: A method should do only one thing and do it well.

4. Research Future Refactoring for email Method

* The email method is convoluted and the functionality should be refactored into a different class in the future.
* This is because this visitor pattern violation is present in many classes, and is beyond the scope of a one-class re-implementation.

5. Improve Variable Naming and Structure

* Replace ambiguous variable names with clearer alternatives that convey purpose, such as renaming @temp_review_responses and @temp_response_map_ids to more meaningful names.
* Simplify long method names to make the code more readable and approachable for new contributors.

=== Implementation ===

1. Analyze and Refactor Current Code Structure

Before refactoring, the FeedbackResponseMap class contains 6 methods, with the majority of the code in self.feedback_response_report:

[[File:FeedbackResponseMap_before.png |250px]]

We aim to change that by splitting up this method into three helper methods, as seen in the following:

[[File:FeedbackResponseMap_after.png |350px]]

To go into more detail, here is the code for the feedback_response_report method, and how we intend to split it up:

[[File:E2451_after_code1.png |600px]]

[[File:E2451_after_code2.png |600px]]

The red section of code will be self.get_feedback_authors, yellow will be self.varying_rubrics_report, and green will be self.static_rubrics_report. Each separated group will be its own method, and self.varying_rubrics_report and self.static_rubrics_report (the yellow and green methods) will be returned at the end of the new feedback_response_report.

2. Refactor the feedback_response_report Method

The following are the original arrays used to statically represent the review rounds.

[[File:E2451-OriginalArrayRounds.png]]

We can take these multiple arrays, and use dictionaries instead, where each round is called by its key value (integer value).

[[File:E2451-UpdatedArraysMain.png | 600px]]

The code found in the feedback_response_report method that use the arrays were moved to the two helper methods, seen as follows:

[[File:E2451-UpdatedArrays1.png | 600px]]

[[File:E2451-UpdatedArrays2.png | 600px]]

Additionally, Rubocop was used to analyze the code and adhere to proper Ruby Guidelines. The command below was used to search for any code smells that we missed.

rubocop app/models/feedback_response_map.rb

Originally, there were only three offenses, but this largely grew as we continued to refactor the code. All of the offenses can be seen below:

[[File:E2451-Rubocop1.png | 600px]]

[[File:E2451-Rubocop2.png | 600px]]

[[File:E2451-Rubocop3.png | 600px]]

[[File:E2451-Rubocop4.png | 600px]]

All of these offenses were fixed. The following three offenses were the original ones. For the first and third offenses, the colon after the method headers were simply removed. For the second offense, the “return” keyword caused errors, thus, it was removed, because a ruby method will return its last statement. The two other private methods containing “return” also had that keyword removed.

[[File:E2451-RubocopOriginal.png | 600px]]

Lastly, commenting was added throughout the files, to improve readability.

3. Introduce Helper Methods for Reusable Logic (for feedback_response_report)

As planned in step 1, the feedback_response_report method was split up into 3 private helper methods: get_feedback_authors(id), varying_rubrics_report(review_responses, response_map_ids), and static_rubrics_report(review_responses, response_map_ids). One change we made that was different from the UML diagram was the addition of an id parameter in the get_feedback_authors method, in order to access id, since it was a parameter given to feedback_response_report. Each helper method was planned in order to stick to the guideline of “A method should do only one thing and do it well.”

Final UML for FeedbackResponseMap

[[File:E2451_FeedbackResponseMap_final.drawio.png | 600px]]

Authors

This image contains comments showing what the implementation looked like before:

[[File:E2451_authors_before_1.png]]

This image shows the construction of the private method we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_authors_after_1.png]]

Report

This image contains comments showing what the implementation looked like before (this image is out of date, the return functionality for the varying rubric report rounds has since been generalized, please see the repo for the updated version) (The updated version does not include the old version comments, which is why this screenshot is used):

[[File:E2451_reports_before_1.png]]

These images show the construction of the private methods we implemented to replace it, reducing complexity and improving readability in the process:

[[File:E2451_reports_varying_1.png]]

[[File:E2451_report_static_1.png]]

Notice that in both the original self.feedback_response_report method and the private methods, comments are included to explain each non-obvious step of the process.

Complexity changes

Previously, Rubocop reported the following failures on behalf of the self.feedback_response_report method:

Metrics/PerceivedComplexity: Perceived complexity for feedback_response_report is too high. [14/8]
Metrics/CyclomaticComplexity: Cyclomatic complexity for feedback_response_report is too high. [12/7]
Metrics/AbcSize: Assignment Branch Condition size for feedback_response_report is too high. [<14, 46, 16> 50.68/20]

Now, neither self.feedback_response_report nor any of its associated private methods trigger any of these Metric violations!
(Note that the email method does trigger a AbcSize violation when the protective comments are removed, but adjusting that method is beyond the scope of this project for reasons listed in the Implementation Plan)

4. Research Future Refactoring for email Method

As discussed in the implementation plan, the email method was left as is. Any changes would require the addition of a new class and/or major refactoring for the functionality.

5. Improve Variable Naming and Structure

The two sets of variables discussed in the plan, @temp_response_map_ids and @temp_review_responses were modified as needed. First, the @temp_response_map_ids was moved to the helper methods varying_rubrics_report and static_rubrics_report, to be initialized, and changed to response_map_ids.

Secondly, @temp_review_responses was changed to review_responses in the helper methods that call it: varying_rubrics_report and static_rubrics_report

=== Testing ===

1. Adapt Existing Tests for Refactored Methods

* Any new helper methods will be private, and so by the "Magic Tricks of Testing" guide, should not be tested (both query and command messages sent to self are ignored in the test plan).
* Use mocks to isolate components during testing, especially for external dependencies like Mailer, to ensure that email functionality works as expected without direct integration.

2. Document Code for Clarity

* Write detailed comments explaining the purpose of each method, input and output, and any critical logic that might be complex for future developers to understand.
* Create or update documentation and diagrams to illustrate the newly designed structure, making it easier for new developers to contribute or modify functionality.

=== Documentation ===

Ensure all code is well-documented, with comments explaining purpose, inputs, outputs, and any complex logic. Maintain updated documentation for all modified and newly added classes and methods, allowing for ease of understanding and maintenance.

=== Video ==

https://youtu.be/SbmDoJNm4Q4

=== Conclusion ===

By refactoring feedback_response_map.rb, this project will enhance Expertiza’s backend maintainability and readability, ensuring a modular, efficient, and more secure implementation.

== Team Information ==

=== Mentor ===

* Chaitanya Srusti (crsrusti@ncsu.edu)

=== Members ===

* Sarah Daniel (sdaniel8@ncsu.edu)

* William Grochocinski (wagrocho@ncsu.edu)

* Tipton Middleton (tgmiddl2@ncsu.edu)

* ChatGPT (Honorary Member)

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:34:32Z

Wagrocho: Removed inaccurate plans for the email method

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:31:39Z

Wagrocho: Rearranged list

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:28:15Z

Wagrocho: Bolded bullet points

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:27:06Z

Wagrocho: shifted bold to not cover colon

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:19:38Z

Wagrocho: Removed self-referential elements from the wiki

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:05:29Z

Wagrocho: Added ChatGPT as honorary member

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:05:10Z

Wagrocho: Revamped testing section

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T03:04:18Z

Wagrocho: Revamped implementation plan

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T02:57:11Z

Wagrocho: Added more information on emails

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T02:56:07Z

Wagrocho: Added information about the email method

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T02:50:21Z

Wagrocho: First draft (just writing words)

CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback response map.rb

2024-11-12T02:40:45Z

Wagrocho: Create empty page

bottom text

CSC/ECE 517 Fall 2024

2024-11-12T02:40:23Z

Wagrocho: Add E2451. Reimplement feedback_response_map.rb

* [[CSC/ECE 517 Fall 2024 - E2450. Refactor assignments_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2451. Reimplement feedback_response_map.rb]]
* [[CSC/ECE 517 Fall 2024 - E2452. Refactor review_mapping_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2453. Refactor review_mapping_helper.rb]]
* [[CSC/ECE 517 Fall 2024 - E2454. Refactor student_task.rb]]
* [[CSC/ECE 517 Fall 2024 - E2455. Refactor sign_up_sheet_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2456. Refactor teams_user.rb]]
* [[CSC/ECE 517 Fall 2024 - E2456. Refactor teams_user.rb (Phase 2 - Design Document)]]
* [[CSC/ECE 517 Fall 2024 - E2458. User management and users table]]
* [[CSC/ECE 517 Fall 2024 - E2459. View for results of bidding]]
* [[CSC/ECE 517 Fall 2024 - E2460 Mentor-Meeting Management]]
* [[CSC/ECE 517 Fall 2024 - E2461. UI for Courses]]
* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2462._UI_for_Questionnaires CSC/ECE 517 Fall 2024 - E2462. UI for Questionnaire.rb]
* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2463_Implement_Front_End_for_Student_Task_List CSC/ECE 517 Fall 2024 - E2463. UI for Student Task List]
* [[CSC/ECE 517 Fall 2024 - E2464 UI for Project Topics (was: Sign_up_Topics)]]
* [[CSC/ECE 517 Fall 2024 - E2465. UI for Institutions and Notification]]
* [[CSC/ECE 517 Fall 2024 - E2466. UI for Impersonate User]]
* [[CSC/ECE 517 Fall 2024 - E2467. UI for View Submissions]]
* [[CSC/ECE 517 Fall 2024 - E2468. Reimplement due_date]]
* [[CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view_team]]
* [[CSC/ECE 517 Fall 2024 - E2470. Reimplement grades_controller]]
* [[CSC/ECE 517 Fall 2024 - E2471. Reimplement logger]]
* [[CSC/ECE 517 Fall 2024 - E2472. Reimplement responses_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2475. Reimplement student_task view]]
* [[CSC/ECE 517 Fall 2024 - E2478. Reimplement the Question hierarchy as Item hierarchy]]
* [[CSC/ECE 517 Fall 2024 - E2479. Reimplement teams_users_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller]]
* [[CSC/ECE 517 Fall 2024 - E2481 Reimplement response_map.rb]]
* [[CSC/ECE 517 Fall 2024 - E2482. Reimplement heatgrid for reviews]]
* [[CSC/ECE 517 Fall 2024 - E2483. Reimplement Notification Controller and Model]]
* [[CSC/ECE 517 Fall 2024 - E2484. Reimplement participants_controller.rb]]
* [[CSC/ECE 517 Fall 2024 - E2485. Allow reviewers to bid on what to review]]
* [[CSC/ECE 517 Fall 2024 - E2487. Reimplement authorization_helper.rb]]
* [[CSC/ECE 517 Fall 2024 - E2492. UI for View submissions/assign grades (except heatgrid)]]
* [[CSC/ECE 517 Fall 2024 - E2493. UI for Assign Reviewers]]
* [[CSC/ECE 517 Fall 2024 - G2401 Refactor Graphql API endpoint for contribution metrics]]
* [[CSC/ECE 517 Fall 2024 - G2402 Refactor Graphql API endpoint for repositories]]

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:59:39Z

Wagrocho: Split team members onto different lines

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|-
|7
|Added commented-out non-working previous implementation
|Added the previous (non-working) code that relied on the non-working app/helpers/authorization_helper.rb file (see below for notes). This was added so that in the future (when session[:user] hopefully works), action_allowed? can be easily switched over.
|[https://github.com/Grochocinski/expertiza-E2480/pull/14 Pull Request 14]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

== Team Information ==

Project Members:

Sarah Daniel (sdaniel8@ncsu.edu)

William Grochocinski (wagrocho@ncsu.edu)

Tipton Middleton (tgmiddl2@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:59:00Z

Wagrocho: Added Team Information

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|-
|7
|Added commented-out non-working previous implementation
|Added the previous (non-working) code that relied on the non-working app/helpers/authorization_helper.rb file (see below for notes). This was added so that in the future (when session[:user] hopefully works), action_allowed? can be easily switched over.
|[https://github.com/Grochocinski/expertiza-E2480/pull/14 Pull Request 14]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

== Team Information ==

Project Members:

Sarah Daniel (sdaniel8@ncsu.edu)
William Grochocinski (wagrocho@ncsu.edu)
Tipton Middleton (tgmiddl2@ncsu.edu)

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:55:45Z

Wagrocho: No longer jumps to E2424 problem statement header

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:53:41Z

Wagrocho: Added commas between subsequent pull requests

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|-
|7
|Added commented-out non-working previous implementation
|Added the previous (non-working) code that relied on the non-working app/helpers/authorization_helper.rb file (see below for notes). This was added so that in the future (when session[:user] hopefully works), action_allowed? can be easily switched over.
|[https://github.com/Grochocinski/expertiza-E2480/pull/14 Pull Request 14]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11], [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:51:05Z

Wagrocho: Added notes for PR14

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|-
|7
|Added commented-out non-working previous implementation
|Added the previous (non-working) code that relied on the non-working app/helpers/authorization_helper.rb file (see below for notes). This was added so that in the future (when session[:user] hopefully works), action_allowed? can be easily switched over.
|[https://github.com/Grochocinski/expertiza-E2480/pull/14 Pull Request 14]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:45:07Z

Wagrocho: Switched double brackets to single brackets

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:43:56Z

Wagrocho: Added stack overflow link

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is currently not implemented and not possible to implement in Expertiza/reimplementation-back-end as there is no login path (see [https://stackoverflow.com/questions/22451969/rspec-set-session-object this stack overflow post for more details]). Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:37:05Z

Wagrocho: Removed extra line break

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:36:42Z

Wagrocho: Added table entries for authorization_helper

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Copied over and fixed dependencies
|This was copied over and dependencies that did not exist in expertiza/reimplementation-back-end were adjusted so they lined up with files that did exist.
|[https://github.com/Grochocinski/expertiza-E2480/pull/2 Pull Request 2]
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:34:25Z

Wagrocho: Fixed the descriptions for seeds.rb

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Add checks for missing data
|The prior behavior of seeds.rb was to error out whenever it was called after seeding had already been done. This did not allow for tweaks to aspects of the seeds without dropping and completely rebuilding the entire database. The new behavior checks if each entry is already in the database. Any entry already in the database is skipped, while any entry that is missing is added. This ensures that all data in seeds.rb is in the database after it completes running and avoids raising errors for actions that shouldn't raise them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Now seeds all 5 user types
|Instead of seeding just an admin, all 5 user types are now seeded. This enabled testing of different user types as the user factory could not set the user role at this time.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Removed seeding for non-admins
|After user factories received the ability to set roles for users, there was no need to have them pre-seeded in the database since no test ever required more than two users. The seeded users in PR6 were removed and any tests requiring them now used the factories to create them.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:24:08Z

Wagrocho: Fixed missing User factory data

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:22:50Z

Wagrocho: Finished updating factories

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial Creation
|The bookmark rating factory was created to assist with the testing of bookmark ratings.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:20:13Z

Wagrocho: Updated factories through PR8

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Bookmarks require sign-up topics and each topic requires an assignment. In order for the functionality to be properly tested, an assignment factory needed to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|3
|Switched to Faker names
|In order to better reflect real-world bookmarks, Faker was used to generate fake URLs, titles, and descriptions rather than have them be static.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|Each bookmark belongs to a topic, which in turn belongs to an assignment, which in turn must belong to a course. In order for bookmarks to be created, a course factory needed to be made.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|-
|4
|Renamed from role.rb to roles.rb
|Factory names should be plural.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Renamed from topics.rb to sign_up_topics.rb
|This factory was renamed to better match the model it represents.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 8]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:12:21Z

Wagrocho: Updated factories with PR7 changes

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|-
|3
|Added ID Lookup and Name
|In addition to adding the role name to the factory, functionality was also added to look up the id of the student role (if it is in the database) rather than assume it will always be 5. This makes the factory more resilient to future changes.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|Changed default password, added role/institution lookup
|The default password was changed from 'password' to 'password123' to better match the default passwords already in use. Additionally, both the role and institution fields attempt to look up the default value for the 'Student' role and 'NCSU' institution respectively. This lack of hardcoding makes the factory more resilient to future database changes.
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:06:04Z

Wagrocho: Updated factories with PR6

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Added id field
|Since roles (and their subsequent access controls) are handled by id, an id field was added to the role to facilitate having multiple roles with different access levels.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T03:03:06Z

Wagrocho: Updated factories with information from PR4

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split bookmarks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the bookmark factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|-
|2
|Switch from Hardcoded IDs to Associations
|Instead of using hardcoded user_id and topic_ids, bookmarks now use user and topic associations. This is the preferred approach as it better handles situations where the specified ID does not exist in the associated table.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as users needed to be associated with an institution for them to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split join team requests out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the join team request factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each user needed to have a role assigned in order for the user to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Created initial factory
|Created an initial factory as each student task needed to be associated with a topic in order for the task to be created.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split student tasks out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the student task factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Split users out of singular factory file
|The standard RSpec file structure dictates that factories should be in their own file in /spec/factories/, but the user factory was originally in /spec/factories.rb.
|[[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]]
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.PNG |1000px]]

[[File:BookmarksController34To63Coverage.PNG |1000px]]

[[File:BookmarksController64To98Coverage.PNG |1000px]]

[[File:BookmarksController99To130Coverage.PNG |1000px]]

[[File:BookmarksController130To154Coverage.PNG |1000px]]

As we can see, many of the lines were executed 10 times or more. Also, many lines in the beginning were executed only once. However, substantial code is executed at least more than once.

See the summary of coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png |1000px]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png |1000px]]

As mentioned before, both files have 100% coverage, with an average of 20 hits (executions) per line for BookmarksController.rb.

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:44:32Z

Wagrocho: Added notes for auth helper

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Initial creation
|This helper file was created to facilitate the automatic login process. When called with a username and password, the system would try to login as that user and return the configuration header that needed to be send with each future CRUD request. If the password field is not provided, the helper attempts to use the default password. If the user is also left blank, an administrator login will be returned.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Removal of Admin Login
|After fully implementing the five separate users, we could not think of a use-case where we would want to log-in as an administrator by default since any user seeded in the DB could easily be loaded and logged in with. Due to this, we removed the internal login_admin functionality, thus requiring all calls to AuthenticationHelper to specify a user.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below, as well as number of times each line was executed:

[[File:BookmarksController1To33Coverage.png]]

[[File:BookmarksController34To63Coverage.png]]

[[File:BookmarksController64To98Coverage.png]]

[[File:BookmarksController99To130Coverage.png]]

[[File:BookmarksController130To154Coverage.png]]

See the coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png]]

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:35:44Z

Wagrocho: Updated spec_helper and rails_helper info

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Seed the database if it isn't already seeded
|After running into issues with the database not being seeded when it should be, rails_helper was modified to check if seeding has occurred and to seed it if that had not already been done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added SimpleCov configuration
|SimpleCov needs configuration files in spec_helper in order to load and be configured properly. Since SimpleCov was required for this project, this configuration information needed to be added to spec_helper.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below:

See the coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png]]

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:31:14Z

Wagrocho: Fixed description of spec_helper for PR4

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Load files in /spec/support/
|Files in /spec/support/ and its subfolders need to be loaded in for certain functionality to work. In particular, factory_bot.rb and authentication_helper.rb are found in this folder.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below:

See the coverage for both files below:

Bookmark.rb

[[File:BookmarkCoverageE2480.png]]

BookmarksController.rb

[[File:BookmarksControllerCoverageE2480.png]]

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:27:08Z

Wagrocho: Added ending characters to table

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below:

See the coverage for both files below:

Bookmark.rb

[[BookmarkCoverageE2480.png]]

BookmarksController.rb

[[BookmarksControllerCoverageE2480.png]]

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:25:51Z

Wagrocho: Added Models & Controllers Header

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

==== Models & Controllers ====

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below:

See the coverage for both files below:

Bookmark.rb

[[BookmarkCoverageE2480.png]]

BookmarksController.rb

[[BookmarksControllerCoverageE2480.png]]

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:22:53Z

Wagrocho: Alphabetized each section, deleted inaccurate statements

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

app/models/bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

app/controllers/api/v1/bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

app/helpers/authorization_helper.rb

This file was imported from the main Expertiza/Expertiza repo and functionality was added to integrate with the action_allowed? method to determine if users had valid privileges when trying to perform certain actions. However, the functionality in this file depends on session[:user], something that is not implemented in Expertiza/reimplementation-back-end. Due to this, this file was not used in this implementation, but the file and added functionality was kept for future use.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

app/models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

spec/requests/api/v1/bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

===== Spec Factories =====

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/institution.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/join_team_requests.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/roles.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/student_tasks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

spec/factories/users.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|
|
|
|}

==== Database files ====

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

Tests for both Bookmark_Controller.rb and Bookmark.rb both have 100% coverage! Previously, tests were not comprehensive, and tests would not run at all. We recreated all of the tests and made sure coverage was at least above 90% (as expected in the Requirements).

View the code for Bookmark_Controller.rb below:

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:12:04Z

Wagrocho: Fixed the descriptions for files that got deleted

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

===== Spec Factories =====

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

spec/factories/bookmarks.rb

spec/factories/institution.rb

spec/factories/join_team_requests.rb

spec/factories/role.rb

spec/factories/student_tasks.rb

spec/factories/topics.rb

spec/factories/users.rb

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

* spec/factories.rb - the factories in this file were split into their own factory files in spec/factories/
* spec/factories/factories.rb - this was an empty file, deleted to clean up the repo

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T02:10:14Z

Wagrocho: /* Spec files */

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Tests & Helpers ====

===== Spec Files =====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

===== Spec Helpers =====

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/support/authentication_helper.rb

===== Spec Factories =====

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

spec/factories/bookmarks.rb

spec/factories/institution.rb

spec/factories/join_team_requests.rb

spec/factories/role.rb

spec/factories/student_tasks.rb

spec/factories/topics.rb

spec/factories/users.rb

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4] in an attempt to clean up unused files:

* spec/factories.rb
* spec/factories/factories.rb

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T01:54:59Z

Wagrocho: Removed extra space

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Spec files ====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

===== Testing Factories =====

The following factories were created to facilitate the streamlined creation of bookmarks and users with different roles in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/factories/bookmarks.rb''
*''spec/factories/institution.rb''
*''spec/factories/join_team_requests.rb''
*''spec/factories/role.rb'': Added a line to make any new roles created, a Student, in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6]. Removed previously created lines, implemented finding or creating a Student's id (of 5), and sets the name to 'Student' in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7]
*''spec/factories/student_tasks.rb''
*''spec/factories/topics.rb''
*''spec/factories/users.rb'': Changed the password and added functionality to use existing Student roles or Institutions, or to create new ones if none exists, in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7].

===== Authentication functionality from Expertiza=====

The following were taken from the Expertiza repo and added into our repo for functionality purposes in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/support/authentication_helper.rb:'' Added checks to see if User, or Token are nil values in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6].

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4] in an attempt to clean up unused files:

* spec/factories.rb
* spec/factories/factories.rb

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T01:54:32Z

Wagrocho: Removed factories from things imported from Expertiza

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Spec files ====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

===== Testing Factories =====

The following factories were created to facilitate the streamlined creation of bookmarks and users with different roles in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/factories/bookmarks.rb''
*''spec/factories/institution.rb''
*''spec/factories/join_team_requests.rb''
*''spec/factories/role.rb'': Added a line to make any new roles created, a Student, in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6]. Removed previously created lines, implemented finding or creating a Student's id (of 5), and sets the name to 'Student' in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7]
*''spec/factories/student_tasks.rb''
*''spec/factories/topics.rb''
*''spec/factories/users.rb'': Changed the password and added functionality to use existing Student roles or Institutions, or to create new ones if none exists, in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7].

===== Authentication functionality from Expertiza=====

The following were taken from the Expertiza repo and added into our repo for functionality purposes in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/support/authentication_helper.rb:'' Added checks to see if User, or Token are nil values in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6].

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4] in an attempt to clean up unused files:

* spec/factories.rb
* spec/factories/factories.rb

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T01:46:53Z

Wagrocho: /* Miscellaneous Files */

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Spec files ====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

===== Authentication functionality from Expertiza=====

The following were taken from the Expertiza repo and added into our repo for functionality purposes in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/factories/bookmarks.rb''
*''spec/factories/institution.rb''
*''spec/factories/join_team_requests.rb''
*''spec/factories/role.rb'': Added a line to make any new roles created, a Student, in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6]. Removed previously created lines, implemented finding or creating a Student's id (of 5), and sets the name to 'Student' in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7]
*''spec/factories/student_tasks.rb''
*''spec/factories/topics.rb''
*''spec/factories/users.rb'': Changed the password and added functionality to use existing Student roles or Institutions, or to create new ones if none exists, in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7].
*''spec/support/authentication_helper.rb:'' Added checks to see if User, or Token are nil values in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6].

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4] in an attempt to clean up unused files:

* spec/factories.rb
* spec/factories/factories.rb

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-11-01T01:43:47Z

Wagrocho: /* Deleted Files */

This page contains the details of OSS project ''E2480: Implement testing for new Bookmarks Controller'' done for Expertiza in Fall 2024.

__TOC__

== Expertiza and Project Overview ==

=== Background ===

Expertiza is an open-source application used in CSC 517 (Object Oriented Design and Development) as a platform for creating teams, assigning programs, and reviewing submissions. Expertiza is also used to help students develop a working application in order to mimic how students will work on programs in the workplace.

A bookmark is a resource that a student can post for a certain topic, that other students may find useful if working on that topic. Students working on the topic have the ability to rate the bookmark based on usefulness, and using a rubric. The average of all ratings will be computed to get an average score.

As discussed in E2480's background, the BookmarksController is implemented with CRUD operations, as well as the ability to rate bookmarks, calculate average ratings, and check for proper authorization when accessing a Bookmark.

=== Prior Work and Related Projects ===

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Spring_2024_-_E2424._Reimplement_the_Bookmarks_Controller#Problem_Statement E2424 Reimplement the Bookmarks Controller]

* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1786_OSS_Project_Juniper:_Bookmark_enhancements E1786 Bookmark enhancements]

* [https://wiki.expertiza.ncsu.edu/index.php?title=E1915_Authorization_Utilities E1915 Authorization Utilities]

=== Requirements ===

There are four main requirements assigned for the project, seen as follows:

1. Add Tests and Generate API Documentation

* Develop comprehensive test cases for the BookmarksController to ensure the correctness of CRUD operations, bookmark ratings, and score calculations.
* The test coverage should aim to cover at least 90% of the code, ensuring thorough validation of edge cases and error handling.
* Utilize Swagger UI to generate API documentation for the controller and verify that routes are correctly defined.

2. Code Quality and Refactoring 

* Use tools like Rubocop and Code Climate to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods).
* Any unused or unclear functionality should be removed to improve maintainability.
* Rename methods with ambiguous names to improve clarity and ensure code follows the clean code principles.
* Review and optimize performance, particularly in areas where loops or methods can be refactored for better efficiency, such as handling the deletion of associated data (e.g., deleting all questions related to a questionnaire).

3. Authorization and Error Handling 

* Ensure proper enforcement of authorization rules and handle edge cases with informative error messages

4. Final Deliverables 

* Ensure that all tests pass and API documentation is fully generated using Swagger UI.
* Confirm that code coverage exceeds 90%, and there are no significant code smells or performance issues flagged by Rubocop and Code Climate.

==== Tasks ====

We can simplify the above requirements down to the following tasks:

* Create tests with at least 90% test coverage for BookmarksController
* Use Swagger UI to generate API documentation for the BookmarksController
* Fix and remove code smells, and refactor where necessary to optimize performance
* Implement authorization rules and handle edge cases using error messages that indicate what the error is

There are two more tasks (see details in ''Process --> Findings'' below) that were given, which can be summed up as the following:
* Create an action_allowed? method to see if a User has access to a Course, and if a Student has access to a Bookmark

== Process ==

=== Findings ===

Please note, the project repository was forked from reimplementation-back-end repository for Expertiza.

After searching through the repository, we noticed a few issues with the reimplementation-back-end that were not discussed in the OSS project details. After discussing with Dr. Gehringer and the TA, we decided on specific tasks to focus on during this project. One such issue was checking for if a user such as a TA, Instructor, or Admin has access to the bookmark, which is determined by if the user has access to the course that contains the assignment, which contains a topic, which then contains the bookmark.

"Access" for different user types (Students are omitted, as they are only allowed to modify/delete bookmarks they created) is defined as follows: TAs have access if there exists a TaMapping between them and the course the bookmark is under. Intructors have access if they are the instructor for the course the bookmark is under. Admins have access if they are the parent of (created) the instructor of the course the bookmark is under. Super Admins always have access.

Thus, the following additional tasks are expected in an action_allowed? method:

* Check to see if a User has access to a Course: The access a User (TA, Instructor, Admin) has to a Course is determined by the connection of Course to a Bookmark. A Course contains an Assignment, which contains a Topic, which then contains the Bookmark. Thus, if the user has access to a Course, they can access the Bookmark.
* Check to see if a Student has access to a Bookmark: This can be determined by checking to see if the Student had created the Bookmark. If so, then the Student can choose to edit or destroy the Bookmark.

=== New Changes ===

bookmark.rb

In the bookmark.rb file, the only change is to uncomment the line related to :topic. This way, we can identify which Users can identify Bookmarks.

bookmarks_controller.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added action_allowed? functionality
|Code was added to include the AuthorizationHelper, as well as run the action_allowed? method before the other methods run, so the User type can be identified.
|[https://github.com/Grochocinski/expertiza-E2480/pull/3 Pull Request 3]
|-
|2
|Added 'index' to a When case for Students
|Identified Students by additionally looking for an'index' parameter, and using just this and the 'list' parameters to determine if the User is a student.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|3
|Added 'show' and 'get_bookmark_rating_score' to a When case for Students
|Identified Students by looking for list, index, show, and get_bookmark_rating_score parameters. If the User is a Student, then the Student can view the bookmarks list.
|[https://github.com/Grochocinski/expertiza-E2480/pull/5 Pull Request 5]
|-
|4
|Added check_action_allowed method
|Making the before action as the new method check_action_allowed, which will pull up an Unauthorized access json file if action_allowed is false.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|5
|Changing the methods, and added a check_action_allowed
|Adding searching for a bookmark by id functionality, and if the bookmark is not found, a json page will be returned for the show, destroy, update, get_bookmark_rating_score, save_bookmark_rating_score. The check_allowed_action method will show a page if the user is allowed to perform the action. Code cleanup was also done.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|6
|Changing a couple of method calls, and adding conditions, as well as checking to see if a TaMapping exists
|Instead of a create method to create a bookmark rating, we call the new method with the same parameters, and call the save method. Also added a few conditionals to the 'when' blocks. Lastly, when the User is a TA, we can check to see if a TaMapping exists for the TA and a Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

authorization_helper.rb

This file is used to aid tests in logging in to different users. The action_allowed? method in bookmarks_controller.rb uses this file.

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Removed details from login_admin
|If there are no users in the database, there is something wrong, because there should always be an admin in the database
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

models/bookmark_rating.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a validates statement
|The new validates statement will check to see if a bookmark's rating is present for a BookmarkRating.
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|2
|Improving validates statement
|The validates statement now allows for only integers that are between 0 and 5.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

==== Spec files ====

bookmarks_controller_spec.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Added and cleaned up happy and sad tests for getting bookmarks
|Cleaned up tests, and added expected functionality for the tests. Some tests were incorrectly named, so that was fixed as well. Added happy and sad tests such as not letting someone without a token access list of bookmarks, and letting the user access the list of bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding User type by role_id and creating headers for signing in, and adding tests.
|Added new tests to check for specific users such as TA, Instructor, and Student. Also, added headers that will be used as tokens in order to authorize User login.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Creating test cases for each User type, and removes the header authentication in this file.
|Added better tests to check for all types of Users, and removed the original getting a student and also moved the headers functionality from the file. Header authentication is now done within each test.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|4
|Add specific test cases for Students, TAs, Admin, and Super Admin
|Added better tests to check for all types of Users, such as letting a specific User type access lists of bookmarks, allowing a specific User type to query existing and non-existing bookmarks and seeing the results. Also, Users who are not signed in cannot access the list of bookmarks, or query bookmarks. Lastly, adds a create_bookmark method to make a bookmark while finding or creating a corresponding User, Course, Assignment, and SignUpTopic. The method will also decide that if the bookmark does not exist based on these values, then create it.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|-
|5
|Adding specific test cases for BookmarkRatings
|Making test cases even more specific by adding test cases for all kinds of Users that may access BookmarkRatings. Also tests to see if BookmarkRatings can be accessed when a User is not logged in. Lastly, makes a make_bookmark_rating method that will create a bookmark if it doesn't exist, along with assigning a user to it (and creating a Student type if the user is nil).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|-
|6
|Adding tests for adding, updating, deleting a bookmark, as well as other tests.
|Tests were created for seeing the path of how a Bookmark is created, updated, and deleted. Tests were also created in querying Bookmark Ratings for all kinds of Users (as well as signed out users), to make sure non-existent bookmarks will not be shown. There was also additions of sad tests to make sure that Users that are not Students cannot make, or update bookmarks.
|[https://github.com/Grochocinski/expertiza-E2480/pull/10 Pull Request 10]
|-
|7
|Adding tests for adding, updating, and deleting a bookmark rating, as well as updating/deleting bookmarks for other Users.
|This PR adds happy and sad tests for functionality of adding, updating, and deleting bookmark ratings as a Student. Tests for adding, updating, and deleting Bookmarks by TA, Instructor, Admin, and SuperAdmin are also added. Lastly, functionality to look for a TA by role, and checking to see if a user is a TA is also added (and if a TA, then add the TA to the course).
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]
|}

spec/spec_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding SimpleCov functionality to specific files
|Making certain files (such as bookmarks_controller.rb and bookmark.rb) run to check coverage of the files.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/rails_helper.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Seed the database
|If there are no Users in the database, then add functionality to seed the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

spec/factories/sign_up_topics.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Topic
|Create Topics using factories, and assign an assignment id to each Topic.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/course.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Factory Course
|Create Course data using factories. Then get an Instructor from the database or create a new one. Then, use an existing institution or make a new Institution for each Course.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/assignment.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create a Assignment from factories
|Create Assignment data using factories. Then get an existing Instructor from the database or create a new one to add to each Assignment.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmarks.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmarks
|Create Bookmark data using factories. We can add random strings to the title and description, as well as search the database for an existing Student to assign the Bookmark to.
|[https://github.com/Grochocinski/expertiza-E2480/pull/8 Pull Request 8]
|}

spec/factories/bookmark_ratings.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Create Factory Bookmark Ratings
|Making data for bookmark ratings using Factory. Will make the bookmark and user null values (nil), and set a rating of 0).
|[https://github.com/Grochocinski/expertiza-E2480/pull/9 Pull Request 9]
|}

spec/factories/roles.rb

This file was renamed from spec/factories/role.rb to spec/factories/roles.rb (originally taken from Authentication functionality from Expertiza).

===== Authentication functionality from Expertiza=====

The following were taken from the Expertiza repo and added into our repo for functionality purposes in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4]:

*''spec/factories/bookmarks.rb''
*''spec/factories/institution.rb''
*''spec/factories/join_team_requests.rb''
*''spec/factories/role.rb'': Added a line to make any new roles created, a Student, in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6]. Removed previously created lines, implemented finding or creating a Student's id (of 5), and sets the name to 'Student' in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7]
*''spec/factories/student_tasks.rb''
*''spec/factories/topics.rb''
*''spec/factories/users.rb'': Changed the password and added functionality to use existing Student roles or Institutions, or to create new ones if none exists, in [https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request #7].
*''spec/support/authentication_helper.rb:'' Added checks to see if User, or Token are nil values in [https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request #6].

==== Database files ====

db/seeds.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Adding a role for the database
|Cleaned up the code, added useful comments, and added a role column for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|-
|2
|Finding and Creating a User by email
|Based on the email type, Users will be created as seeds for the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/6 Pull Request 6]
|-
|3
|Remove all Code except Admin find and creation
|Only admin values will be found or created (for testing purposes). All other users will not be created using seed. From now on, User's will be created by factories instead of seeded into the database.
|[https://github.com/Grochocinski/expertiza-E2480/pull/7 Pull Request 7]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|All usages of ta mappings throughout the reimplementation-back-end repository use ta_id, whereas the schema refers to it as user_id. This created problems when trying to use ta mappings, especially in tests. To fix this, instead of refactoring all instances of ta mappings to have their field referred to as user_id, we changed the schema to reflect the existing usage of ta_id, while still having it understand that the foreign key refers to users. We created a migration (seen below) that accomplishes this task.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/migrate/20241030195109_update_ta_mappings_table_structure.rb
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing ta_mappings references from user_id to ta_id
|Facilitates the changes made to the schema
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11] [https://github.com/Grochocinski/expertiza-E2480/pull/12 Pull Request 12]
|-
|}

db/schema.rb

{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Changing users to TAs
|Instead of "user_id", changed the value to ta_id. Also removing a foreign_key of mapping TA's to Users.
|[https://github.com/Grochocinski/expertiza-E2480/pull/11 Pull Request 11]

|}

==== Miscellaneous Files ====

bookmark_tester.sh
{| class="wikitable" style="width: 100%;
!  #  !! Change !! Rationale !! PR Link
|-
|1
|Trying to automate Bookmark testing
|Swagger tests must be manually run, so this file attempts to automate testing for the Bookmark.
|[https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request 4]
|}

==== Deleted Files ====

Two files regarding factories were deleted in [https://github.com/Grochocinski/expertiza-E2480/pull/4 Pull Request #4] in an attempt to clean up unused files:

* spec/factories.rb
* spec/factories/factories.rb

=== Rubocop ===

==== Why Rubocop ====

Rubocop was one of the tools listed in the project instructions, and so we used it "to assess code quality, remove code smells, and refactor any inefficient sections (e.g., redundant loops or methods)". We chose it in part because it was easy to apply to our system (simple CLI), and easy to make changes based on the feedback (provided line numbers and violation types).

==== How it was applied ====

We applied rubocop using simple one line commands based on what we wanted it to do. The general template we followed was:
rubocop [-A] ./spec/requests/api/v1/bookmarks_controller_spec.rb [--out ./spec/requests/<temporary file>.txt]
Where we would include
-A
If we wanted it to auto-correct any automatically correctable violations, and
--out ./spec/requests/<temporary file>.txt
If we wanted output to be delivered to a file for improved readability

==== What Changed ====

Lots of small violations like trailing whitespace, unnecessary blank lines, using " == nil" instead of ".nil?", and using double instead of single quotes were corrected automatically.

Some bigger violations like brace indent alignment and inner field indentation were also able to be fixed automatically, although many of those came about after manual fixes to other violations, like:

Line length violations were plentiful, most of them being caused by the long API commands. When we broke those down into their chunks, often times the `params:` argument would have its contents spread across multiple lines for readability (which caused some of the indent-related violations mentioned above). Other line length violations were on test descriptor lines (`it '<...>'`). The descriptors that triggered them covered complex tests, and so were intentionally detailed to inform future developers of what the test does, so shortening them was not ideal. These violations were resolved by splitting the descriptor across multiple lines.

Overall, the readability of the test file improved substantially!

==== What did not change, and why? ====

There were some violations that were intentionally not corrected to preserve readability and consistency:
* Block length violations were dismissed because adhering to them would undermine the structure of our test file. Our test file is laid out in segments defined by the `describe` blocks. At the uppermost level there is a describe block encapsulating all of the tests in the file. From there tests are divided by user type, this reduces redundancy in data preparation, improving test efficiency by having separate `before(:each)` blocks for each user. Within users, tests are further divided by API call type. This way it is easy to determine the location of a failing test, improving the speed of debugging. Because our structure relies on nested `describe` blocks, those at the uppermost levels are prone to triggering block length violations. With this in mind, we made the conscious decision to disable rubocop block length metrics with the following comments at the start and end of our test file respectively:
# rubocop:disable Metrics/BlockLength

# rubocop:enable Metrics/BlockLength

== Tests ==

Originally, tests were run using RSpec, but these created 13/13 Bookmarks controller tests failed. These tests were removed, and remade.

Swagger UI is a set of tools that is used by the Expertiza developers to run RSpec tests through an interface instead of the command line. Swagger was originally needed in order to view and run tests, because the RSpec tests for this project need to be fixed. However, since RSpec tests have been recreated, the use of Swagger will not be required to run tests, but only check for code smells and coverage.

=== Running RSpec tests via Swagger ===

Steps
* Build the containers
* Go to http://localhost:3002/api-docs
* Login via the Authentication block at the bottom (U: "admin", P: "password123")
* Copy the token in the response
* Scroll up to the top and click "Authorize"
* In the popup, paste in the token and hit "Authorize"
* Navigate to the test you want to run, edit the parameters, and run it

=== Test Coverage ===

=== Failing Tests ===

== Recommended next steps ==

* There are methods in the authorization_helper.rb that check to see if a TA or Instructor can access an assignment, that have some code smells such as bad method names.
* The questionnaire (which is used to rate the bookmark) needs the functionality of identifying a user type. Possibly create a mixin to implement this.

CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller

2024-10-28T23:01:05Z

Wagrocho: Added some placeholder text so the page would resolve

Scripts.com
Bee Movie
By Jerry Seinfeld

NARRATOR:
(Black screen with text; The sound of buzzing bees can be heard)
According to all known laws
of aviation,
:
there is no way a bee
should be able to fly.
:
Its wings are too small to get
its fat little body off the ground.
:
The bee, of course, flies anyway
:
because bees don't care
what humans think is impossible.
BARRY BENSON:
(Barry is picking out a shirt)
Yellow, black. Yellow, black.
Yellow, black. Yellow, black.
:
Ooh, black and yellow!
Let's shake it up a little.
JANET BENSON:
Barry! Breakfast is ready!
BARRY:
Coming!
:
Hang on a second.
(Barry uses his antenna like a phone)
:
Hello?
ADAM FLAYMAN:

(Through phone)
- Barry?
BARRY:
- Adam?
ADAM:
- Can you believe this is happening?
BARRY:
- I can't. I'll pick you up.
(Barry flies down the stairs)
:
MARTIN BENSON:
Looking sharp.
JANET:
Use the stairs. Your father
paid good money for those.
BARRY:
Sorry. I'm excited.
MARTIN:
Here's the graduate.
We're very proud of you, son.
:
A perfect report card, all B's.
JANET:
Very proud.
(Rubs Barry's hair)
BARRY=
Ma! I got a thing going here.
JANET:
- You got lint on your fuzz.
BARRY:
- Ow! That's me!

JANET:
- Wave to us! We'll be in row 118,000.
- Bye!
(Barry flies out the door)
JANET:
Barry, I told you,
stop flying in the house!
(Barry drives through the hive,and is waved at by Adam who is reading a
newspaper)
BARRY==
- Hey, Adam.
ADAM:
- Hey, Barry.
(Adam gets in Barry's car)
:
- Is that fuzz gel?
BARRY:
- A little. Special day, graduation.
ADAM:
Never thought I'd make it.
(Barry pulls away from the house and continues driving)
BARRY:
Three days grade school,
three days high school...
ADAM:
Those were awkward.
BARRY:
Three days college. I'm glad I took
a day and hitchhiked around the hive.
ADAM==
You did come back different.
(Barry and Adam pass by Artie, who is jogging)
ARTIE:
- Hi, Barry!

BARRY:
- Artie, growing a mustache? Looks good.
ADAM:
- Hear about Frankie?
BARRY:
- Yeah.
ADAM==
- You going to the funeral?
BARRY:
- No, I'm not going to his funeral.
:
Everybody knows,
sting someone, you die.
:
Don't waste it on a squirrel.
Such a hothead.
ADAM:
I guess he could have
just gotten out of the way.
(The car does a barrel roll on the loop-shaped bridge and lands on the
highway)
:
I love this incorporating
an amusement park into our regular day.
BARRY:
I guess that's why they say we don't need vacations.
(Barry parallel parks the car and together they fly over the graduating
students)
Boy, quite a bit of pomp...
under the circumstances.
(Barry and Adam sit down and put on their hats)
:
- Well, Adam, today we are men.

ADAM:
- We are!
BARRY=
- Bee-men.
=ADAM=
- Amen!
BARRY AND ADAM:
Hallelujah!
(Barry and Adam both have a happy spasm)
ANNOUNCER:
Students, faculty, distinguished bees,
:
please welcome Dean Buzzwell.
DEAN BUZZWELL:
Welcome, New Hive Oity
graduating class of...
:
...9:
:
That concludes our ceremonies.
:
And begins your career
at Honex Industries!
ADAM:
Will we pick our job today?
(Adam and Barry get into a tour bus)
BARRY=
I heard it's just orientation.
(Tour buses rise out of the ground and the students are automatically
loaded into the buses)
TOUR GUIDE:
Heads up! Here we go.

ANNOUNCER:
Keep your hands and antennas
inside the tram at all times.
BARRY:
- Wonder what it'll be like?
ADAM:
- A little scary.
TOUR GUIDE==
Welcome to Honex,
a division of Honesco
:
and a part of the Hexagon Group.
Barry:
This is it!
BARRY AND ADAM:
Wow.
BARRY:
Wow.
(The bus drives down a road an on either side are the Bee's massive
complicated Honey-making machines)
TOUR GUIDE:
We know that you, as a bee,
have worked your whole life
:
to get to the point where you
can work for your whole life.
:
Honey begins when our valiant Pollen
Jocks bring the nectar to the hive.
:
Our top-secret formula
:
is automatically color-corrected,

scent-adjusted and bubble-contoured
:
into this soothing sweet syrup
:
with its distinctive
golden glow you know as...
EVERYONE ON BUS:
Honey!
(The guide has been collecting honey into a bottle and she throws it into
the crowd on the bus and it is caught by a girl in the back)
ADAM:
- That girl was hot.
BARRY:
- She's my cousin!
ADAM==
- She is?
BARRY:
- Yes, we're all cousins.
ADAM:
- Right. You're right.
TOUR GUIDE:
- At Honex, we constantly strive
:
to improve every aspect
of bee existence.
:
These bees are stress-testing
a new helmet technology.
(The bus passes by a Bee wearing a helmet who is being smashed into the
ground with fly-swatters, newspapers and boots. He lifts a thumbs up but
you can hear him groan)
:
ADAM==

- What do you think he makes?
BARRY:
- Not enough.
TOUR GUIDE:
Here we have our latest advancement,
the Krelman.
(They pass by a turning wheel with Bees standing on pegs, who are each
wearing a finger-shaped hat)
Barry:
- Wow, What does that do?
TOUR GUIDE:
- Catches that little strand of honey
:
that hangs after you pour it.
Saves us millions.
ADAM:
(Intrigued)
Can anyone work on the Krelman?
TOUR GUIDE:
Of course. Most bee jobs are
small ones.
But bees know that every small job,
if it's done well, means a lot.
:
But choose carefully
:
because you'll stay in the job
you pick for the rest of your life.
(Everyone claps except for Barry)
BARRY:
The same job the rest of your life?
I didn't know that.
ADAM:

What's the difference?
TOUR GUIDE:
You'll be happy to know that bees,
as a species, haven't had one day off
:
in 27 million years.
BARRY:
(Upset)
So you'll just work us to death?
:
We'll sure try.
(Everyone on the bus laughs except Barry. Barry and Adam are walking back
home together)
ADAM:
Wow! That blew my mind!
BARRY:
"What's the difference?"
How can you say that?
:
One job forever?
That's an insane choice to have to make.
ADAM:
I'm relieved. Now we only have
to make one decision in life.
BARRY:
But, Adam, how could they
never have told us that?
ADAM:
Why would you question anything?
We're bees.
:
We're the most perfectly
functioning society on Earth.

BARRY:
You ever think maybe things
work a little too well here?
ADAM:
Like what? Give me one example.
(Barry and Adam stop walking and it is revealed to the audience that
hundreds of cars are speeding by and narrowly missing them in perfect
unison)
BARRY:
I don't know. But you know
what I'm talking about.
ANNOUNCER:
Please clear the gate.
Royal Nectar Force on approach.
BARRY:
Wait a second. Check it out.
(The Pollen jocks fly in, circle around and landing in line)
:
- Hey, those are Pollen Jocks!
ADAM:
- Wow.
:
I've never seen them this close.
BARRY:
They know what it's like
outside the hive.
ADAM:
Yeah, but some don't come back.
GIRL BEES:
- Hey, Jocks!
- Hi, Jocks!
(The Pollen Jocks hook up their backpacks to machines that pump the nectar
to trucks, which drive away)

LOU LO DUVA:
You guys did great!
:
You're monsters!
You're sky freaks!
I love it!
(Punching the Pollen Jocks in joy)
I love it!
ADAM:
- I wonder where they were.
BARRY:
- I don't know.
:
Their day's not planned.
:
Outside the hive, flying who knows
where, doing who knows what.
:
You can't just decide to be a Pollen
Jock. You have to be bred for that.
ADAM==
Right.
(Barry and Adam are covered in some pollen that floated off of the Pollen
Jocks)
BARRY:
Look at that. That's more pollen
than you and I will see in a lifetime.
ADAM:
It's just a status symbol.
Bees make too much of it.
BARRY:
Perhaps. Unless you're wearing it
and the ladies see you wearing it.
(Barry waves at 2 girls standing a little away from them)

ADAM==
Those ladies?
Aren't they our cousins too?
BARRY:
Distant. Distant.
POLLEN JOCK #1:
Look at these two.
POLLEN JOCK #2:
- Couple of Hive Harrys.
POLLEN JOCK #1:
- Let's have fun with them.
GIRL BEE #1:
It must be dangerous
being a Pollen Jock.
BARRY:
Yeah. Once a bear pinned me
against a mushroom!
:
He had a paw on my throat,
and with the other, he was slapping me!
(Slaps Adam with his hand to represent his scenario)
GIRL BEE #2:
- Oh, my!
BARRY:
- I never thought I'd knock him out.
GIRL BEE #1:
(Looking at Adam)
What were you doing during this?
ADAM:
Obviously I was trying to alert the authorities.
BARRY:
I can autograph that.

(The pollen jocks walk up to Barry and Adam, they pretend that Barry and
Adam really are pollen jocks.)
POLLEN JOCK #1:
A little gusty out there today,
wasn't it, comrades?
BARRY:
Yeah. Gusty.
POLLEN JOCK #1:
We're hitting a sunflower patch
six miles from here tomorrow.
BARRY:
- Six miles, huh?
ADAM:
- Barry!
POLLEN JOCK #2:
A puddle jump for us,
but maybe you're not up for it.
BARRY:
- Maybe I am.
ADAM:
- You are not!
POLLEN JOCK #1:
We're going 0900 at J-Gate.
:
What do you think, buzzy-boy?
Are you bee enough?
BARRY:
I might be. It all depends
on what 0900 means.
(The scene cuts to Barry looking out on the hive-city from his balcony at
night)
MARTIN:

Hey, Honex!
BARRY:
Dad, you surprised me.
MARTIN:
You decide what you're interested in?
BARRY:
- Well, there's a lot of choices.
- But you only get one.
:
Do you ever get bored
doing the same job every day?
MARTIN:
Son, let me tell you about stirring.
:
You grab that stick, and you just
move it around, and you stir it around.
:
You get yourself into a rhythm.
It's a beautiful thing.
BARRY:
You know, Dad,
the more I think about it,
:
maybe the honey field
just isn't right for me.
MARTIN:
You were thinking of what,
making balloon animals?
:
That's a bad job
for a guy with a stinger.
:

Janet, your son's not sure
he wants to go into honey!
JANET:
- Barry, you are so funny sometimes.
BARRY:
- I'm not trying to be funny.
MARTIN:
You're not funny! You're going
into honey. Our son, the stirrer!
JANET:
- You're gonna be a stirrer?
BARRY:
- No one's listening to me!
MARTIN:
Wait till you see the sticks I have.
BARRY:
I could say anything right now.
I'm gonna get an ant tattoo!
(Barry's parents don't listen to him and continue to ramble on)
MARTIN:
Let's open some honey and celebrate!
BARRY:
Maybe I'll pierce my thorax.
Shave my antennae.
:
Shack up with a grasshopper. Get
a gold tooth and call everybody "dawg"!
JANET:
I'm so proud.
(The scene cuts to Barry and Adam waiting in line to get a job)
ADAM:
- We're starting work today!

BARRY:
- Today's the day.
ADAM:
Come on! All the good jobs
will be gone.
BARRY:
Yeah, right.
JOB LISTER:
Pollen counting, stunt bee, pouring,
stirrer, front desk, hair removal...
BEE IN FRONT OF LINE:
- Is it still available?
JOB LISTER:
- Hang on. Two left!
:
One of them's yours! Congratulations!
Step to the side.
ADAM:
- What'd you get?
BEE IN FRONT OF LINE:
- Picking crud out. Stellar!
(He walks away)
ADAM:
Wow!
JOB LISTER:
Couple of newbies?
ADAM:
Yes, sir! Our first day! We are ready!
JOB LISTER:
Make your choice.
(Adam and Barry look up at the job board. There are hundreds of constantly
changing panels that contain available or unavailable jobs. It looks very
confusing)

ADAM:
- You want to go first?
BARRY:
- No, you go.
ADAM:
Oh, my. What's available?
JOB LISTER:
Restroom attendant's open,
not for the reason you think.
ADAM:
- Any chance of getting the Krelman?
JOB LISTER:
- Sure, you're on.
(Puts the Krelman finger-hat on Adam's head)
(Suddenly the sign for Krelman closes out)
:
I'm sorry, the Krelman just closed out.
(Takes Adam's hat off)
Wax monkey's always open.
ADAM:
The Krelman opened up again.
:
What happened?
JOB LISTER:
A bee died. Makes an opening. See?
He's dead. Another dead one.
:
Deady. Deadified. Two more dead.
:
Dead from the neck up.
Dead from the neck down. That's life!

ADAM:
Oh, this is so hard!
(Barry remembers what the Pollen Jock offered him and he flies off)
Heating, cooling,
stunt bee, pourer, stirrer,
:
humming, inspector number seven,
lint coordinator, stripe supervisor,
:
mite wrangler. Barry, what
do you think I should... Barry?
(Adam turns around and sees Barry flying away)
:
Barry!
POLLEN JOCK:
All right, we've got the sunflower patch
in quadrant nine...
ADAM:
(Through phone)
What happened to you?
Where are you?
BARRY:
- I'm going out.
ADAM:
- Out? Out where?
BARRY:
- Out there.
ADAM:
- Oh, no!
BARRY:
I have to, before I go
to work for the rest of my life.
ADAM:

You're gonna die! You're crazy!
(Barry hangs up)
Hello?
POLLEN JOCK #2:
Another call coming in.
:
If anyone's feeling brave,
there's a Korean deli on 83rd
:
that gets their roses today.
BARRY:
Hey, guys.
POLLEN JOCK #1 ==
- Look at that.
POLLEN JOCK #2:
- Isn't that the kid we saw yesterday?
LOU LO DUVA:
Hold it, son, flight deck's restricted.
POLLEN JOCK #1:
It's OK, Lou. We're gonna take him up.
(Puts hand on Barry's shoulder)
LOU LO DUVA:
(To Barry) Really? Feeling lucky, are you?
BEE WITH CLIPBOARD:
(To Barry) Sign here, here. Just initial that.
:
- Thank you.
LOU LO DUVA:
- OK.
:
You got a rain advisory today,
:

and as you all know,
bees cannot fly in rain.
:
So be careful. As always,
watch your brooms,
:
hockey sticks, dogs,
birds, bears and bats.
:
Also, I got a couple of reports
of root beer being poured on us.
:
Murphy's in a home because of it,
babbling like a cicada!
BARRY:
- That's awful.
LOU LO DUVA:
(Still talking through megaphone)
- And a reminder for you rookies,
:
bee law number one,
absolutely no talking to humans!
:
All right, launch positions!
POLLEN JOCKS:
(The Pollen Jocks run into formation)
:
Buzz, buzz, buzz, buzz! Buzz, buzz,
buzz, buzz! Buzz, buzz, buzz, buzz!
LOU LU DUVA:
Black and yellow!
POLLEN JOCKS:

Hello!
POLLEN JOCK #1:
(To Barry)You ready for this, hot shot?
BARRY:
Yeah. Yeah, bring it on.
POLLEN JOCK's:
Wind, check.
:
- Antennae, check.
- Nectar pack, check.
:
- Wings, check.
- Stinger, check.
BARRY:
Scared out of my shorts, check.
LOU LO DUVA:
OK, ladies,
:
let's move it out!
:
Pound those petunias,
you striped stem-suckers!
:
All of you, drain those flowers!
(The pollen jocks fly out of the hive)
BARRY:
Wow! I'm out!
:
I can't believe I'm out!
:
So blue.

:
I feel so fast and free!
:
Box kite!
(Barry flies through the kite)
:
Wow!
:
Flowers!
(A pollen jock puts on some high tech goggles that shows flowers similar to
heat sink goggles.)
POLLEN JOCK:
This is Blue Leader.
We have roses visual.
:
Bring it around 30 degrees and hold.
:
Roses!
POLLEN JOCK #1:
30 degrees, roger. Bringing it around.
:
Stand to the side, kid.
It's got a bit of a kick.
(The pollen jock fires a high-tech gun at the flower, shooting tubes that
suck up the nectar from the flower and collects it into a pouch on the gun)
BARRY:
That is one nectar collector!
POLLEN JOCK #1==
- Ever see pollination up close?
BARRY:
- No, sir.
POLLEN JOCK #1:

(Barry and the Pollen jock fly over the field, the pollen jock sprinkles
pollen as he goes)
:
I pick up some pollen here, sprinkle it
over here. Maybe a dash over there,
:
a pinch on that one.
See that? It's a little bit of magic.
BARRY:
That's amazing. Why do we do that?
POLLEN JOCK #1:
That's pollen power. More pollen, more
flowers, more nectar, more honey for us.
BARRY:
Cool.
POLLEN JOCK #1:
I'm picking up a lot of bright yellow.
could be daisies. Don't we need those?
POLLEN JOCK #2:
Copy that visual.
:
Wait. One of these flowers
seems to be on the move.
POLLEN JOCK #1:
Say again? You're reporting
a moving flower?
POLLEN JOCK #2:
Affirmative.
(The Pollen jocks land near the "flowers" which, to the audience are
obviously just tennis balls)
KEN:
(In the distance) That was on the line!

POLLEN JOCK #1:
This is the coolest. What is it?
POLLEN JOCK #2:
I don't know, but I'm loving this color.
:
It smells good.
Not like a flower, but I like it.
POLLEN JOCK #1:
Yeah, fuzzy.
(Sticks his hand on the ball but it gets stuck)
POLLEN JOCK #3==
Chemical-y.
(The pollen jock finally gets his hand free from the tennis ball)
POLLEN JOCK #1:
Careful, guys. It's a little grabby.
(The pollen jocks turn around and see Barry lying his entire body on top of
one of the tennis balls)
POLLEN JOCK #2:
My sweet lord of bees!
POLLEN JOCK #3:
Candy-brain, get off there!
POLLEN JOCK #1:
(Pointing upwards)
Problem!
(A human hand reaches down and grabs the tennis ball that Barry is stuck
to)
BARRY:
- Guys!
POLLEN JOCK #2:
- This could be bad.
POLLEN JOCK #3:
Affirmative.
(Vanessa Bloome starts bouncing the tennis ball, not knowing Barry is stick
to it)

BARRY==
Very close.
:
Gonna hurt.
:
Mama's little boy.
(Barry is being hit back and forth by two humans playing tennis. He is
still stuck to the ball)
POLLEN JOCK #1:
You are way out of position, rookie!
KEN:
Coming in at you like a MISSILE!
(Barry flies past the pollen jocks, still stuck to the ball)
BARRY:
(In slow motion)
Help me!
POLLEN JOCK #2:
I don't think these are flowers.
POLLEN JOCK #3:
- Should we tell him?
POLLEN JOCK #1:
- I think he knows.
BARRY:
What is this?!
KEN:
Match point!
:
You can start packing up, honey,
because you're about to EAT IT!
(A pollen jock coughs which confused Ken and he hits the ball the wrong way
with Barry stuck to it and it goes flying into the city)
BARRY:

Yowser!
(Barry bounces around town and gets stuck in the engine of a car. He flies
into the air conditioner and sees a bug that was frozen in there)
BARRY:
Ew, gross.
(The man driving the car turns on the air conditioner which blows Barry
into the car)
GIRL IN CAR:
There's a bee in the car!
:
- Do something!
DAD DRIVING CAR:
- I'm driving!
BABY GIRL:
(Waving at Barry)
- Hi, bee.
(Barry smiles and waves at the baby girl)
GUY IN BACK OF CAR:
- He's back here!
:
He's going to sting me!
GIRL IN CAR:
Nobody move. If you don't move,
he won't sting you. Freeze!
(Barry freezes as well, hovering in the middle of the car)
:
GRANDMA IN CAR==
He blinked!
(The grandma whips out some bee-spray and sprays everywhere in the car,
climbing into the front seat, still trying to spray Barry)
GIRL IN CAR:
Spray him, Granny!
DAD DRIVING THE CAR:
What are you doing?!
(Barry escapes the car through the air conditioner and is flying high above

the ground, safe.)
BARRY:
Wow... the tension level
out here is unbelievable.
(Barry sees that storm clouds are gathering and he can see rain clouds
moving into this direction)
:
I gotta get home.
:
Can't fly in rain.
:
Can't fly in rain.
(A rain drop hits Barry and one of his wings is damaged)
:
Can't fly in rain.
(A second rain drop hits Barry again and he spirals downwards)
Mayday! Mayday! Bee going down!
(WW2 plane sound effects are played as he plummets, and he crash-lands on a
plant inside an apartment near the window)
VANESSA BLOOME:
Ken, could you close
the window please?
KEN==
Hey, check out my new resume.
I made it into a fold-out brochure.
:
You see?
(Folds brochure resume out)
Folds out.
(Ken closes the window, trapping Barry inside)
BARRY:
Oh, no. More humans. I don't need this.
(Barry tries to fly away but smashes into the window and falls again)
:
What was that?

(Barry keeps trying to fly out the window but he keeps being knocked back
because the window is closed)
Maybe this time. This time. This time.
This time! This time! This...
:
Drapes!
(Barry taps the glass. He doesn't understand what it is)
That is diabolical.
KEN:
It's fantastic. It's got all my special
skills, even my top-ten favorite movies.
ANDY:
What's number one? Star Wars?
KEN:
Nah, I don't go for that...
(Ken makes finger guns and makes "pew pew pew" sounds and then stops)
:
...kind of stuff.
BARRY:
No wonder we shouldn't talk to them.
They're out of their minds.
KEN:
When I leave a job interview, they're
flabbergasted, can't believe what I say.
BARRY:
(Looking at the light on the ceiling)
There's the sun. Maybe that's a way out.
(Starts flying towards the lightbulb)
:
I don't remember the sun
having a big 75 on it.
(Barry hits the lightbulb and falls into the dip on the table that the
humans are sitting at)
KEN:

I predicted global warming.
:
I could feel it getting hotter.
At first I thought it was just me.
(Andy dips a chip into the bowl and scoops up some dip with Barry on it and
is about to put it in his mouth)
:
Wait! Stop! Bee!
(Andy drops the chip with Barry in fear and backs away. All the humans
freak out)
:
Stand back. These are winter boots.
(Ken has winter boots on his hands and he is about to smash the bee but
Vanessa saves him last second)
VANESSA:
Wait!
:
Don't kill him!
(Vanessa puts Barry in a glass to protect him)
KEN:
You know I'm allergic to them!
This thing could kill me!
VANESSA:
Why does his life have
less value than yours?
KEN:
Why does his life have any less value
than mine? Is that your statement?
VANESSA:
I'm just saying all life has value. You
don't know what he's capable of feeling.
(Vanessa picks up Ken's brochure and puts it under the glass so she can
carry Barry back to the window. Barry looks at Vanessa in amazement)
KEN:

My brochure!
VANESSA:
There you go, little guy.
(Vanessa opens the window and lets Barry out but Barry stays back and is
still shocked that a human saved his life)
KEN:
I'm not scared of him.
It's an allergic thing.
VANESSA:
Put that on your resume brochure.
KEN:
My whole face could puff up.
ANDY:
Make it one of your special skills.
KEN:
Knocking someone out
is also a special skill.
(Ken walks to the door)
Right. Bye, Vanessa. Thanks.
:
- Vanessa, next week? Yogurt night?
VANESSA:
- Sure, Ken. You know, whatever.
:
(Vanessa tries to close door)
KEN==
- You could put carob chips on there.
VANESSA:
- Bye.
(Closes door but Ken opens it again)
KEN:
- Supposed to be less calories.

VANESSA:
- Bye.
(Closes door)
(Fast forward to the next day, Barry is still inside the house. He flies
into the kitchen where Vanessa is doing dishes)
BARRY==
(Talking to himself)
I gotta say something.
:
She saved my life.
I gotta say something.
:
All right, here it goes.
(Turns back)
Nah.
:
What would I say?
:
I could really get in trouble.
:
It's a bee law.
You're not supposed to talk to a human.
:
I can't believe I'm doing this.
:
I've got to.
(Barry disguises himself as a character on a food can as Vanessa walks by
again)
:
Oh, I can't do it. Come on!
:
No. Yes. No.
:
Do it. I can't.

:
How should I start it?
(Barry strikes a pose and wiggles his eyebrows)
"You like jazz?"
No, that's no good.
(Vanessa is about to walk past Barry)
Here she comes! Speak, you fool!
:
...Hi!
(Vanessa gasps and drops the dishes in fright and notices Barry on the
counter)
:
I'm sorry.
VANESSA:
- You're talking.
BARRY:
- Yes, I know.
VANESSA:
(Pointing at Barry)
You're talking!
BARRY:
I'm so sorry.
VANESSA:
No, it's OK. It's fine.
I know I'm dreaming.
:
But I don't recall going to bed.
BARRY:
Well, I'm sure this
is very disconcerting.
VANESSA:
This is a bit of a surprise to me.
I mean, you're a bee!

BARRY:
I am. And I'm not supposed
to be doing this,
(Pointing to the living room where Ken tried to kill him last night)
but they were all trying to kill me.
:
And if it wasn't for you...
:
I had to thank you.
It's just how I was raised.
(Vanessa stabs her hand with a fork to test whether she's dreaming or not)
:
That was a little weird.
VANESSA:
- I'm talking with a bee.
BARRY:
- Yeah.
VANESSA:
I'm talking to a bee.
And the bee is talking to me!
BARRY:
I just want to say I'm grateful.
I'll leave now.
(Barry turns to leave)
VANESSA:
- Wait! How did you learn to do that?
BARRY:
(Flying back)
- What?
VANESSA:
The talking...thing.
BARRY:

Same way you did, I guess.
"Mama, Dada, honey." You pick it up.
VANESSA:
- That's very funny.
BARRY:
- Yeah.
:
Bees are funny. If we didn't laugh,
we'd cry with what we have to deal with.
:
Anyway...
VANESSA:
Can I...
:
...get you something?
BARRY:
- Like what?
VANESSA:
I don't know. I mean...
I don't know. Coffee?
BARRY:
I don't want to put you out.
VANESSA:
It's no trouble. It takes two minutes.
:
- It's just coffee.
BARRY:
- I hate to impose.
(Vanessa starts making coffee)
VANESSA:
- Don't be ridiculous!

BARRY:
- Actually, I would love a cup.
VANESSA:
Hey, you want rum cake?
BARRY:
- I shouldn't.
VANESSA:
- Have some.
BARRY:
- No, I can't.
VANESSA:
- Come on!
BARRY:
I'm trying to lose a couple micrograms.
VANESSA:
- Where?
BARRY:
- These stripes don't help.
VANESSA:
You look great!
BARRY:
I don't know if you know
anything about fashion.
:
Are you all right?
VANESSA:
(Pouring coffee on the floor and missing the cup completely)
No.
(Flash forward in time. Barry and Vanessa are sitting together at a table
on top of the apartment building drinking coffee)

:
BARRY==
He's making the tie in the cab
as they're flying up Madison.
:
He finally gets there.
:
He runs up the steps into the church.
The wedding is on.
:
And he says, "Watermelon?
I thought you said Guatemalan.
:
Why would I marry a watermelon?"
(Barry laughs but Vanessa looks confused)
VANESSA:
Is that a bee joke?
BARRY:
That's the kind of stuff we do.
VANESSA:
Yeah, different.
:
So, what are you gonna do, Barry?
(Barry stands on top of a sugar cube floating in his coffee and paddles it
around with a straw like it's a gondola)
BARRY:
About work? I don't know.
:
I want to do my part for the hive,
but I can't do it the way they want.
VANESSA:
I know how you feel.

BARRY:
- You do?
VANESSA:
- Sure.
:
My parents wanted me to be a lawyer or
a doctor, but I wanted to be a florist.
BARRY:
- Really?
VANESSA:
- My only interest is flowers.
BARRY:
Our new queen was just elected
with that same campaign slogan.
:
Anyway, if you look...
(Barry points to a tree in the middle of Central Park)
:
There's my hive right there. See it?
VANESSA:
You're in Sheep Meadow!
BARRY:
Yes! I'm right off the Turtle Pond!
VANESSA:
No way! I know that area.
I lost a toe ring there once.
BARRY:
- Why do girls put rings on their toes?
VANESSA:
- Why not?
BARRY:

- It's like putting a hat on your knee.
VANESSA:
- Maybe I'll try that.
(A custodian installing a lightbulb looks over at them but to his
perspective it looks like Vanessa is talking to a cup of coffee on the
table)
CUSTODIAN:
- You all right, ma'am?
VANESSA:
- Oh, yeah. Fine.
:
Just having two cups of coffee!
BARRY:
Anyway, this has been great.
Thanks for the coffee.
VANESSA==
Yeah, it's no trouble.
BARRY:
Sorry I couldn't finish it. If I did,
I'd be up the rest of my life.
(Barry points towards the rum cake)
:
Can I take a piece of this with me?
VANESSA:
Sure! Here, have a crumb.
(Vanessa hands Barry a crumb but it is still pretty big for Barry)
BARRY:
- Thanks!
VANESSA:
- Yeah.
BARRY:
All right. Well, then...
I guess I'll see you around.

:
Or not.
VANESSA:
OK, Barry...
BARRY:
And thank you
so much again... for before.
VANESSA:
Oh, that? That was nothing.
BARRY:
Well, not nothing, but... Anyway...
(Vanessa and Barry hold hands, but Vanessa has to hold out a finger because
her hands is to big and Barry holds that)
(The custodian looks over again and it appears Vanessa is laughing at her
coffee again. The lightbulb that he was screwing in sparks and he falls off
the ladder)
(Fast forward in time and we see two Bee Scientists testing out a parachute
in a Honex wind tunnel)
BEE SCIENTIST #1:
This can't possibly work.
BEE SCIENTIST #2:
He's all set to go.
We may as well try it.
:
OK, Dave, pull the chute.
(Dave pulls the chute and the wind slams him against the wall and he falls
on his face.The camera pans over and we see Barry and Adam walking
together)
ADAM:
- Sounds amazing.
BARRY:
- It was amazing!
:
It was the scariest,
happiest moment of my life.

ADAM:
Humans! I can't believe
you were with humans!
:
Giant, scary humans!
What were they like?
BARRY:
Huge and crazy. They talk crazy.
:
They eat crazy giant things.
They drive crazy.
ADAM:
- Do they try and kill you, like on TV?
BARRY:
- Some of them. But some of them don't.
ADAM:
- How'd you get back?
BARRY:
- Poodle.
ADAM:
You did it, and I'm glad. You saw
whatever you wanted to see.
:
You had your "experience." Now you
can pick out your job and be normal.
BARRY:
- Well...
ADAM:
- Well?
BARRY:
Well, I met someone.

ADAM:
You did? Was she Bee-ish?
:
- A wasp?! Your parents will kill you!
BARRY:
- No, no, no, not a wasp.
ADAM:
- Spider?
BARRY:
- I'm not attracted to spiders.
:
I know, for everyone else, it's the hottest thing,
with the eight legs and all.
:
I can't get by that face.
ADAM:
So who is she?
BARRY:
She's... human.
ADAM:
No, no. That's a bee law.
You wouldn't break a bee law.
BARRY:
- Her name's Vanessa.
(Adam puts his head in his hands)
ADAM:
- Oh, boy.
BARRY==
She's so nice. And she's a florist!
ADAM:
Oh, no! You're dating a human florist!

BARRY:
We're not dating.
ADAM:
You're flying outside the hive, talking
to humans that attack our homes
:
with power washers and M-80s!
That's one-eighth a stick of dynamite!
BARRY:
She saved my life!
And she understands me.
ADAM:
This is over!
BARRY:
Eat this.
(Barry gives Adam a piece of the crumb that he got from Vanessa. Adam eats
it)
ADAM:
(Adam's tone changes)
This is not over! What was that?
BARRY:
- They call it a crumb.
ADAM:
- It was so stingin' stripey!
BARRY:
And that's not what they eat.
That's what falls off what they eat!
:
- You know what a Cinnabon is?
ADAM:
- No.
(Adam opens a door behind him and he pulls Barry in)

BARRY:
It's bread and cinnamon and frosting.
ADAM:
Be quiet!
BARRY:
They heat it up...
ADAM:
Sit down!
(Adam forces Barry to sit down)
BARRY:
(Still rambling about Cinnabons)
...really hot!
(Adam grabs Barry by the shoulders)
ADAM:
- Listen to me!
:
We are not them! We're us.
There's us and there's them!
BARRY==
Yes, but who can deny
the heart that is yearning?
ADAM:
There's no yearning.
Stop yearning. Listen to me!
:
You have got to start thinking bee,
my friend. Thinking bee!
BARRY:
- Thinking bee.
WORKER BEE:
- Thinking bee.
WORKER BEES AND ADAM:
Thinking bee! Thinking bee!

Thinking bee! Thinking bee!
(Flash forward in time; Barry is laying on a raft in a pool full of honey.
He is wearing sunglasses)
JANET:
There he is. He's in the pool.
MARTIN:
You know what your problem is, Barry?
(Barry pulls down his sunglasses and he looks annoyed)
BARRY:
(Sarcastic)
I gotta start thinking bee?
JANET:
How much longer will this go on?
MARTIN:
It's been three days!
Why aren't you working?
(Puts sunglasses back on)
BARRY:
I've got a lot of big life decisions
to think about.
MARTIN:
What life? You have no life!
You have no job. You're barely a bee!
JANET:
Would it kill you
to make a little honey?
(Barry rolls off the raft and sinks into the honey pool)
:
Barry, come out.
Your father's talking to you.
:
Martin, would you talk to him?
MARTIN:

Barry, I'm talking to you!
(Barry keeps sinking into the honey until he is suddenly in Central Park
having a picnic with Vanessa)
(Barry has a cup of honey and he clinks his glass with Vanessas. Suddenly a
mosquito lands on Vanessa and she slaps it, killing it. They both gasp but
then burst out laughing)
VANESSA:
You coming?
(The camera pans over and Vanessa is climbing into a small yellow airplane)
BARRY:
Got everything?
VANESSA:
All set!
BARRY:
Go ahead. I'll catch up.
(Vanessa lifts off and flies ahead)
VANESSA:
Don't be too long.
(Barry catches up with Vanessa and he sticks out his arms like ana irplane.
He rolls from side to side, and Vanessa copies him with the airplane)
VANESSA:
Watch this!
(Barry stays back and watches as Vanessa draws a heart in the air using
pink smoke from the plane, but on the last loop-the-loop she suddenly
crashes into a mountain and the plane explodes. The destroyed plane falls
into some rocks and explodes a second time)
BARRY:
Vanessa!
(As Barry is yelling his mouth fills with honey and he wakes up,
discovering that he was just day dreaming. He slowly sinks back into the
honey pool)
MARTIN:
- We're still here.

JANET:
- I told you not to yell at him.
:
He doesn't respond to yelling!
MARTIN:
- Then why yell at me?
JANET:
- Because you don't listen!
MARTIN:
I'm not listening to this.
BARRY:
Sorry, I've gotta go.
MARTIN:
- Where are you going?
BARRY:
- I'm meeting a friend.
JANET:
A girl? Is this why you can't decide?
BARRY:
Bye.
(Barry flies out the door and Martin shakes his head)
:
JANET==
I just hope she's Bee-ish.
(Fast forward in time and Barry is sitting on Vanessa's shoulder and she is
closing up her shop)
BARRY:
They have a huge parade
of flowers every year in Pasadena?
VANESSA:
To be in the Tournament of Roses,
that's every florist's dream!

:
Up on a float, surrounded
by flowers, crowds cheering.
BARRY:
A tournament. Do the roses
compete in athletic events?
VANESSA:
No. All right, I've got one.
How come you don't fly everywhere?
BARRY:
It's exhausting. Why don't you
run everywhere? It's faster.
VANESSA:
Yeah, OK, I see, I see.
All right, your turn.
BARRY:
TiVo. You can just freeze live TV?
That's insane!
VANESSA:
You don't have that?
BARRY:
We have Hivo, but it's a disease.
It's a horrible, horrible disease.
VANESSA:
Oh, my.
(A human walks by and Barry narrowly avoids him)
PASSERBY:
Dumb bees!
VANESSA:
You must want to sting all those jerks.
BARRY:
We try not to sting.

It's usually fatal for us.
VANESSA:
So you have to watch your temper
(They walk into a store)
BARRY:
Very carefully.
You kick a wall, take a walk,
:
write an angry letter and throw it out.
Work through it like any emotion:
:
Anger, jealousy, lust.
(Suddenly an employee(Hector) hits Barry off of Vanessa's shoulder. Hector
thinks he's saving Vanessa)
VANESSA:
(To Barry)
Oh, my goodness! Are you OK?
(Barry is getting up off the floor)
BARRY:
Yeah.
VANESSA:
(To Hector)
- What is wrong with you?!
HECTOR:
(Confused)
- It's a bug.
VANESSA:
He's not bothering anybody.
Get out of here, you creep!
(Vanessa hits Hector across the face with the magazine he had and then hits
him in the head. Hector backs away covering his head)
Barry:
What was that? A Pic 'N' Save circular?
(Vanessa sets Barry back on her shoulder)

VANESSA:
Yeah, it was. How did you know?
BARRY:
It felt like about 10 pages.
Seventy-five is pretty much our limit.
VANESSA:
You've really got that
down to a science.
BARRY:
- Oh, we have to. I lost a cousin to Italian Vogue.
VANESSA:
- I'll bet.
(Barry looks to his right and notices there is honey for sale in the aisle)
BARRY:
What in the name
of Mighty Hercules is this?
(Barry looks at all the brands of honey, shocked)
How did this get here?
Cute Bee, Golden Blossom,
:
Ray Liotta Private Select?
(Barry puts his hands up and slowly turns around, a look of disgust on his
face)
VANESSA:
- Is he that actor?
BARRY:
- I never heard of him.
:
- Why is this here?
VANESSA:
- For people. We eat it.
BARRY:

You don't have
enough food of your own?!
(Hector looks back and notices that Vanessa is talking to Barry)
VANESSA:
- Well, yes.
BARRY:
- How do you get it?
VANESSA:
- Bees make it.
BARRY:
- I know who makes it!
:
And it's hard to make it!
:
There's heating, cooling, stirring.
You need a whole Krelman thing!
VANESSA:
- It's organic.
BARRY:
- It's our-ganic!
VANESSA:
It's just honey, Barry.
BARRY:
Just what?!
:
Bees don't know about this!
This is stealing! A lot of stealing!
:
You've taken our homes, schools,
hospitals! This is all we have!
:

And it's on sale?!
I'm getting to the bottom of this.
:
I'm getting to the bottom
of all of this!
(Flash forward in time; Barry paints his face with black strikes like a
soldier and sneaks into the storage section of the store)
(Two men, including Hector, are loading boxes into some trucks)
:
SUPERMARKET EMPLOYEE==
Hey, Hector.
:
- You almost done?
HECTOR:
- Almost.
(Barry takes a step to peak around the corner)
(Whispering)
He is here. I sense it.
:
Well, I guess I'll go home now
(Hector pretends to walk away by walking in place and speaking loudly)
:
and just leave this nice honey out,
with no one around.
BARRY:
You're busted, box boy!
HECTOR:
I knew I heard something!
So you can talk!
BARRY:
I can talk.
And now you'll start talking!
:
Where you getting the sweet stuff?

Who's your supplier?
HECTOR:
I don't understand.
I thought we were friends.
:
The last thing we want
to do is upset bees!
(Hector takes a thumbtack out of the board behind him and sword-fights
Barry. Barry is using his stinger like a sword)
:
You're too late! It's ours now!
BARRY:
You, sir, have crossed
the wrong sword!
HECTOR:
You, sir, will be lunch
for my iguana, Ignacio!
(Barry hits the thumbtack out of Hectors hand and Hector surrenders)
Barry:
Where is the honey coming from?
:
Tell me where!
HECTOR:
(Pointing to leaving truck)
Honey Farms! It comes from Honey Farms!
(Barry chases after the truck but it is getting away. He flies onto a
bicyclists' backpack and he catches up to the truck)
CAR DRIVER:
(To bicyclist)
Crazy person!
(Barry flies off and lands on the windshield of the Honey farms truck.
Barry looks around and sees dead bugs splattered everywhere)
BARRY:
What horrible thing has happened here?

:
These faces, they never knew
what hit them. And now
:
they're on the road to nowhere!
(Barry hears a sudden whisper)
(Barry looks up and sees Mooseblood, a mosquito playing dead)
MOOSEBLOOD:
Just keep still.
BARRY:
What? You're not dead?
MOOSEBLOOD:
Do I look dead? They will wipe anything
that moves. Where you headed?
BARRY:
To Honey Farms.
I am onto something huge here.
MOOSEBLOOD:
I'm going to Alaska. Moose blood,
crazy stuff. Blows your head off!
ANOTHER BUG PLAYING DEAD:
I'm going to Tacoma.
(Barry looks at another bug)
BARRY:
- And you?
MOOSEBLOOD:
- He really is dead.
BARRY:
All right.
(Another bug hits the windshield and the drivers notice. They activate the
windshield wipers)
MOOSEBLOOD==
Uh-oh!
(The windshield wipers are slowly sliding over the dead bugs and wiping

them off)
BARRY:
- What is that?!
MOOSEBLOOD:
- Oh, no!
:
- A wiper! Triple blade!
BARRY:
- Triple blade?
MOOSEBLOOD:
Jump on! It's your only chance, bee!
(Mooseblood and Barry grab onto the wiper and they hold on as it wipes the
windshield)
Why does everything have
to be so doggone clean?!
:
How much do you people need to see?!
(Bangs on windshield)
:
Open your eyes!
Stick your head out the window!
RADIO IN TRUCK:
From NPR News in Washington,
I'm Carl Kasell.
MOOSEBLOOD:
But don't kill no more bugs!
(Mooseblood and Barry are washed off by the wipr fluid)
MOOSEBLOOD:
- Bee!
BARRY:
- Moose blood guy!!
(Barry starts screaming as he hangs onto the antenna)
(Suddenly it is revealed that a water bug is also hanging on the antenna.

There is a pause and then Barry and the water bug both start screaming)
TRUCK DRIVER:
- You hear something?
GUY IN TRUCK:
- Like what?
TRUCK DRIVER:
Like tiny screaming.
GUY IN TRUCK:
Turn off the radio.
(The antenna starts to lower until it gets to low and sinks into the truck.
The water bug flies off and Barry is forced to let go and he is blown away.
He luckily lands inside a horn on top of the truck where he finds
Mooseblood, who was blown into the same place)
MOOSEBLOOD:
Whassup, bee boy?
BARRY:
Hey, Blood.
(Fast forward in time and we see that Barry is deep in conversation with
Mooseblood. They have been sitting in this truck for a while)
BARRY:
...Just a row of honey jars,
as far as the eye could see.
MOOSEBLOOD:
Wow!
BARRY:
I assume wherever this truck goes
is where they're getting it.
:
I mean, that honey's ours.
MOOSEBLOOD:
- Bees hang tight.
BARRY:

- We're all jammed in.
:
It's a close community.
MOOSEBLOOD:
Not us, man. We on our own.
Every mosquito on his own.
BARRY:
- What if you get in trouble?
MOOSEBLOOD:
- You a mosquito, you in trouble.
:
Nobody likes us. They just smack.
See a mosquito, smack, smack!
BARRY:
At least you're out in the world.
You must meet girls.
MOOSEBLOOD:
Mosquito girls try to trade up,
get with a moth, dragonfly.
:
Mosquito girl don't want no mosquito.
(An ambulance passes by and it has a blood donation sign on it)
You got to be kidding me!
:
Mooseblood's about to leave
the building! So long, bee!
(Mooseblood leaves and flies onto the window of the ambulance where there
are other mosquito's hanging out)
:
- Hey, guys!
OTHER MOSQUITO:
- Mooseblood!

MOOSEBLOOD:
I knew I'd catch y'all down here.
Did you bring your crazy straw?
(The truck goes out of view and Barry notices that the truck he's on is
pulling into a camp of some sort)
TRUCK DRIVER:
We throw it in jars, slap a label on it,
and it's pretty much pure profit.
(Barry flies out)
BARRY:
What is this place?
BEEKEEPER 1#:
A bee's got a brain
the size of a pinhead.
BEEKEEPER #2:
They are pinheads!
:
Pinhead.
:
- Check out the new smoker.
BEEKEEPER #1:
- Oh, sweet. That's the one you want.
:
The Thomas 3000!
BARRY:
Smoker?
BEEKEEPER #1:
Ninety puffs a minute, semi-automatic.
Twice the nicotine, all the tar.
:
A couple breaths of this
knocks them right out.

BEEKEEPER #2:
They make the honey,
and we make the money.
BARRY:
"They make the honey,
and we make the money"?
(The Beekeeper sprays hundreds of cheap miniature apartments with the
smoker. The bees are fainting or passing out)
Oh, my!
:
What's going on? Are you OK?
(Barry flies into one of the apartment and helps a Bee couple get off the
ground. They are coughing and its hard for them to stand)
BEE IN APARTMENT:
Yeah. It doesn't last too long.
BARRY:
Do you know you're
in a fake hive with fake walls?
BEE IN APPARTMENT:
Our queen was moved here.
We had no choice.
(The apartment room is completely empty except for a photo on the wall of
the "queen" who is obviously a man in women's clothes)
BARRY:
This is your queen?
That's a man in women's clothes!
:
That's a drag queen!
:
What is this?
(Barry flies out and he discovers that there are hundreds of these
structures, each housing thousands of Bees)
Oh, no!
:
There's hundreds of them!
(Barry takes out his camera and takes pictures of these Bee work camps. The
beekeepers look very evil in these depictions)

Bee honey.
:
Our honey is being brazenly stolen
on a massive scale!
:
This is worse than anything bears
have done! I intend to do something.
(Flash forward in time and Barry is showing these pictures to his parents)
JANET:
Oh, Barry, stop.
MARTIN:
Who told you humans are taking
our honey? That's a rumor.
BARRY:
Do these look like rumors?
(Holds up the pictures)
UNCLE CARL:
That's a conspiracy theory.
These are obviously doctored photos.
JANET:
How did you get mixed up in this?
ADAM:
He's been talking to humans.
JANET:
- What?
MARTIN:
- Talking to humans?!
ADAM:
He has a human girlfriend.
And they make out!
JANET:
Make out? Barry!

BARRY:
We do not.
ADAM:
- You wish you could.
MARTIN:
- Whose side are you on?
BARRY:
The bees!
UNCLE CARL:
(He has been sitting in the back of the room this entire time)
I dated a cricket once in San Antonio.
Those crazy legs kept me up all night.
JANET:
Barry, this is what you want
to do with your life?
BARRY:
I want to do it for all our lives.
Nobody works harder than bees!
:
Dad, I remember you
coming home so overworked
:
your hands were still stirring.
You couldn't stop.
JANET:
I remember that.
BARRY:
What right do they have to our honey?
:
We live on two cups a year. They put it
in lip balm for no reason whatsoever!

ADAM:
Even if it's true, what can one bee do?
BARRY:
Sting them where it really hurts.
MARTIN:
In the face! The eye!
:
- That would hurt.
BARRY:
- No.
MARTIN:
Up the nose? That's a killer.
BARRY:
There's only one place you can sting
the humans, one place where it matters.
(Flash forward a bit in time and we are watching the Bee News)
BEE NEWS NARRATOR:
Hive at Five, the hive's only
full-hour action news source.
BEE PROTESTOR:
No more bee beards!
BEE NEWS NARRATOR:
With Bob Bumble at the anchor desk.
:
Weather with Storm Stinger.
:
Sports with Buzz Larvi.
:
And Jeanette Chung.
BOB BUMBLE:
- Good evening. I'm Bob Bumble.
JEANETTE CHUNG:

- And I'm Jeanette Chung.
BOB BUMBLE:
A tri-county bee, Barry Benson,
:
intends to sue the human race
for stealing our honey,
:
packaging it and profiting
from it illegally!
JEANETTE CHUNG:
Tomorrow night on Bee Larry King,
:
we'll have three former queens here in
our studio, discussing their new book,
:
Classy Ladies,
out this week on Hexagon.
(The scene changes to an interview on the news with Bee version of Larry
King and Barry)
BEE LARRY KING:
Tonight we're talking to Barry Benson.
:
Did you ever think, "I'm a kid
from the hive. I can't do this"?
BARRY:
Bees have never been afraid
to change the world.
:
What about Bee Columbus?
Bee Gandhi? Bejesus?
BEE LARRY KING:
Where I'm from, we'd never sue humans.

:
We were thinking
of stickball or candy stores.
BARRY:
How old are you?
BEE LARRY KING:
The bee community
is supporting you in this case,
:
which will be the trial
of the bee century.
BARRY:
You know, they have a Larry King
in the human world too.
BEE LARRY KING:
It's a common name. Next week...
BARRY:
He looks like you and has a show
and suspenders and colored dots...
BEE LARRY KING:
Next week...
BARRY:
Glasses, quotes on the bottom from the
guest even though you just heard 'em.
BEE LARRY KING:
Bear Week next week!
They're scary, hairy and here, live.
(Bee Larry King gets annoyed and flies away offscreen)
BARRY:
Always leans forward, pointy shoulders,
squinty eyes, very Jewish.
(Flash forward in time. We see Vanessa enter and Ken enters behind her.
They are arguing)

KEN:
In tennis, you attack
at the point of weakness!
VANESSA:
It was my grandmother, Ken. She's 81.
KEN==
Honey, her backhand's a joke!
I'm not gonna take advantage of that?
BARRY:
(To Ken)
Quiet, please.
Actual work going on here.
KEN:
(Pointing at Barry)
- Is that that same bee?
VANESSA:
- Yes, it is!
:
I'm helping him sue the human race.
BARRY:
- Hello.
KEN:
- Hello, bee.
VANESSA:
This is Ken.
BARRY:
(Recalling the "Winter Boots" incident earlier)
Yeah, I remember you. Timberland, size
ten and a half. Vibram sole, I believe.
KEN:
(To Vanessa)
Why does he talk again?
VANESSA:

Listen, you better go
'cause we're really busy working.
KEN:
But it's our yogurt night!
VANESSA:
(Holding door open for Ken)
Bye-bye.
KEN:
(Yelling)
Why is yogurt night so difficult?!
(Ken leaves and Vanessa walks over to Barry. His workplace is a mess)
VANESSA:
You poor thing.
You two have been at this for hours!
BARRY:
Yes, and Adam here
has been a huge help.
ADAM:
- Frosting...
- How many sugars?
==BARRY==
Just one. I try not
to use the competition.
:
So why are you helping me?
VANESSA:
Bees have good qualities.
:
And it takes my mind off the shop.
:
Instead of flowers, people
are giving balloon bouquets now.
BARRY:

Those are great, if you're three.
VANESSA:
And artificial flowers.
BARRY:
- Oh, those just get me psychotic!
VANESSA:
- Yeah, me too.
:
BARRY:
Bent stingers, pointless pollination.
ADAM:
Bees must hate those fake things!
:
Nothing worse
than a daffodil that's had work done.
:
Maybe this could make up
for it a little bit.
VANESSA:
- This lawsuit's a pretty big deal.
BARRY:
- I guess.
ADAM:
You sure you want to go through with it?
BARRY:
Am I sure? When I'm done with
the humans, they won't be able
:
to say, "Honey, I'm home,"
without paying a royalty!
(Flash forward in time and we are watching the human news. The camera shows

a crowd outside a courthouse)
NEWS REPORTER:
It's an incredible scene
here in downtown Manhattan,
:
where the world anxiously waits,
because for the first time in history,
:
we will hear for ourselves
if a honeybee can actually speak.
(We are no longer watching through a news camera)
ADAM:
What have we gotten into here, Barry?
BARRY:
It's pretty big, isn't it?
ADAM==
(Looking at the hundreds of people around the courthouse)
I can't believe how many humans
don't work during the day.
BARRY:
You think billion-dollar multinational
food companies have good lawyers?
SECURITY GUARD:
Everybody needs to stay
behind the barricade.
(A limousine drives up and a fat man,Layton Montgomery, a honey industry
owner gets out and walks past Barry)
ADAM:
- What's the matter?
BARRY:
- I don't know, I just got a chill.
(Fast forward in time and everyone is in the court)
MONTGOMERY:
Well, if it isn't the bee team.

(To Honey Industry lawyers)
You boys work on this?
MAN:
All rise! The Honorable
Judge Bumbleton presiding.
JUDGE BUMBLETON:
All right. Case number 4475,
:
Superior Court of New York,
Barry Bee Benson v. the Honey Industry
:
is now in session.
:
Mr. Montgomery, you're representing
the five food companies collectively?
MONTGOMERY:
A privilege.
JUDGE BUMBLETON:
Mr. Benson... you're representing
all the bees of the world?
(Everyone looks closely, they are waiting to see if a Bee can really talk)
(Barry makes several buzzing sounds to sound like a Bee)
BARRY:
I'm kidding. Yes, Your Honor,
we're ready to proceed.
JUDGE BUMBLBETON:
Mr. Montgomery,
your opening statement, please.
MONTGOMERY:
Ladies and gentlemen of the jury,
:
my grandmother was a simple woman.
:

Born on a farm, she believed
it was man's divine right
:
to benefit from the bounty
of nature God put before us.
:
If we lived in the topsy-turvy world
Mr. Benson imagines,
:
just think of what would it mean.
:
I would have to negotiate
with the silkworm
:
for the elastic in my britches!
:
Talking bee!
(Montgomery walks over and looks closely at Barry)
:
How do we know this isn't some sort of
:
holographic motion-picture-capture
Hollywood wizardry?
:
They could be using laser beams!
:
Robotics! Ventriloquism!
Cloning! For all we know,
:
he could be on steroids!
JUDGE BUMBLETON:
Mr. Benson?

BARRY:
Ladies and gentlemen,
there's no trickery here.
:
I'm just an ordinary bee.
Honey's pretty important to me.
:
It's important to all bees.
We invented it!
:
We make it. And we protect it
with our lives.
:
Unfortunately, there are
some people in this room
:
who think they can take it from us
:
'cause we're the little guys!
I'm hoping that, after this is all over,
:
you'll see how, by taking our honey,
you not only take everything we have
:
but everything we are!
JANET==
(To Martin)
I wish he'd dress like that
all the time. So nice!
JUDGE BUMBLETON:
Call your first witness.
BARRY:
So, Mr. Klauss Vanderhayden

of Honey Farms, big company you have.
KLAUSS VANDERHAYDEN:
I suppose so.
BARRY:
I see you also own
Honeyburton and Honron!
KLAUSS:
Yes, they provide beekeepers
for our farms.
BARRY:
Beekeeper. I find that
to be a very disturbing term.
:
I don't imagine you employ
any bee-free-ers, do you?
KLAUSS:
(Quietly)
- No.
BARRY:
- I couldn't hear you.
KLAUSS:
- No.
BARRY:
- No.
:
Because you don't free bees.
You keep bees. Not only that,
:
it seems you thought a bear would be
an appropriate image for a jar of honey.
KLAUSS:
They're very lovable creatures.

:
Yogi Bear, Fozzie Bear, Build-A-Bear.
BARRY:
You mean like this?
(The bear from Over The Hedge barges in through the back door and it is
roaring and standing on its hind legs. It is thrashing its claws and people
are screaming. It is being held back by a guard who has the bear on a
chain)
:
(Pointing to the roaring bear)
Bears kill bees!
:
How'd you like his head crashing
through your living room?!
:
Biting into your couch!
Spitting out your throw pillows!
JUDGE BUMBLETON:
OK, that's enough. Take him away.
(The bear stops roaring and thrashing and walks out)
BARRY:
So, Mr. Sting, thank you for being here.
Your name intrigues me.
:
- Where have I heard it before?
MR. STING:
- I was with a band called The Police.
BARRY:
But you've never been
a police officer, have you?
STING:
No, I haven't.
BARRY:

No, you haven't. And so here
we have yet another example
:
of bee culture casually
stolen by a human
:
for nothing more than
a prance-about stage name.
STING:
Oh, please.
BARRY:
Have you ever been stung, Mr. Sting?
:
Because I'm feeling
a little stung, Sting.
:
Or should I say... Mr. Gordon M. Sumner!
MONTGOMERY:
That's not his real name?! You idiots!
BARRY:
Mr. Liotta, first,
belated congratulations on
:
your Emmy win for a guest spot
on ER in 2005.
RAY LIOTTA:
Thank you. Thank you.
BARRY:
I see from your resume
that you're devilishly handsome
:
with a churning inner turmoil

that's ready to blow.
RAY LIOTTA:
I enjoy what I do. Is that a crime?
BARRY:
Not yet it isn't. But is this
what it's come to for you?
:
Exploiting tiny, helpless bees
so you don't
:
have to rehearse
your part and learn your lines, sir?
RAY LIOTTA:
Watch it, Benson!
I could blow right now!
BARRY:
This isn't a goodfella.
This is a badfella!
(Ray Liotta looses it and tries to grab Barry)
RAY LIOTTA:
Why doesn't someone just step on
this creep, and we can all go home?!
JUDGE BUMBLETON:
- Order in this court!
RAY LIOTTA:
- You're all thinking it!
(Judge Bumbleton starts banging her gavel)
JUDGE BUMBLETON:
Order! Order, I say!
RAY LIOTTA:
- Say it!
MAN:

- Mr. Liotta, please sit down!
(We see a montage of magazines which feature the court case)
(Flash forward in time and Barry is back home with Vanessa)
BARRY:
I think it was awfully nice
of that bear to pitch in like that.
VANESSA:
I think the jury's on our side.
BARRY:
Are we doing everything right,you know, legally?
VANESSA:
I'm a florist.
BARRY:
Right. Well, here's to a great team.
VANESSA:
To a great team!
(Ken walks in from work. He sees Barry and he looks upset when he sees
Barry clinking his glass with Vanessa)
KEN:
Well, hello.
VANESSA:
- Oh, Ken!
BARRY:
- Hello!
VANESSA:
I didn't think you were coming.
:
No, I was just late.
I tried to call, but...
(Ken holds up his phone and flips it open. The phone has no charge)
...the battery...
VANESSA:

I didn't want all this to go to waste,
so I called Barry. Luckily, he was free.
KEN:
Oh, that was lucky.
(Ken sits down at the table across from Barry and Vanessa leaves the room)
VANESSA:
There's a little left.
I could heat it up.
KEN:
(Not taking his eyes off Barry)
Yeah, heat it up, sure, whatever.
BARRY:
So I hear you're quite a tennis player.
:
I'm not much for the game myself.
The ball's a little grabby.
KEN:
That's where I usually sit.
Right...
(Points to where Barry is sitting)
there.
VANESSA:
(Calling from other room)
Ken, Barry was looking at your resume,
:
and he agreed with me that eating with
chopsticks isn't really a special skill.
KEN:
(To Barry)
You think I don't see what you're doing?
BARRY:
I know how hard it is to find
the right job. We have that in common.

KEN:
Do we?
BARRY:
Bees have 100 percent employment,
but we do jobs like taking the crud out.
KEN:
(Menacingly)
That's just what
I was thinking about doing.
(Ken reaches for a fork on the table but knocks if on the floor. He goes to
pick it up)
VANESSA:
Ken, I let Barry borrow your razor
for his fuzz. I hope that was all right.
(Ken quickly rises back up after hearing this but hits his head on the
table and yells)
BARRY:
I'm going to drain the old stinger.
KEN:
Yeah, you do that.
(Barry flies past Ken to get to the bathroom and Ken freaks out, splashing
some of the wine he was using to cool his head in his eyes. He yells in
anger)
(Barry looks at the magazines featuring his victories in court)
BARRY:
Look at that.
(Barry flies into the bathroom)
(He puts his hand on his head but this makes hurts him and makes him even
madder. He yells again)
(Barry is washing his hands in the sink but then Ken walks in)
KEN:
You know, you know I've just about had it
(Closes bathroom door behind him)
with your little mind games.
(Ken is menacingly rolling up a magazine)
BARRY:

(Backing away)
- What's that?
KEN:
- Italian Vogue.
BARRY:
Mamma mia, that's a lot of pages.
KEN:
It's a lot of ads.
BARRY:
Remember what Van said, why is
your life more valuable than mine?
KEN:
That's funny, I just can't seem to recall that!
(Ken smashes everything off the sink with the magazine and Barry narrowly
escapes)
(Ken follows Barry around and tries to hit him with the magazine but he
keeps missing)
(Ken gets a spray bottle)
:
I think something stinks in here!
BARRY:
(Enjoying the spray)
I love the smell of flowers.
(Ken holds a lighter in front of the spray bottle)
KEN:
How do you like the smell of flames?!
BARRY:
Not as much.
(Ken fires his make-shift flamethrower but misses Barry, burning the
bathroom. He torches the whole room but looses his footing and falls into
the bathtub. After getting hit in the head by falling objects 3 times he
picks up the shower head, revealing a Water bug hiding under it)
WATER BUG:
Water bug! Not taking sides!

(Barry gets up out of a pile of bathroom supplies and he is wearing a
chapstick hat)
BARRY:
Ken, I'm wearing a Chapstick hat!
This is pathetic!
(Ken switches the shower head to lethal)
KEN:
I've got issues!
(Ken sprays Barry with the shower head and he crash lands into the toilet)
(Ken menacingly looks down into the toilet at Barry)
Well, well, well, a royal flush!
BARRY:
- You're bluffing.
KEN:
- Am I?
(flushes toilet)
(Barry grabs a chapstick from the toilet seat and uses it to surf in the
flushing toilet)
BARRY:
Surf's up, dude!
(Barry flies out of the toilet on the chapstick and sprays Ken's face with
the toilet water)
:
EW,Poo water!
BARRY:
That bowl is gnarly.
KEN:
(Aiming a toilet cleaner at Barry)
Except for those dirty yellow rings!
(Barry cowers and covers his head and Vanessa runs in and takes the toilet
cleaner from Ken just before he hits Barry)
VANESSA:
Kenneth! What are you doing?!
KEN==
(Leaning towards Barry)

You know, I don't even like honey!
I don't eat it!
VANESSA:
We need to talk!
(Vanessa pulls Ken out of the bathroom)
:
He's just a little bee!
:
And he happens to be
the nicest bee I've met in a long time!
KEN:
Long time? What are you talking about?!
Are there other bugs in your life?
VANESSA:
No, but there are other things bugging
me in life. And you're one of them!
KEN:
Fine! Talking bees, no yogurt night...
:
My nerves are fried from riding
on this emotional roller coaster!
VANESSA:
Goodbye, Ken.
(Ken huffs and walks out and slams the door. But suddenly he walks back in
and stares at Barry)
:
And for your information,
I prefer sugar-free, artificial
sweeteners MADE BY MAN!
(Ken leaves again and Vanessa leans in towards Barry)
VANESSA:
I'm sorry about all that.
(Ken walks back in again)

KEN:
I know it's got
an aftertaste! I LIKE IT!
(Ken leaves for the last time)
VANESSA:
I always felt there was some kind
of barrier between Ken and me.
:
I couldn't overcome it.
Oh, well.
:
Are you OK for the trial?
BARRY:
I believe Mr. Montgomery
is about out of ideas.
(Flash forward in time and Barry, Adam, and Vanessa are back in court)
MONTGOMERY--
We would like to call
Mr. Barry Benson Bee to the stand.
ADAM:
Good idea! You can really see why he's
considered one of the best lawyers...
(Barry stares at Adam)
...Yeah.
LAWYER:
Layton, you've
gotta weave some magic
with this jury,
or it's gonna be all over.
MONTGOMERY:
Don't worry. The only thing I have
to do to turn this jury around
:
is to remind them
of what they don't like about bees.
(To lawyer)

- You got the tweezers?
LAWYER:
- Are you allergic?
MONTGOMERY:
Only to losing, son. Only to losing.
:
Mr. Benson Bee, I'll ask you
what I think we'd all like to know.
:
What exactly is your relationship
(Points to Vanessa)
:
to that woman?
BARRY:
We're friends.
MONTGOMERY:
- Good friends?
BARRY:
- Yes.
MONTGOMERY:
How good? Do you live together?
ADAM:
Wait a minute...
:
MONTGOMERY:
Are you her little...
:
...bedbug?
(Adam's stinger starts vibrating. He is agitated)
I've seen a bee documentary or two.
From what I understand,

:
doesn't your queen give birth
to all the bee children?
BARRY:
- Yeah, but...
MONTGOMERY:
(Pointing at Janet and Martin)
- So those aren't your real parents!
JANET:
- Oh, Barry...
BARRY:
- Yes, they are!
ADAM:
Hold me back!
(Vanessa tries to hold Adam back. He wants to sting Montgomery)
MONTGOMERY:
You're an illegitimate bee,
aren't you, Benson?
ADAM:
He's denouncing bees!
MONTGOMERY:
Don't y'all date your cousins?
(Montgomery leans over on the jury stand and stares at Adam)
VANESSA:
- Objection!
(Vanessa raises her hand to object but Adam gets free. He flies straight at
Montgomery)
=ADAM:
- I'm going to pincushion this guy!
BARRY:
Adam, don't! It's what he wants!
(Adam stings Montgomery in the butt and he starts thrashing around)

MONTGOMERY:
Oh, I'm hit!!
:
Oh, lordy, I am hit!
JUDGE BUMBLETON:
(Banging gavel)
Order! Order!
MONTGOMERY:
(Overreacting)
The venom! The venom
is coursing through my veins!
:
I have been felled
by a winged beast of destruction!
:
You see? You can't treat them
like equals! They're striped savages!
:
Stinging's the only thing
they know! It's their way!
BARRY:
- Adam, stay with me.
ADAM:
- I can't feel my legs.
MONTGOMERY:
(Overreacting and throwing his body around the room)
What angel of mercy
will come forward to suck the poison
:
from my heaving buttocks?
JUDGE BUMLBETON:
I will have order in this court. Order!

:
Order, please!
(Flash forward in time and we see a human news reporter)
NEWS REPORTER:
The case of the honeybees
versus the human race
:
took a pointed turn against the bees
:
yesterday when one of their legal
team stung Layton T. Montgomery.
(Adam is laying in a hospital bed and Barry flies in to see him)
BARRY:
- Hey, buddy.
ADAM:
- Hey.
BARRY:
- Is there much pain?
ADAM:
- Yeah.
:
I...
:
I blew the whole case, didn't I?
BARRY:
It doesn't matter. What matters is
you're alive. You could have died.
ADAM:
I'd be better off dead. Look at me.
(A small plastic sword is replaced as Adam's stinger)
They got it from the cafeteria
downstairs, in a tuna sandwich.

:
Look, there's
a little celery still on it.
(Flicks off the celery and sighs)
BARRY:
What was it like to sting someone?
ADAM:
I can't explain it. It was all...
:
All adrenaline and then...
and then ecstasy!
BARRY:
...All right.
ADAM:
You think it was all a trap?
BARRY:
Of course. I'm sorry.
I flew us right into this.
:
What were we thinking? Look at us. We're
just a couple of bugs in this world.
ADAM:
What will the humans do to us
if they win?
BARRY:
I don't know.
ADAM:
I hear they put the roaches in motels.
That doesn't sound so bad.
BARRY:
Adam, they check in,
but they don't check out!

ADAM:
Oh, my.
(Coughs)
Could you get a nurse
to close that window?
BARRY:
- Why?
ADAM:
- The smoke.
(We can see that two humans are smoking cigarettes outside)
:
Bees don't smoke.
BARRY:
Right. Bees don't smoke.
:
Bees don't smoke!
But some bees are smoking.
:
That's it! That's our case!
ADAM:
It is? It's not over?
BARRY:
Get dressed. I've gotta go somewhere.
:
Get back to the court and stall.
Stall any way you can.
(Flash forward in time and Adam is making a paper boat in the courtroom)
ADAM:
And assuming you've done step 29 correctly, you're ready for the tub!
(We see that the jury have each made their own paper boats after being
taught how by Adam. They all look confused)
JUDGE BUMBLETON:

Mr. Flayman.
ADAM:
Yes? Yes, Your Honor!
JUDGE BUMBLETON:
Where is the rest of your team?
ADAM:
(Continues stalling)
Well, Your Honor, it's interesting.
:
Bees are trained to fly haphazardly,
:
and as a result,
we don't make very good time.
:
I actually heard a funny story about...
MONTGOMERY:
Your Honor,
haven't these ridiculous bugs
:
taken up enough
of this court's valuable time?
:
How much longer will we allow
these absurd shenanigans to go on?
:
They have presented no compelling
evidence to support their charges
:
against my clients,
who run legitimate businesses.
:
I move for a complete dismissal

of this entire case!
JUDGE BUMBLETON:
Mr. Flayman, I'm afraid I'm going
:
to have to consider
Mr. Montgomery's motion.
ADAM:
But you can't! We have a terrific case.
MONTGOMERY:
Where is your proof?
Where is the evidence?
:
Show me the smoking gun!
BARRY:
(Barry flies in through the door)
Hold it, Your Honor!
You want a smoking gun?
:
Here is your smoking gun.
(Vanessa walks in holding a bee smoker. She sets it down on the Judge's
podium)
JUDGE BUMBLETON:
What is that?
BARRY:
It's a bee smoker!
MONTGOMERY:
(Picks up smoker)
What, this?
This harmless little contraption?
:
This couldn't hurt a fly,
let alone a bee.
(Montgomery accidentally fires it at the bees in the crowd and they faint

and cough)
(Dozens of reporters start taking pictures of the suffering bees)
BARRY:
Look at what has happened
:
to bees who have never been asked,
"Smoking or non?"
:
Is this what nature intended for us?
:
To be forcibly addicted
to smoke machines
:
and man-made wooden slat work camps?
:
Living out our lives as honey slaves
to the white man?
(Barry points to the honey industry owners. One of them is an African
American so he awkwardly separates himself from the others)
LAWYER:
- What are we gonna do?
- He's playing the species card.
BARRY:
Ladies and gentlemen, please,
free these bees!
ADAM AND VANESSA:
Free the bees! Free the bees!
BEES IN CROWD:
Free the bees!
HUMAN JURY:
Free the bees! Free the bees!
JUDGE BUMBLETON:
The court finds in favor of the bees!

BARRY:
Vanessa, we won!
VANESSA:
I knew you could do it! High-five!
(Vanessa hits Barry hard because her hand is too big)
:
Sorry.
BARRY:
(Overjoyed)
I'm OK! You know what this means?
:
All the honey
will finally belong to the bees.
:
Now we won't have
to work so hard all the time.
MONTGOMERY:
This is an unholy perversion
of the balance of nature, Benson.
:
You'll regret this.
(Montgomery leaves and Barry goes outside the courtroom. Several reporters
start asking Barry questions)
REPORTER 1#:
Barry, how much honey is out there?
BARRY:
All right. One at a time.
REPORTER 2#:
Barry, who are you wearing?
BARRY:
My sweater is Ralph Lauren,
and I have no pants.

(Barry flies outside with the paparazzi and Adam and Vanessa stay back)
ADAM:
(To Vanessa)
- What if Montgomery's right?
Vanessa:
- What do you mean?
ADAM:
We've been living the bee way
a long time, 27 million years.
(Flash forward in time and Barry is talking to a man)
BUSINESS MAN:
Congratulations on your victory.
What will you demand as a settlement?
BARRY:
First, we'll demand a complete shutdown
of all bee work camps.
(As Barry is talking we see a montage of men putting "closed" tape over the
work camps and freeing the bees in the crappy apartments)
Then we want back the honey
that was ours to begin with,
:
every last drop.
(Men in suits are pushing all the honey of the aisle and into carts)
We demand an end to the glorification
of the bear as anything more
(We see a statue of a bear-shaped honey container being pulled down by
bees)
than a filthy, smelly,
bad-breath stink machine.
:
We're all aware
of what they do in the woods.
(We see Winnie the Pooh sharing his honey with Piglet in the cross-hairs of
a high-tech sniper rifle)
BARRY:
(Looking through binoculars)

Wait for my signal.
:
Take him out.
(Winnie gets hit by a tranquilizer dart and dramatically falls off the log
he was standing on, his tongue hanging out. Piglet looks at Pooh in fear
and the Sniper takes the honey.)
SNIPER:
He'll have nausea
for a few hours, then he'll be fine.
(Flash forward in time)
BARRY:
And we will no longer tolerate
bee-negative nicknames...
(Mr. Sting is sitting at home until he is taken out of his house by the men
in suits)
STING:
But it's just a prance-about stage name!
BARRY:
...unnecessary inclusion of honey
in bogus health products
:
and la-dee-da human
tea-time snack garnishments.
(An old lady is mixing honey into her tea but suddenly men in suits smash
her face down on the table and take the honey)
OLD LADY:
Can't breathe.
(A honey truck pulls up to Barry's hive)
WORKER:
Bring it in, boys!
:
Hold it right there! Good.
:
Tap it.

(Tons of honey is being pumped into the hive's storage)
BEE WORKER 1#:
(Honey overflows from the cup)
Mr. Buzzwell, we just passed three cups,
and there's gallons more coming!
:
- I think we need to shut down!
=BEE WORKER #2=
- Shut down? We've never shut down.
:
Shut down honey production!
DEAN BUZZWELL:
Stop making honey!
(The bees all leave their stations. Two bees run into a room and they put
the keys into a machine)
Turn your key, sir!
(Two worker bees dramatically turn their keys, which opens the button which
they press, shutting down the honey-making machines. This is the first time
this has ever happened)
BEE:
...What do we do now?
(Flash forward in time and a Bee is about to jump into a pool full of
honey)
Cannonball!
(The bee gets stuck in the honey and we get a short montage of Bees leaving
work)
(We see the Pollen Jocks flying but one of them gets a call on his antenna)
LOU LU DUVA:
(Through "phone")
We're shutting honey production!
:
Mission abort.
POLLEN JOCK #1:
Aborting pollination and nectar detail.
Returning to base.
(The Pollen Jocks fly back to the hive)

(We get a time lapse of Central Park slowly wilting away as the bees all
relax)
BARRY:
Adam, you wouldn't believe
how much honey was out there.
ADAM:
Oh, yeah?
BARRY:
What's going on? Where is everybody?
(The entire street is deserted)
:
- Are they out celebrating?
ADAM:
- They're home.
:
They don't know what to do.
Laying out, sleeping in.
:
I heard your Uncle Carl was on his way
to San Antonio with a cricket.
BARRY:
At least we got our honey back.
ADAM:
Sometimes I think, so what if humans
liked our honey? Who wouldn't?
:
It's the greatest thing in the world!
I was excited to be part of making it.
:
This was my new desk. This was my
new job. I wanted to do it really well.
:

And now...
:
Now I can't.
(Flash forward in time and Barry is talking to Vanessa)
BARRY:
I don't understand
why they're not happy.
:
I thought their lives would be better!
:
They're doing nothing. It's amazing.
Honey really changes people.
VANESSA:
You don't have any idea
what's going on, do you?
BARRY:
- What did you want to show me?
(Vanessa takes Barry to the rooftop where they first had coffee and points
to her store)
VANESSA:
- This.
(Points at her flowers. They are all grey and wilting)
BARRY:
What happened here?
VANESSA:
That is not the half of it.
(Small flash forward in time and Vanessa and Barry are on the roof of her
store and she points to Central Park)
(We see that Central Park is no longer green and colorful, rather it is
grey, brown, and dead-like. It is very depressing to look at)
BARRY:
Oh, no. Oh, my.
:

They're all wilting.
VANESSA:
Doesn't look very good, does it?
BARRY:
No.
VANESSA:
And whose fault do you think that is?
BARRY:
You know, I'm gonna guess bees.
VANESSA==
(Staring at Barry)
Bees?
BARRY:
Specifically, me.
:
I didn't think bees not needing to make
honey would affect all these things.
VANESSA:
It's not just flowers.
Fruits, vegetables, they all need bees.
BARRY:
That's our whole SAT test right there.
VANESSA:
Take away produce, that affects
the entire animal kingdom.
:
And then, of course...
BARRY:
The human species?
:
So if there's no more pollination,

:
it could all just go south here,
couldn't it?
VANESSA:
I know this is also partly my fault.
BARRY:
How about a suicide pact?
VANESSA:
How do we do it?
BARRY:
- I'll sting you, you step on me.
VANESSA:
- That just kills you twice.
BARRY:
Right, right.
VANESSA:
Listen, Barry...
sorry, but I gotta get going.
(Vanessa leaves)
BARRY:
(To himself)
I had to open my mouth and talk.
:
Vanessa?
:
Vanessa? Why are you leaving?
Where are you going?
(Vanessa is getting into a taxi)
VANESSA:
To the final Tournament of Roses parade
in Pasadena.
:

They've moved it to this weekend
because all the flowers are dying.
:
It's the last chance
I'll ever have to see it.
BARRY:
Vanessa, I just wanna say I'm sorry.
I never meant it to turn out like this.
VANESSA:
I know. Me neither.
(The taxi starts to drive away)
BARRY:
Tournament of Roses.
Roses can't do sports.
:
Wait a minute. Roses. Roses?
:
Roses!
:
Vanessa!
(Barry flies after the Taxi)
VANESSA:
Roses?!
:
Barry?
(Barry is flying outside the window of the taxi)
BARRY:
- Roses are flowers!
VANESSA:
- Yes, they are.
BARRY:
Flowers, bees, pollen!

VANESSA:
I know.
That's why this is the last parade.
BARRY:
Maybe not.
Could you ask him to slow down?
VANESSA:
Could you slow down?
(The taxi driver screeches to a stop and Barry keeps flying forward)
:
Barry!
(Barry flies back to the window)
BARRY:
OK, I made a huge mistake.
This is a total disaster, all my fault.
VANESSA:
Yes, it kind of is.
BARRY:
I've ruined the planet.
I wanted to help you
:
with the flower shop.
I've made it worse.
VANESSA:
Actually, it's completely closed down.
BARRY:
I thought maybe you were remodeling.
:
But I have another idea, and it's
greater than my previous ideas combined.
VANESSA:
I don't want to hear it!

BARRY:
All right, they have the roses,
the roses have the pollen.
:
I know every bee, plant
and flower bud in this park.
:
All we gotta do is get what they've got
back here with what we've got.
:
- Bees.
VANESSA:
- Park.
BARRY:
- Pollen!
VANESSA:
- Flowers.
BARRY:
- Re-pollination!
VANESSA:
- Across the nation!
:
Tournament of Roses,
Pasadena, California.
:
They've got nothing
but flowers, floats and cotton candy.
:
Security will be tight.
BARRY:
I have an idea.

(Flash forward in time. Vanessa is about to board a plane which has all the
Roses on board.
VANESSA:
Vanessa Bloome, FTD.
(Holds out badge)
:
Official floral business. It's real.
SECURITY GUARD:
Sorry, ma'am. Nice brooch.
=VANESSA==
Thank you. It was a gift.
(Barry is revealed to be hiding inside the brooch)
(Flash back in time and Barry and Vanessa are discussing their plan)
BARRY:
Once inside,
we just pick the right float.
VANESSA:
How about The Princess and the Pea?
:
I could be the princess,
and you could be the pea!
BARRY:
Yes, I got it.
:
- Where should I sit?
GUARD:
- What are you?
BARRY:
- I believe I'm the pea.
GUARD:
- The pea?
VANESSA:

It goes under the mattresses.
GUARD:
- Not in this fairy tale, sweetheart.
- I'm getting the marshal.
VANESSA:
You do that!
This whole parade is a fiasco!
:
Let's see what this baby'll do.
(Vanessa drives the float through traffic)
GUARD:
Hey, what are you doing?!
BARRY==
Then all we do
is blend in with traffic...
:
...without arousing suspicion.
:
Once at the airport,
there's no stopping us.
(Flash forward in time and Barry and Vanessa are about to get on a plane)
SECURITY GUARD:
Stop! Security.
:
- You and your insect pack your float?
VANESSA:
- Yes.
SECURITY GUARD:
Has it been
in your possession the entire time?
VANESSA:
- Yes.

SECURITY GUARD:
Would you remove your shoes?
(To Barry)
- Remove your stinger.
BARRY:
- It's part of me.
SECURITY GUARD:
I know. Just having some fun.
Enjoy your flight.
(Barry plotting with Vanessa)
BARRY:
Then if we're lucky, we'll have
just enough pollen to do the job.
(Flash forward in time and Barry and Vanessa are flying on the plane)
Can you believe how lucky we are? We
have just enough pollen to do the job!
VANESSA:
I think this is gonna work.
BARRY:
It's got to work.
CAPTAIN SCOTT:
(On intercom)
Attention, passengers,
this is Captain Scott.
:
We have a bit of bad weather
in New York.
:
It looks like we'll experience
a couple hours delay.
VANESSA:
Barry, these are cut flowers
with no water. They'll never make it.
BARRY:

I gotta get up there
and talk to them.
VANESSA==
Be careful.
(Barry flies right outside the cockpit door)
BARRY:
Can I get help
with the Sky Mall magazine?
I'd like to order the talking
inflatable nose and ear hair trimmer.
(The flight attendant opens the door and walks out and Barry flies into the
cockpit unseen)
BARRY:
Captain, I'm in a real situation.
CAPTAIN SCOTT:
- What'd you say, Hal?
CO-PILOT HAL:
- Nothing.
(Scott notices Barry and freaks out)
CAPTAIN SCOTT:
Bee!
BARRY:
No,no,no, Don't freak out! My entire species...
(Captain Scott gets out of his seat and tries to suck Barry into a handheld
vacuum)
HAL:
(To Scott)
What are you doing?
(Barry lands on Hals hair but Scott sees him. He tries to suck up Barry but
instead he sucks up Hals toupee)
CAPTAIN SCOTT:
Uh-oh.
BARRY:
- Wait a minute! I'm an attorney!

HAL:
(Hal doesn't know Barry is on his head)
- Who's an attorney?
CAPTAIN SCOTT:
Don't move.
(Scott hits Hal in the face with the vacuum in an attempt to hit Barry. Hal
is knocked out and he falls on the life raft button which launches an
infalatable boat into Scott, who gets knocked out and falls to the floor.
They are both uncounscious.)
BARRY:
(To himself)
Oh, Barry.
BARRY:
(On intercom, with a Southern accent)
Good afternoon, passengers.
This is your captain.
:
Would a Miss Vanessa Bloome in 24B
please report to the cockpit?
(Vanessa looks confused)
(Normal accent)
...And please hurry!
(Vanessa opens the door and sees the life raft and the uncounscious pilots)
VANESSA:
What happened here?
BARRY:
I tried to talk to them, but
then there was a DustBuster,
a toupee, a life raft exploded.
:
Now one's bald, one's in a boat,
and they're both unconscious!
VANESSA:
...Is that another bee joke?
BARRY:

- No!
:
No one's flying the plane!
BUD DITCHWATER:
(Through radio on plane)
This is JFK control tower, Flight 356.
What's your status?
VANESSA:
This is Vanessa Bloome.
I'm a florist from New York.
BUD:
Where's the pilot?
VANESSA:
He's unconscious,
and so is the copilot.
BUD:
Not good. Does anyone onboard
have flight experience?
BARRY:
As a matter of fact, there is.
BUD:
- Who's that?
BARRY:
- Barry Benson.
BUD:
From the honey trial?! Oh, great.
BARRY:
Vanessa, this is nothing more
than a big metal bee.
:
It's got giant wings, huge engines.

VANESSA:
I can't fly a plane.
BARRY:
- Why not? Isn't John Travolta a pilot?
VANESSA:
- Yes.
BARRY:
How hard could it be?
(Vanessa sits down and flies for a little bit but we see lightning clouds
outside the window)
VANESSA:
Wait, Barry!
We're headed into some lightning.
(An ominous lightning storm looms in front of the plane)
(We are now watching the Bee News)
BOB BUMBLE:
This is Bob Bumble. We have some
late-breaking news from JFK Airport,
:
where a suspenseful scene
is developing.
:
Barry Benson,
fresh from his legal victory...
ADAM:
That's Barry!
BOB BUMBLE:
...is attempting to land a plane,
loaded with people, flowers
:
and an incapacitated flight crew.
JANET, MARTIN, UNCLE CAR AND ADAM:
Flowers?!
(The scene switches to the human news)

REPORTER:
(Talking with Bob Bumble)
We have a storm in the area
and two individuals at the controls
:
with absolutely no flight experience.
BOB BUMBLE:
Just a minute.
There's a bee on that plane.
BUD:
I'm quite familiar with Mr. Benson
and his no-account compadres.
:
They've done enough damage.
REPORTER:
But isn't he your only hope?
BUD:
Technically, a bee
shouldn't be able to fly at all.
:
Their wings are too small...
BARRY:
(Through radio)
Haven't we heard this a million times?
:
"The surface area of the wings
and body mass make no sense."...
BOB BUMBLE:
- Get this on the air!
BEE:
- Got it.

BEE NEWS CREW:
- Stand by.
BEE NEWS CREW:
- We're going live!
BARRY:
(Through radio on TV)
...The way we work may be a mystery to you.
:
Making honey takes a lot of bees
doing a lot of small jobs.
:
But let me tell you about a small job.
:
If you do it well,
it makes a big difference.
:
More than we realized.
To us, to everyone.
:
That's why I want to get bees
back to working together.
:
That's the bee way!
We're not made of Jell-O.
:
We get behind a fellow.
:
- Black and yellow!
BEES:
- Hello!
(The scene switches and Barry is teaching Vanessa how to fly)
BARRY:

Left, right, down, hover.
VANESSA:
- Hover?
BARRY:
- Forget hover.
VANESSA:
This isn't so hard.
(Pretending to honk the horn)
Beep-beep! Beep-beep!
(A Lightning bolt hits the plane and autopilot turns off)
Barry, what happened?!
BARRY:
Wait, I think we were
on autopilot the whole time.
VANESSA:
- That may have been helping me.
BARRY:
- And now we're not!
VANESSA:
So it turns out I cannot fly a plane.
(The plane plummets but we see Lou Lu Duva and the Pollen Jocks, along with
multiple other bees flying towards the plane)
Lou Lu DUva:
All of you, let's get
behind this fellow! Move it out!
:
Move out!
(The scene switches back to Vanessa and Barry in the plane)
BARRY:
Our only chance is if I do what I'd do,
you copy me with the wings of the plane!
(Barry sticks out his arms like an airplane and flys in front of Vanessa's
face)

VANESSA:
Don't have to yell.
BARRY:
I'm not yelling!
We're in a lot of trouble.
VANESSA:
It's very hard to concentrate
with that panicky tone in your voice!
BARRY:
It's not a tone. I'm panicking!
VANESSA:
I can't do this!
(Barry slaps Vanessa)
BARRY:
Vanessa, pull yourself together.
You have to snap out of it!
VANESSA:
(Slaps Barry)
You snap out of it.
BARRY:
(Slaps Vanessa)
:
You snap out of it.
VANESSA:
- You snap out of it!
BARRY:
- You snap out of it!
(We see that all the Pollen Jocks are flying under the plane)
VANESSA:
- You snap out of it!
BARRY:
- You snap out of it!

VANESSA:
- You snap out of it!
BARRY:
- You snap out of it!
VANESSA:
- Hold it!
BARRY:
- Why? Come on, it's my turn.
VANESSA:
How is the plane flying?
(The plane is now safely flying)
VANESSA:
I don't know.
(Barry's antennae rings like a phone. Barry picks up)
BARRY:
Hello?
LOU LU DUVA:
(Through "phone")
Benson, got any flowers
for a happy occasion in there?
(All of the Pollen Jocks are carrying the plane)
BARRY:
The Pollen Jocks!
:
They do get behind a fellow.
LOU LU DUVA:
- Black and yellow.
POLLEN JOCKS:
- Hello.
LOU LU DUVA:
All right, let's drop this tin can

on the blacktop.
BARRY:
Where? I can't see anything. Can you?
VANESSA:
No, nothing. It's all cloudy.
:
Come on. You got to think bee, Barry.
BARRY:
- Thinking bee.
- Thinking bee.
(On the runway there are millions of bees laying on their backs)
BEES:
Thinking bee!
Thinking bee! Thinking bee!
BARRY:
Wait a minute.
I think I'm feeling something.
VANESSA:
- What?
BARRY:
- I don't know. It's strong, pulling me.
:
Like a 27-million-year-old instinct.
:
Bring the nose down.
BEES:
Thinking bee!
Thinking bee! Thinking bee!
CONTROL TOWER OPERATOR:
- What in the world is on the tarmac?
BUD:
- Get some lights on that!

(It is revealed that all the bees are organized into a giant pulsating
flower formation)
BEES:
Thinking bee!
Thinking bee! Thinking bee!
BARRY:
- Vanessa, aim for the flower.
VANESSA:
- OK.
BARRY:
Out the engines. We're going in
on bee power. Ready, boys?
LOU LU DUVA:
Affirmative!
BARRY:
Good. Good. Easy, now. That's it.
:
Land on that flower!
:
Ready? Full reverse!
:
Spin it around!
(The plane's nose is pointed at a flower painted on a nearby plane)
- Not that flower! The other one!
VANESSA:
- Which one?
BARRY:
- That flower.
(The plane is now pointed at a fat guy in a flowered shirt. He freaks out
and tries to take a picture of the plane)
VANESSA:
- I'm aiming at the flower!

BARRY:
That's a fat guy in a flowered shirt.
I mean the giant pulsating flower
made of millions of bees!
(The plane hovers over the bee-flower)
:
Pull forward. Nose down. Tail up.
:
Rotate around it.
VANESSA:
- This is insane, Barry!
BARRY:
- This's the only way I know how to fly.
BUD:
Am I koo-koo-kachoo, or is this plane
flying in an insect-like pattern?
(The plane is unrealistically hovering and spinning over the bee-flower)
BARRY:
Get your nose in there. Don't be afraid.
Smell it. Full reverse!
:
Just drop it. Be a part of it.
:
Aim for the center!
:
Now drop it in! Drop it in, woman!
:
Come on, already.
(The bees scatter and the plane safely lands)
VANESSA:
Barry, we did it!
You taught me how to fly!

BARRY:
- Yes!
(Vanessa is about to high-five Barry)
No high-five!
VANESSA:
- Right.
ADAM:
Barry, it worked!
Did you see the giant flower?
BARRY:
What giant flower? Where? Of course
I saw the flower! That was genius!
ADAM:
- Thank you.
BARRY:
- But we're not done yet.
:
Listen, everyone!
:
This runway is covered
with the last pollen
:
from the last flowers
available anywhere on Earth.
:
That means this is our last chance.
:
We're the only ones who make honey,
pollinate flowers and dress like this.
:
If we're gonna survive as a species,
this is our moment! What do you say?

:
Are we going to be bees, or just
Museum of Natural History keychains?
BEES:
We're bees!
BEE WHO LIKES KEYCHAINS:
Keychain!
BARRY:
Then follow me! Except Keychain.
POLLEN JOCK #1:
Hold on, Barry. Here.
:
You've earned this.
BARRY:
Yeah!
:
I'm a Pollen Jock! And it's a perfect
fit. All I gotta do are the sleeves.
(The Pollen Jocks throw Barry a nectar-collecting gun. Barry catches it)
Oh, yeah.
JANET:
That's our Barry.
(Barry and the Pollen Jocks get pollen from the flowers on the plane)
(Flash forward in time and the Pollen Jocks are flying over NYC)
:
(Barry pollinates the flowers in Vanessa's shop and then heads to Central
Park)
BOY IN PARK:
Mom! The bees are back!
ADAM:
(Putting on his Krelman hat)
If anybody needs

to make a call, now's the time.
:
I got a feeling we'll be
working late tonight!
(The bee honey factories are back up and running)
(Meanwhile at Vanessa's shop)
VANESSA:
(To customer)
Here's your change. Have a great
afternoon! Can I help who's next?
:
Would you like some honey with that?
It is bee-approved. Don't forget these.
(There is a room in the shop where Barry does legal work for other animals.
He is currently talking with a Cow)
COW:
Milk, cream, cheese, it's all me.
And I don't see a nickel!
:
Sometimes I just feel
like a piece of meat!
BARRY:
I had no idea.
VANESSA:
Barry, I'm sorry.
Have you got a moment?
BARRY:
Would you excuse me?
My mosquito associate will help you.
MOOSEBLOOD:
Sorry I'm late.
COW:
He's a lawyer too?

MOOSEBLOOD:
Ma'am, I was already a blood-sucking parasite.
All I needed was a briefcase.
VANESSA:
Have a great afternoon!
:
Barry, I just got this huge tulip order,
and I can't get them anywhere.
BARRY:
No problem, Vannie.
Just leave it to me.
VANESSA:
You're a lifesaver, Barry.
Can I help who's next?
BARRY:
All right, scramble, jocks!
It's time to fly.
VANESSA:
Thank you, Barry!
(Ken walks by on the sidewalk and sees the "bee-approved honey" in
Vanessa's shop)
KEN:
That bee is living my life!!
ANDY:
Let it go, Kenny.
KEN:
- When will this nightmare end?!
ANDY:
- Let it all go.
BARRY:
- Beautiful day to fly.
POLLEN JOCK:

- Sure is.
BARRY:
Between you and me,
I was dying to get out of that office.
(Barry recreates the scene near the beginning of the movie where he flies
through the box kite. The movie fades to black and the credits being)
[--after credits; No scene can be seen but the characters can be heard
talking over the credits--]
You have got
to start thinking bee, my friend!
:
- Thinking bee!
- Me?
BARRY:
(Talking over singer)
Hold it. Let's just stop
for a second. Hold it.
:
I'm sorry. I'm sorry, everyone.
Can we stop here?
SINGER:
Oh, BarryBARRY:
I'm not making a major life decision
during a production number!
SINGER:
All right. Take ten, everybody.
Wrap it up, guys.
BARRY:
I had virtually no rehearsal for that.

CSC/ECE 517 Fall 2024

2024-10-28T23:00:16Z

Wagrocho: Add 2480 - Implement testing for new Bookmarks Controller

* [[CSC/ECE 517 Fall 2024 - E2454. Refactor student_task.rb]]
* [[CSC/ECE 517 Fall 2024 - E2456. Refactor teams_user.rb]]
* [[CSC/ECE 517 Fall 2024 - E2459. View for results of bidding]]
* [[CSC/ECE 517 Fall 2024 - E2461. UI for Courses]]
* [[CSC/ECE 517 Fall 2024 - E2465. UI for Institutions and Notification]]
* [[CSC/ECE 517 Fall 2024 - E2466. UI for Impersonate User]]
* [[CSC/ECE 517 Fall 2024 - E2467. UI for View Submissions]]
* [[CSC/ECE 517 Fall 2024 - E2469. Reimplement grades/view_team]]
* [[CSC/ECE 517 Fall 2024 - E2480. Implement testing for new Bookmarks Controller]]
* [[CSC/ECE 517 Fall 2024 - E2482. Reimplement heatgrid for reviews]]

Broken Links

2024-10-28T22:25:13Z

Wagrocho: Updated the list with all other links on Expertiza_documentation

The goal of this page is to note broken links so they can be fixed. If adding an entry to the table, add the wiki page and header the link can be found in, the broken link and the link text, and note what is broken with the link (404, now redirects to a different site, etc.)

{| class="wikitable" style="margin:auto"
|+ Broken Links
|-
! Wiki Page !! Broken Link !! Notes
|-
| [[Expertiza_documentation#Short Powerpoint introductions]] ||[[https://research.csc.ncsu.edu/efg/expertiza/presentations/ELI_11_wiki_textbook.ppt presentation]] || 404
|-
| [[Expertiza_documentation#Short Powerpoint introductions]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/Purdue_TLT_2009.ppt plenary talk]] || 404
|-
| [[Expertiza_documentation#Short Powerpoint introductions]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza-short.htm rationale]] || 404
|-
| [[Expertiza_documentation#Short Powerpoint introductions]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza%20in%20Action.ppt virtual demo]] || 404
|-
| [[Expertiza_documentation#Papers]] || [[https://innovateonline.info/index.php?view=article&id=365 prose rendition]] || 404
|-
| [[Expertiza_documentation#Papers]] || [[http://innovateonline.info/ Innovate]] || redirects to [[https://onlinegraduateprograms.net/ onlinegraduateprograms.net]]
|-
| [[Expertiza_documentation#Papers]] || [[https://research.csc.ncsu.edu/efg/expertiza/papers/ here]] || 404
|-
| [[Expertiza_documentation#Video presentations]] || [[http://connectpro86502729.na6.acrobat.com/p99048610/ overview]] || times out
|-
| [[Expertiza_documentation#Video presentations]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/TLT_Live.ppt (slides)]] || 404
|-
| [[Expertiza_documentation#Video presentations]] || [[https://sas.elluminate.com/site/external/recording/playback/link/dropin.jnlp?sid=2008350&suid=D.2D2E269EE524FD263F89DA6872A41E Student-authored wiki textbooks: Composition and review]] || site can't be reached
|-
| [[Expertiza_documentation#Video presentations]] || [[http://educause.mediasite.com/mediasite/SilverlightPlayer/Default.aspx?peid=cdeebca6d1a34610923bcabd4c2d2fd91d session from EDUCAUSE ELI 2011]] || Site loads, but displays "No compatible source was found for this media.". Site might be using Silverlight to stream, which is EOL.
|-
| [[Expertiza_documentation#Video presentations]] || [[http://breeze.uliveandlearn.com/p10263667/ Webcast]] || 404
|-
| [[Expertiza_documentation#Video presentations]] || [[http://www.youtube.com/watch?v=hVpS7qvC5Zs interview]] || Video unavailable (posting account has been terminated)
|-
| [[Expertiza_documentation#Video presentations]] || [[http://breeze.uliveandlearn.com/p84785847/ Ideagora]] || 404
|-
| [[Expertiza_documentation#Video presentations]] || [[https://sas.elluminate.com/site/external/jwsdetect/playback.jnlp?psid=2009-03-17.1032.M.F13AAE88367AEE982449E713075D42.vcr Forming and managing student teams and peer feedback in Expertiza]] || site can't be reached
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/reports/Instructor_documentation.doc instructor manual]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/videos/instructor.swf instructor video]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[http://rajanalwan.com/ui_guidelines/ design document]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/student_documentation.ppt Powerpoint]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/student_documentation.pdf PDF]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[http://research.csc.ncsu.edu/efg/expertiza/presentations/videos/student.swf video]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/student_wiki_documentation.ppt Powerpoint]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://research.csc.ncsu.edu/efg/expertiza/presentations/student_wiki_documentation.pdf PDF]] || 404
|-
| [[Expertiza_documentation#Documentation]] || [[https://courses.ncsu.edu/csc517/common/homework/topic-signup-team-formation.ppt Powerpoint]] || site can't be reached
|-
| [[Expertiza_documentation#Documentation]] || [[https://courses.ncsu.edu/csc517/common/homework/topic-signup-team-formation.pdf PDF]] || site can't be reached
|-
| [[Expertiza_documentation#Developers section]] || [[https://drive.google.com/a/ncsu.edu/file/d/0B2vDvVjH76uEUmNKVncxRUhUVVE/view?usp=sharing Download the VirtualBox Ubuntu image here]] || Sorry, the file you have requested does not exist
|-
| [[Expertiza_documentation#Links]] || [[https://research.csc.ncsu.edu/efg/expertiza/papers Papers on Expertiza]] || 404
|-
| [[Expertiza_documentation#Links]] || [[http://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza-short.htm PowerPoint Presentation - The Expertiza platform]] || 404
|}

Broken Links

2024-10-26T17:06:30Z

Wagrocho: added a few more links under video presentations

Expertiza documentation

2024-10-26T16:56:27Z

Wagrocho: Added a link to the "Broken Links" page under Misc

[[Image:715px-EXPERTIZA.png|715px]]

= Welcome to the Expertiza project! =

The Expertiza project is software to create reusable learning objects through peer review. It also supports team projects, and the submission of almost any document type, including URLs and wiki pages.

== Short Powerpoint introductions ==
*My [http://research.csc.ncsu.edu/efg/expertiza/presentations/ELI_11_wiki_textbook.ppt presentation] on using Expertiza to support wiki-textbook creation, at the 2011 EDUCAUSE Learning Initiative conference, February 15, 2011
*My [http://research.csc.ncsu.edu/efg/expertiza/presentations/Purdue_TLT_2009.ppt plenary talk] at the Purdue TLT Conference on April 22, 2009
*We invite you to view the original [http://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza-short.htm rationale] for the system.
*You can walk through a [http://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza%20in%20Action.ppt virtual demo] of the system.

== Papers ==
*A [http://innovateonline.info/index.php?view=article&id=365 prose rendition] of the rationale was published in [http://innovateonline.info/ Innovate] in 2007. (To view it, you need to register, and you will receive e-mail each time a new issue of this very interesting and useful journal is published.)
*Other papers on Expertiza can be found [http://research.csc.ncsu.edu/efg/expertiza/papers/ here].

== Video presentations ==

*An [http://connectpro86502729.na6.acrobat.com/p99048610/ overview] of Expertiza ("Software support for teamwork and authentic assessment [http://research.csc.ncsu.edu/efg/expertiza/presentations/TLT_Live.ppt (slides)]") from the TLT Group's Friday Live, September 24, 2010
*[https://sas.elluminate.com/site/external/recording/playback/link/dropin.jnlp?sid=2008350&suid=D.2D2E269EE524FD263F89DA6872A41E Student-authored wiki textbooks: Composition and review] from the 2011 Global Education Consortium, November 18, 2011
*This [http://educause.mediasite.com/mediasite/SilverlightPlayer/Default.aspx?peid=cdeebca6d1a34610923bcabd4c2d2fd91d session from EDUCAUSE ELI 2011] describes how Expertiza can be used to review wiki-textbook contributions. It is an earlier version of the presentation above that includes a live demo.
*This Innovate [http://breeze.uliveandlearn.com/p10263667/ Webcast] from July 2007 includes the rationale and a demo of the system.
*A six-minute [http://www.youtube.com/watch?v=hVpS7qvC5Zs interview] from the 2009 Lilly Conference on College Teaching describes the goals and realization of the project. (Note: Background noise may be distracting.)
*This Innovate [http://breeze.uliveandlearn.com/p84785847/ Ideagora] discussion from January 2009 describes the social-networking features planned for Expertiza.
*[https://sas.elluminate.com/site/external/jwsdetect/playback.jnlp?psid=2009-03-17.1032.M.F13AAE88367AEE982449E713075D42.vcr Forming and managing student teams and peer feedback in Expertiza], a presentation at the UNC TLT conference in March 2009.

== Documentation ==

*An [http://research.csc.ncsu.edu/efg/expertiza/reports/Instructor_documentation.doc instructor manual], explaining how to create an deploy an assignment in Expertiza.
*An [http://research.csc.ncsu.edu/efg/expertiza/presentations/videos/instructor.swf instructor video], slightly dated, showing how to create and deploy an assignment
*A [http://rajanalwan.com/ui_guidelines/ design document] for the application.
* A guide for [[Creating_Custom_Rubric]]
*For students, a [http://research.csc.ncsu.edu/efg/expertiza/presentations/student_documentation.ppt Powerpoint] or [http://research.csc.ncsu.edu/efg/expertiza/presentations/student_documentation.pdf PDF] presentation explaining how to submit and review an assignment with Expertiza.
*For students, a [http://research.csc.ncsu.edu/efg/expertiza/presentations/videos/student.swf video] showing how to use the system to submit and review an assignment.
*For students, a [http://research.csc.ncsu.edu/efg/expertiza/presentations/student_wiki_documentation.ppt Powerpoint] or [http://research.csc.ncsu.edu/efg/expertiza/presentations/student_wiki_documentation.pdf PDF] presentation explaining how to submit and review wiki pages with Expertiza.
*For students, a [http://courses.ncsu.edu/csc517/common/homework/topic-signup-team-formation.ppt Powerpoint] or [http://courses.ncsu.edu/csc517/common/homework/topic-signup-team-formation.pdf PDF] presentation explaining how to form teams and sign up for topics.

== Developers section ==
''Expertiza now has a Java dependency, so the machine you are using to develop Expertiza on should have the JVM installed.''
=== Development Environment Setup Guides ===
* [[Creating a Linux Development Environment for Expertiza - Installation Guide]]
**[http://wiki.expertiza.ncsu.edu/index.php/Development:Setup:Linux:Debian Development setup for Ubuntu/Debian]
* [[Development:Setup:OSX]]
*[http://wiki.expertiza.ncsu.edu/index.php/Development:Setup:Linux:RHEL Development setup for Linux RHEL ]
*[[Developing Expertiza on the VCL]]
*Developing Expertiza on Virtual Box
** [https://drive.google.com/a/ncsu.edu/file/d/0B2vDvVjH76uEUmNKVncxRUhUVVE/view?usp=sharing Download the VirtualBox Ubuntu image here]
** [https://drive.google.com/open?id=1YlqiSsbZl8TfPuQmIFG7TYo2npWzqqu4 or try the Lubuntu image here if the Ubuntu image is too heavy for your PC/Laptop ]
*Docker image (Only if you are familiar with docker. You will need it if you choose Expertiza to do OSS project.)
** Please follow the instruction in https://hub.docker.com/r/winbobob/expertiza-fall2016/

=== Database Guides ===
*[[Deploying and importing production data with capistrano]]
*[[Documentation on Database Tables]]
*[[Documentation for Database Anonymization]]

=== Security Guidelines ===
*[[Security guidelines for Expertiza]]
=== Git ===
*[[Version Control with the Git repository]]
*[http://wiki.expertiza.ncsu.edu/index.php/How_to_Begin_a_Project_from_the_Current_Expertiza_Repository How to Begin a Project from the Current Expertiza Repository]

=== Ruby and Rails ===
*[[Restart Instructions for Expertiza]]
*[[Deploying Expertiza to Production]]
*[[Gem dependencies]]
*[[http://wiki.expertiza.ncsu.edu/index.php?title=Using_Cucumber_with_Expertiza Using Cucumber with Expertiza]]

=== Misc ===
*[[Setting up and using TA functionality]]
*[[Restart instructions for Wiki]]
*[[Scoring & Grading Methods (Fall '21)]]
*[[Broken Links]]

=== Final Projects on Expertiza for Fall 2015 ===
[https://docs.google.com/document/d/1t0keeNQ2kP0NmcgIrtQXGi5K_GhQYcKzEVWJPPRBOHE/edit?pli=1 The Expertiza Final Project Submission] 

== Links ==
[http://expertiza.ncsu.edu The Expertiza application] 
[http://research.csc.ncsu.edu/efg/expertiza/papers Papers on Expertiza] 
[http://research.csc.ncsu.edu/efg/expertiza/presentations/Expertiza-short.htm PowerPoint Presentation - The Expertiza platform] 
[http://www.csc.ncsu.edu/news/463 Expertiza Platform Takes Honorable Mention in Gertrude Cox Awards]

== Acknowledgments ==

This material is based upon work supported by the National Science Foundation under Grant No. 0536558. Additional funding from the NCSU Learning in a Technology-Rich Environment (LITRE) program, the NCSU Faculty Center for Teaching and Learning, the NCSU STEM Initiative, and the Center for Advanced Computing and Communication.

Broken Links

2024-10-26T16:55:06Z

Wagrocho: Created initial wiki to keep