Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-25T02:33:31Z

Jdjohns4: added video link

== Topic Overview ==

=== Motivation ===
Numerical data are important in providing insights. However, in raw format, numerical data are hard to grasp and introduce more confusion than information. Graphical presentations of numerical data are needed to draw insights and focus from the available data.

'''For this project, we are developing the front-end user interface for GraphQL query for a desktop application to display summary statistics of Github repository and Github users' contribution to said repository.''' Github provides [https://docs.github.com/en/graphql GraphQL API] for developers who are interested in the raw data surrounding each Github repository and user. Such data can be used to develop metrics to monitor a repository's activities, performance, community involvement, community usage, and contribution from the community and collaborators. The main focus of this project is developing a UI to display these metrics and summary statistics in graphical and tabular formats to provide clients with insights into their own Github repository or any Github repository they are interested in.

Our interface design will be developed from scratch based on client requirements ([https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2023_-G2335._Develop_Frontend_UI_Interface_for_GraphQL_Query#Feature_Requirements project requirements]). We aim to make this design and interface a building block and sound foundation for future projects that want to extend our use case or build similar applications.

=== Scope ===
As our project focuses on the design and front-end interface of the application, back-end calls to fetch and methods organize data from Github GraphQL API will not be handled. Instead, the data will be stubbed using pre-process datasets in CSV files. These files are the products of data fetched from Github API and organized for ease of accessing and rapid development of the front-end.

Additionally, as the interface will be developed from scratch and the time allotted for this project, we will be focusing on basic displays and graphs of the data.

== Feature Requirements ==

=== Raw Data ===
The raw data we are working with contain these fields

{| class="wikitable" style="width: 100%;
! Metrics !! Column Names !! Definition
|-
|Days
|<code>lifeSpan</code>
|Days of Github experience before class.
|-
|A
|<code>commitContributions</code>
|The number of private and public commits made by this user.
|-
|B
|<code>commitComments, issueComments, gistComments, repositoryDiscussionComments, repositoryDiscussions</code>
|The number of comments made by this user in commits, issues, and pull request discussions.
|-
|C
|<code>pullRequests, pullRequestReviewContributions</code>
|The number of PR and PR reviews made by this user.
|-
|D
|<code>issues, projects</code>
|The number of issues, and projects created by this user.
|-
|E
|<code>Alanguagecount + Clanguagecount</code>
|The number of different languages used in user's type I repositories.
|-
|F
|<code>Alanguagesizet + Clanguagesize</code>
|The size of code written in Github popular languages in user's type I repositories.
|-
|G
|<code>Blanguagecount + Dlanguagecount</code>
|The number of different languages used in user's type II repositories.
|-
|H
|<code>Blanguagesizet + Dlanguagesize</code>
|The size of code written in Github popular languages in user's type II repositories.
|-
|I
|<code>repoACount, repoBCount, repoCCount, repoDCount</code>
|The total number of type I, and type II repositories.
|-
|J
|<code>forkACount, stargazerACount, Awatchers, forkCCount, stargazerCCount, Cwatchers</code>
|The total number of forks, stars, and watchers in type I repositories.
|-
|K
|<code> forkBCount, stargazerBCount, Bwatchers, forkDCount, stargazerDCount, Dwatchers</code>
|The total number of forks, stars, and watchers in type II repositories.
|-
|L
|<code>repoASize, repoCSize</code>
|The total code size of type I repositories.
|-
|M
|<code>repoBSize, repoDSize</code>
|The total code size of type II repositories.
|}

=== Features ===
The followings are the features that the desktop application is required to have
* A table for basic statistics ((median, 25th, mean, 75th percentile, stdev) in the following format
{| class="wikitable" style="width: 100%;
! !! median!! 25th !! mean !! 75th !! stdev
|-
|Days
|
|
|
|
|
|-
|A
|
|
|
|
|
|-
|...''other metrics''...
|
|
|
|
|
|}

* A table for the lowest ranked 1/5 username in the following format
{| class="wikitable" style="width: 100%;
! !! 1st!! 2nd !! 3rd !! 4th !! 5th
|-
|Days
|USER 10
|USER 2
|USER 6
|USER 18
|USER 21
|-
|A
|USER 5
|USER 1
|USER 13
|USER 22
|USER 19
|-
|...''other metrics''...
|...
|...
|...
|...
|...
|}

* A boxplot for each of the metrics listed
* A histogram for each of the metrics listed

== Interface Design ==

=== User Interaction ===

With the GUI of our application, we aim to create an interactive workflow where users can drill into each metric, graph, and summary statistics table by clicking. Thus, prevent a ton of scrolling or production of unnecessary charts that flood the interface. The following graph shows the workflow of our ideal application design

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

=== App workflow ===
The visualization below presents the general workflow of our app.

Upon launch, the app starts with a open_file window dialog box which prompts user to load a local file (or enter query input, in the future). The open_file window allows file browsing (in the future, query to GitHub GraphQL API), and upon loading the data, the app will load and preprocess the data for display and computation. Once data is loaded and prepare, main_window opens and this event will close the initial ope_file dialog.

The main window contains two tabs: one for metrics summary statistics and one for ranking users (returned by the query or data file) for each metric. Next to each metric in the summary statistics tab, users will have the option to visualize the metric. Additionally, the main window contains a menu option that allows loading another file (or performing another query). This action will close the report and visualization of current data and load up the new data.

The visualization window contains two tabs: one for box plot and one for histogram. These visualizations provide graphical insights into the chosen metric.

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

=== Mockup Design ===
The mockups below were created using Qt Designer, a graphical interface builder that produces XML-based mockups that can be converted into working python-based pyQt code.

The current design consists of a desktop application that allows the user to browse for and select a csv-based data file (1), loads and processes the data from the csv into tables for summary stats (2) and the lowest ranked users (3) for each metric. On the summary stats table, the user can select the chart icon to bring up a popup that has details about the metric and tabs to show a boxplot (4) and histogram (5) for the selected metric.

==== 1. Open File ====
[[File:G2335_-_mockup_openfile.png]]

==== 2. Summary Stats ====
[[File:G2335_-_mockup_table_summary_stats.png]]

==== 3. Lowest Rank ====
[[File:G2335_-_mockup_table_lowest_ranked.png]]

==== 4. Boxplot ====
[[File:G2335_-_mockup_chart_boxplot.png]]

==== 5. Histogram ====
[[File:G2335_-_mockup_chart_histogram.png]]

== Implementation Details ==

=== Tools ===
The interface for the desktop application will be developed using
* [https://www.riverbankcomputing.com/software/pyqt/ pyQt6] to create front-end components,
* [https://www.python.org/ Python (v3)] to compute statistics from raw data
* [https://matplotlib.org/ matplotlib] to render graphs
* [https://build-system.fman.io/qt-designer-download Qt Designer] to mock-up the application UI using a drag-drop interface of pyQt

=== Project Setup and Application Execution ===
To set up and execute this project follow the instructions below:

*Create a new virtual environment
*Enter the virtual environment
*Install prerequisite Python libraries

===== Create Virtual Environment =====
*It is recommended to create a python3 virtual environment to set up and run this application within. To create a virtual environment, from the root of this project:

<code> python3 -m venv ./venv </code>

*Enter the virtual environment by running:

<code> source venv/bin/activate ## mac and linux</code>

<code> venv\Scripts\activate ## windows</code>

*You can exit the virtual environment at any time by running:
<code> deactivate </code>

==== Install Prereq Libraries ====
Once within the virtual environment, at initial setup, the prereq Python libraries need to be installed within the environment. To do this run the following from the root of this project:

<code>pip install -r requirements.txt</code>

==== Run the Application ====
From within the virtual environment in the root directory (PYQT_UI) run the following command to start the application:

<code>python run.py</code>

=== Implementation ===

===== GUI =====
We implemented the graphical user interface of our application using PyQt6. Our interface consists of three main windows:

* File Browser Window -- the interface allowing the user to browse and load an input CSV file
* Report Window -- the interface showing two tabs, one for summary statistics for all metrics and one for the lowest ranked users in each metric
* Metric Detail Window -- the interface showing two tabs, one for an boxplot of the selected metric data, and one for a histogram of the selected metric data

We constructed our three windows using the Qt Designer [https://build-system.fman.io/qt-designer-download] application which allows the laying out and building of a user interface via graphical drag-and-drop methods. The output of Qt Designer are .ui files which are an XML format file that describes the user interface elements and properties.

With the .ui files, there are two methods to using them within the PyQt library:
* Generating python class source code directly from the .ui file(s) for insertion into the application or,
* Reading the .ui files in directly during the execution of the python application which constructs the GUI objects on the fly at runtime.

Since the application is small and performance with our sample data was not an issue, we elected for the second method to generate the GUI objects on the fly. Additionally we are able to version the XML .ui files and directly tweak elements within the XML to manipulate the interface.

Each of our windows has a python class and a paired .ui file that is loaded by the class when it is instantiated. An example of this from the FileWindow class within app/gui/file_window.py:

<nowiki>
ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
DESIGNER_OPEN_FILE = os.path.join(ROOT_DIR,"designer","file_window.ui")
self.ui = uic.loadUi(DESIGNER_OPEN_FILE, self)</nowiki>

From there the ui objects can be referenced to hook up interaction events with the rest of the application. Continuing the above example, the file browse and load buttons are hooked to downstream browseFile() and openReport() functions:

<nowiki>
self.ui.browseButton.clicked.connect(self.browseFile)
self.ui.loadFileButton.clicked.connect(self.openReport)</nowiki>

In addition to our three main windows, we use a singleton class called Main (app/gui/main.py) that is responsible for all programmatic opening/closing of windows such that a single version of the current state of the application is kept by that object. Instantiated window objects have a pointer to this Main class which allows windows to interact with one another, for instance to single the report window to open once the file window has loaded a CSV.

===== File browsing/loading and summary statistics tables =====
The app starts with a browse/load file dialog box that prompts the user to provide data for the report. ''Browse'' button opens file explorer on the user's machine and allows the user to search for the file they need. Based on how the data is organized behind the scene and the tools we're currently using, our app only accepts files with CSV extension. Our app accesses the machine's file explorer system and safeguards the file type using the following code.
<nowiki>
## browse csv file using file explorer
def browseFile(self):
filename = QFileDialog.getOpenFileName(self, 'Open File', '.', 'CSV Files (*.csv)')
self.filename = filename[0]
self.ui.pathToFileTextbox.setText(self.filename)</nowiki>

The text box next to ''browse'' button display the path of the chosen file on the user's machine. This text box will not allow the user to manually enter the path to the file or edit the path of the file browsed. This is to avoid human error while interacting with the file's path. The load function of the ''open_file'' window also further checks the validity of the path using the following code. If the path of a file is invalid, a dialog box will pop up to notify the user as such. Note that, the validity of the path to a file is not checked until the ''load'' button is clicked. This is to prevent situations in which the user browses a valid file through the machine's file explorer, but the file, under whatever circumstances, gets deleted between after browsing is done and before loading is finished.

<nowiki>
## check the validity of user-entered filename
def _isValidFile(self):
return self.filename and os.path.isfile(self.filename) and self.filename[-4:] == '.csv'

## load csv file
def loadFile(self):
if not self._isValidFile():
return self.raiseMissingFilenameError()
metric_constructor = Metrics(self.filename)
metric_constructor.constructMetricsTable()
self.data = metric_constructor.get_datatable()</nowiki>

Behind the scene, the ''load'' button also performs the following functionalities upon activation and before the main window loads
* Computes the metric values (columns) for each user (row) [1]
* Compute summary statistics for each metric using the data resulted from computation in [1]
* Compute user ranking for each metric using the data resulted from computation in [1]
* Organize the summary statistics into pandas dataframe for display
* Organize the ranking data into pandas dataframe for display

===== Visualization =====
Once a CSV has been loaded and the Report Window appears, the detail icon to the left of each metric row can be selected to launch the Metric Detail Window. This window consists of a tabbed interface allowing the toggling between Boxplot and Histogram visual representations of the underlying metric data. The class responsible for initializing the window and visualizations is app.gui.metric_detail_window.MetricDetailWindow().

The boxplot and histogram visualizations are constructed via the matplotlib library which is initialized in a special manner to allow use within the PyQt library. These imports were demonstrated in a useful example at https://www.pythonguis.com/tutorials/pyqt6-plotting-matplotlib/ and are included below for reference:

<nowiki>
import matplotlib
matplotlib.use('QtAgg')

from PyQt6 import uic
from PyQt6.QtGui import QAction
from PyQt6.QtWidgets import (
QDialog
)

from matplotlib.backends.backend_qt5agg import FigureCanvasQTAgg
from matplotlib.figure import Figure</nowiki>

The MetricDetailWindow class is instantiated with a pointer to the parent Main() as well as the associated metric identifier, summary data, and histogram data used to construct the visualizations. The window is labeled with the metric identifier and a short description of the metric from a currently hardcoded dictionary within the class. The boxplot and histogram matplotlib figures are initialized via the app.gui.metric_detail_window.MplCanvas() class from the input data which was derived within app/data/compute_statistics.py.

The boxplot is constructed per the following:
<nowiki>
boxplot_data = [{
'label': "",
'whislo': float(metric_summary_data['Min']),
'q1': float(metric_summary_data['25th']),
'med': float(metric_summary_data['Median']),
'q3': float(metric_summary_data['75th']),
whishi': float(metric_summary_data['Max']),
'fliers': []
}]
sc.axes.bxp(boxplot_data, showfliers=False)
</nowiki>

The histogram is constructed per the following:
<nowiki>
sc.axes.hist(self.histogram_data)
</nowiki>

Default matplotlib settings are used for both visualizations -- this is an area where possible tweaks to the application could be beneficial.

== Testing ==

=== Test execution ===

*Before you run your test make sure you Install Prereq Libraries:
<code> pip install -r requirements.txt </code>
*To run different test cases:
<code> pytest tests/test.py </code>

=== Test plan ===
{| class="wikitable" style="margin-left:40px"
|-
! Test No !! Test Description !! Expected Output || Test Result
|-
| 1 || Test that the browseFile method opens the file dialog || A file dialog should appear and the file name should not be empty || PASS
|-
| 1.2 || Test that the loadFile method loads the file correctly || User should be able to load csv file in their device || PASS
|-
| 2 || Test if the file is valid || User should be able to select a valid CSV file is selected, Invalid files should trigger an error message || PASS
|-
| 3 || Test getSummaryStatistics function || It verifies that the function returns a DataFrame, if DataFrame has the expected columns and also that the DataFrame has the expected index || PASS
|-
| 4 || Test getHistogramData function || It verifies if function returns a Series, if series has the expected length and that the values are numeric || PASS
|-
| 5 || Test constructMetricsTable method || It verifies if the constructMetricsTable method generates the expected data frame with the correct columns and dimensions || PASS

|}

====Details====

*Browse File:

In this test, we verify that the browseFile() method of the FileWindow class opens a file dialog correctly.
A qtbot fixture is passed as an argument to this fixture. For testing PyQt-based GUI applications, the pytest-qt library provides the qtbot fixture.
It then asserts that the filename attribute of the FileWindow instance is not empty, indicating that the user has selected a file.

<nowiki>
@pytest.fixture
def file_window(qtbot):
# Create a FileWindow instance for testing and show it
file_window = FileWindow(None)
file_window.show()
# Test that the browseFile method opens the file dialog
with qtbot.waitSignal(file_window.ui.pathToFileTextbox.textChanged):
file_window.browseFile()
assert file_window.filename != ''
</nowiki>

*Load File:

A file can be selected from a local machine and loaded into the application(particularly CSV file). This functionality is essential to the application's primary purpose, which is to analyze data for users.

<nowiki>
# Test that the loadFile method loads the file correctly
file_window.loadFile()
assert file_window.data is not None
qtbot.addWidget(file_window)
return file_window
</nowiki>

*Valid / Invalid files:

The first test function, "test_is_valid_file", checks if a CSV file exists by mocking the "isfile" function from the "os.path" module. And the second test function, "test_invalid_file", checks if a file with a TXT format does not exist by mocking the "isfile" function to always return false.

<nowiki>
def test_is_valid_file(qtbot, file_window, monkeypatch):
# Test if the file is valid
filename = "CSV Files (*.csv)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return True
monkeypatch.setattr(os.path, "isfile", mock_return)

def test_invalid_file(qtbot, file_window, monkeypatch):
# Test if the file is invalid
filename = "TXT Files (*.txt)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return False
monkeypatch.setattr(os.path, "isfile", mock_return)
</nowiki>

* getSummaryStatistics:

This test determines whether a given input dataset's summary statistics, such as the median, 25th percentile, mean, 75th percentile, standard deviation, minimum, and maximum, are accurately computed by the getSummaryStatistics function. It makes use of NumPy and Pandas for creating a random dataset, which it then gives to the getSummaryStatistics method. The test verifies whether a Pandas DataFrame with the anticipated columns and index is properly returned by the function.

<nowiki>
def test_getSummaryStatistics():
# Test that the function returns a DataFrame
result = getSummaryStatistics(data)
assert isinstance(result, pd.DataFrame)

# Test that the DataFrame has the expected columns
expected_columns = ['Median', '25th', 'Mean', '75th', 'Stdev', 'Min', 'Max']
assert result.columns.tolist() == expected_columns

# Test that the DataFrame has the expected index
expected_index = data.columns.tolist()
assert result.index.tolist() == expected_index
</nowiki>

* getHistogramData:

This test checks whether a particular input dataset and metric has been utilized by the getHistogramData method to compute histogram data correctly. Using NumPy and Pandas, the program generates a random dataset and chooses the first column in that dataset as the metric. Following that, this dataset and metric are passed to the getHistogramData function. The function's accuracy in returning a Pandas Series with the desired length and data type is checked in this test. It also tests that the values are numeric.

<nowiki>

def test_getHistogramData():
# Test that the function returns a Series
metric = data.columns[0]
result = getHistogramData(data, metric)
assert isinstance(result, pd.Series)

# Test that the Series has the expected length
expected_length = len(data)
assert len(result) == expected_length

# Test that the values are numeric
assert result.dtype == 'float64'
</nowiki>

*constructMetricsTable:

This test validates whether the Metrics class' constructMetricsTable method correctly creates a Pandas DataFrame from the imported data. It first creates a Metrics object using the metrics_obj fixture mentioned above before invoking the constructMetricsTable function. The resulting Pandas DataFrame is tested to determine if the intended column names and shape are there.
<nowiki>
# Test for constructMetricsTable method
def test_constructMetricsTable(metrics_obj):
# Test the output of the method
metrics_obj.constructMetricsTable()
df = metrics_obj.get_datatable()
assert 'lifespan' in df.columns
assert 'A' in df.columns
assert 'B' in df.columns
assert 'C' in df.columns
assert 'D' in df.columns
assert 'E' in df.columns
assert 'F' in df.columns
assert 'G' in df.columns
assert 'H' in df.columns
assert 'I' in df.columns
assert 'J' in df.columns
assert 'K' in df.columns
assert 'L' in df.columns
assert 'M' in df.columns
assert df.shape == (52, 15)

</nowiki>

=== Test Result ===
[[File:TestResult.png |1000px|]]

== End point summary ==

==== Data Ingestion and Processing ====
We will use the python [https://docs.python.org/3/library/unittest.html unittest] framework to implement unit testing of classes responsible for reading in the input CSVs and executing the metrics within including the functions supporting boxplot, histogram, and basic statistics generation/calculations.

==== PyQt Interface ====
We will use the [https://pytest-qt.readthedocs.io/en/latest/intro.html pytest-qt] package to implement our testing of the user interface. We expect that given the nature of UI testing, our tests may not be fully comprehensive of all situations/environments, but we will attempt to test all major events within the UI (e.g., button presses triggering appropriate actions, data appearing correctly in tables).

See also: [https://doc.qt.io/qtforpython/overviews/qtest-overview.html Python unit testing for pyQt]

== Future Work ==
For this project, our goal is to develop a solid foundation for a desktop application that reports Github data in an informative manner. Our design focuses on displaying the most imperative information to users while avoiding requiring users to engage in complex and unnecessary interactions. We focus on a simple graphical view to avoid overwhelming users with multiple graphs and data.

As a front-end project, our application contains mainly front-end components with a few basic functions behind the scene that do computation and rendering graphs. The backend data pipeline is stubbed using pre-processed CSV files of data fetched manually from Github GraphQL API. However, the connection between the data and the GUI is designed so that the GUI can work with a full-fledged data pipeline. As a result, for future work, we hope to extend our application functionality so that it has a functional backend data pipeline that can take in a user input command to fetch data directly from Github API, process it, and then display information.

Besides having a fully functional application with a backend data pipeline, the following features can be added to the application:
* Users can combine graphs and compare metrics.
* Users can compare the performance and metrics of a Github account to another (or multiple other) account(s).
* Users can manually add texts and annotations to graphs generated by the application.
* Users can export graphs and reports into pdf or image formats (e.g., PNG, and JPEG)

Keeping the future direction in mind, we will design and build the UI to enable as clean as possible of a switch between loading the data from CSV to loading the data via API. One such area of potential reuse/repurpose would be the portions of the application (GUI, controller, and model classes) responsible for taking in an input file -- in our case, the data itself will be ingested, but in the future state, a CSV of GitHub usernames may serve as the entry point.

Additionally, our current code reads and processes .ui files (which are XML files of our app interface generated by the Qt Designer app) and then adds functions to the UI using Python code. The fact that our code has to read and process XML files first slows down our app on start-up. In the future, this could be avoided by converting the XML files into Python codes and objects and work with them directly without having to read and process the .ui files

== Contributors ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Related Links ==
* [https://github.ncsu.edu/anguyen9/pyqt_UI Github repo]
* [https://drive.google.com/file/d/1C2YpQUS8T-329YTJDOE8aK0gZuVzYr2F/view?usp=sharing Demonstration Video]

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-25T00:53:13Z

Jdjohns4: /* Visualization */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-25T00:38:59Z

Jdjohns4: /* Project Setup and Application Execution */

== Topic Overview ==

=== Motivation ===
Numerical data are important in providing insights. However, in raw format, numerical data are hard to grasp and introduce more confusion than information. Graphical presentations of numerical data are needed to draw insights and focus from the available data.

'''For this project, we are developing the front-end user interface for GraphQL query for a desktop application to display summary statistics of Github repository and Github users' contribution to said repository.''' Github provides [https://docs.github.com/en/graphql GraphQL API] for developers who are interested in the raw data surrounding each Github repository and user. Such data can be used to develop metrics to monitor a repository's activities, performance, community involvement, community usage, and contribution from the community and collaborators. The main focus of this project is developing a UI to display these metrics and summary statistics in graphical and tabular formats to provide clients with insights into their own Github repository or any Github repository they are interested in.

Our interface design will be developed from scratch based on client requirements ([https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2023_-G2335._Develop_Frontend_UI_Interface_for_GraphQL_Query#Feature_Requirements project requirements]). We aim to make this design and interface a building block and sound foundation for future projects that want to extend our use case or build similar applications.

=== Scope ===
As our project focuses on the design and front-end interface of the application, back-end calls to fetch and methods organize data from Github GraphQL API will not be handled. Instead, the data will be stubbed using pre-process datasets in CSV files. These files are the products of data fetched from Github API and organized for ease of accessing and rapid development of the front-end.

Additionally, as the interface will be developed from scratch and the time allotted for this project, we will be focusing on basic displays and graphs of the data.

== Feature Requirements ==

=== Raw Data ===
The raw data we are working with contain these fields

{| class="wikitable" style="width: 100%;
! Metrics !! Column Names !! Definition
|-
|Days
|<code>lifeSpan</code>
|Days of Github experience before class.
|-
|A
|<code>commitContributions</code>
|The number of private and public commits made by this user.
|-
|B
|<code>commitComments, issueComments, gistComments, repositoryDiscussionComments, repositoryDiscussions</code>
|The number of comments made by this user in commits, issues, and pull request discussions.
|-
|C
|<code>pullRequests, pullRequestReviewContributions</code>
|The number of PR and PR reviews made by this user.
|-
|D
|<code>issues, projects</code>
|The number of issues, and projects created by this user.
|-
|E
|<code>Alanguagecount + Clanguagecount</code>
|The number of different languages used in user's type I repositories.
|-
|F
|<code>Alanguagesizet + Clanguagesize</code>
|The size of code written in Github popular languages in user's type I repositories.
|-
|G
|<code>Blanguagecount + Dlanguagecount</code>
|The number of different languages used in user's type II repositories.
|-
|H
|<code>Blanguagesizet + Dlanguagesize</code>
|The size of code written in Github popular languages in user's type II repositories.
|-
|I
|<code>repoACount, repoBCount, repoCCount, repoDCount</code>
|The total number of type I, and type II repositories.
|-
|J
|<code>forkACount, stargazerACount, Awatchers, forkCCount, stargazerCCount, Cwatchers</code>
|The total number of forks, stars, and watchers in type I repositories.
|-
|K
|<code> forkBCount, stargazerBCount, Bwatchers, forkDCount, stargazerDCount, Dwatchers</code>
|The total number of forks, stars, and watchers in type II repositories.
|-
|L
|<code>repoASize, repoCSize</code>
|The total code size of type I repositories.
|-
|M
|<code>repoBSize, repoDSize</code>
|The total code size of type II repositories.
|}

=== Features ===
The followings are the features that the desktop application is required to have
* A table for basic statistics ((median, 25th, mean, 75th percentile, stdev) in the following format
{| class="wikitable" style="width: 100%;
! !! median!! 25th !! mean !! 75th !! stdev
|-
|Days
|
|
|
|
|
|-
|A
|
|
|
|
|
|-
|...''other metrics''...
|
|
|
|
|
|}

* A table for the lowest ranked 1/5 username in the following format
{| class="wikitable" style="width: 100%;
! !! 1st!! 2nd !! 3rd !! 4th !! 5th
|-
|Days
|USER 10
|USER 2
|USER 6
|USER 18
|USER 21
|-
|A
|USER 5
|USER 1
|USER 13
|USER 22
|USER 19
|-
|...''other metrics''...
|...
|...
|...
|...
|...
|}

* A boxplot for each of the metrics listed
* A histogram for each of the metrics listed

== Interface Design ==

=== User Interaction ===

With the GUI of our application, we aim to create an interactive workflow where users can drill into each metric, graph, and summary statistics table by clicking. Thus, prevent a ton of scrolling or production of unnecessary charts that flood the interface. The following graph shows the workflow of our ideal application design

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

=== App workflow ===
The visualization below presents the general workflow of our app.

Upon launch, the app starts with a open_file window dialog box which prompts user to load a local file (or enter query input, in the future). The open_file window allows file browsing (in the future, query to GitHub GraphQL API), and upon loading the data, the app will load and preprocess the data for display and computation. Once data is loaded and prepare, main_window opens and this event will close the initial ope_file dialog.

The main window contains two tabs: one for metrics summary statistics and one for ranking users (returned by the query or data file) for each metric. Next to each metric in the summary statistics tab, users will have the option to visualize the metric. Additionally, the main window contains a menu option that allows loading another file (or performing another query). This action will close the report and visualization of current data and load up the new data.

The visualization window contains two tabs: one for box plot and one for histogram. These visualizations provide graphical insights into the chosen metric.

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

=== Mockup Design ===
The mockups below were created using Qt Designer, a graphical interface builder that produces XML-based mockups that can be converted into working python-based pyQt code.

The current design consists of a desktop application that allows the user to browse for and select a csv-based data file (1), loads and processes the data from the csv into tables for summary stats (2) and the lowest ranked users (3) for each metric. On the summary stats table, the user can select the chart icon to bring up a popup that has details about the metric and tabs to show a boxplot (4) and histogram (5) for the selected metric.

==== 1. Open File ====
[[File:G2335_-_mockup_openfile.png]]

==== 2. Summary Stats ====
[[File:G2335_-_mockup_table_summary_stats.png]]

==== 3. Lowest Rank ====
[[File:G2335_-_mockup_table_lowest_ranked.png]]

==== 4. Boxplot ====
[[File:G2335_-_mockup_chart_boxplot.png]]

==== 5. Histogram ====
[[File:G2335_-_mockup_chart_histogram.png]]

== Implementation Details ==

=== Tools ===
The interface for the desktop application will be developed using
* [https://www.riverbankcomputing.com/software/pyqt/ pyQt6] to create front-end components,
* [https://www.python.org/ Python (v3)] to compute statistics from raw data
* [https://matplotlib.org/ matplotlib] to render graphs
* [https://build-system.fman.io/qt-designer-download Qt Designer] to mock-up the application UI using a drag-drop interface of pyQt

=== Project Setup and Application Execution ===
To set up and execute this project follow the instructions below:

*Create a new virtual environment
*Enter the virtual environment
*Install prerequisite Python libraries

===== Create Virtual Environment =====
*It is recommended to create a python3 virtual environment to set up and run this application within. To create a virtual environment, from the root of this project:

<code> python3 -m venv ./venv </code>

*Enter the virtual environment by running:

<code> source venv/bin/activate ## mac and linux</code>

<code> venv\Scripts\activate ## windows</code>

*You can exit the virtual environment at any time by running:
<code> deactivate </code>

==== Install Prereq Libraries ====
Once within the virtual environment, at initial setup, the prereq Python libraries need to be installed within the environment. To do this run the following from the root of this project:

<code>pip install -r requirements.txt</code>

==== Run the Application ====
From within the virtual environment in the root directory (PYQT_UI) run the following command to start the application:

<code>python run.py</code>

=== Implementation ===

===== GUI =====
We implemented the graphical user interface of our application using PyQt6. Our interface consists of three main windows:

* File Browser Window -- the interface allowing the user to browse and load an input CSV file
* Report Window -- the interface showing two tabs, one for summary statistics for all metrics and one for the lowest ranked users in each metric
* Metric Detail Window -- the interface showing two tabs, one for an boxplot of the selected metric data, and one for a histogram of the selected metric data

We constructed our three windows using the Qt Designer [https://build-system.fman.io/qt-designer-download] application which allows the laying out and building of a user interface via graphical drag-and-drop methods. The output of Qt Designer are .ui files which are an XML format file that describes the user interface elements and properties.

With the .ui files, there are two methods to using them within the PyQt library:
* Generating python class source code directly from the .ui file(s) for insertion into the application or,
* Reading the .ui files in directly during the execution of the python application which constructs the GUI objects on the fly at runtime.

Since the application is small and performance with our sample data was not an issue, we elected for the second method to generate the GUI objects on the fly. Additionally we are able to version the XML .ui files and directly tweak elements within the XML to manipulate the interface.

Each of our windows has a python class and a paired .ui file that is loaded by the class when it is instantiated. An example of this from the FileWindow class within app/gui/file_window.py:

<nowiki>
ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
DESIGNER_OPEN_FILE = os.path.join(ROOT_DIR,"designer","file_window.ui")
self.ui = uic.loadUi(DESIGNER_OPEN_FILE, self)</nowiki>

From there the ui objects can be referenced to hook up interaction events with the rest of the application. Continuing the above example, the file browse and load buttons are hooked to downstream browseFile() and openReport() functions:

<nowiki>
self.ui.browseButton.clicked.connect(self.browseFile)
self.ui.loadFileButton.clicked.connect(self.openReport)</nowiki>

In addition to our three main windows, we use a singleton class called Main (app/gui/main.py) that is responsible for all programmatic opening/closing of windows such that a single version of the current state of the application is kept by that object. Instantiated window objects have a pointer to this Main class which allows windows to interact with one another, for instance to single the report window to open once the file window has loaded a CSV.

===== File browsing/loading and summary statistics tables =====
The app starts with a browse/load file dialog box that prompts the user to provide data for the report. ''Browse'' button opens file explorer on the user's machine and allows the user to search for the file they need. Based on how the data is organized behind the scene and the tools we're currently using, our app only accepts files with CSV extension. Our app accesses the machine's file explorer system and safeguards the file type using the following code.
<nowiki>
## browse csv file using file explorer
def browseFile(self):
filename = QFileDialog.getOpenFileName(self, 'Open File', '.', 'CSV Files (*.csv)')
self.filename = filename[0]
self.ui.pathToFileTextbox.setText(self.filename)</nowiki>

The text box next to ''browse'' button display the path of the chosen file on the user's machine. This text box will not allow the user to manually enter the path to the file or edit the path of the file browsed. This is to avoid human error while interacting with the file's path. The load function of the ''open_file'' window also further checks the validity of the path using the following code. If the path of a file is invalid, a dialog box will pop up to notify the user as such. Note that, the validity of the path to a file is not checked until the ''load'' button is clicked. This is to prevent situations in which the user browses a valid file through the machine's file explorer, but the file, under whatever circumstances, gets deleted between after browsing is done and before loading is finished.

<nowiki>
## check the validity of user-entered filename
def _isValidFile(self):
return self.filename and os.path.isfile(self.filename) and self.filename[-4:] == '.csv'

## load csv file
def loadFile(self):
if not self._isValidFile():
return self.raiseMissingFilenameError()
metric_constructor = Metrics(self.filename)
metric_constructor.constructMetricsTable()
self.data = metric_constructor.get_datatable()</nowiki>

Behind the scene, the ''load'' button also performs the following functionalities upon activation and before the main window loads
* Computes the metric values (columns) for each user (row) [1]
* Compute summary statistics for each metric using the data resulted from computation in [1]
* Compute user ranking for each metric using the data resulted from computation in [1]
* Organize the summary statistics into pandas dataframe for display
* Organize the ranking data into pandas dataframe for display

===== Visualization =====
''' Todo: ''' add visualization implementation details

== Testing ==

=== Test execution ===

*Before you run your test make sure you Install Prereq Libraries:
<code> pip install -r requirements.txt </code>
*To run different test cases:
<code> pytest tests/test.py </code>

=== Test plan ===
{| class="wikitable" style="margin-left:40px"
|-
! Test No !! Test Description !! Expected Output || Test Result
|-
| 1 || Test that the browseFile method opens the file dialog || A file dialog should appear and the file name should not be empty || PASS
|-
| 1.2 || Test that the loadFile method loads the file correctly || User should be able to load csv file in their device || PASS
|-
| 2 || Test if the file is valid || User should be able to select a valid CSV file is selected, Invalid files should trigger an error message || PASS
|-
| 3 || Test getSummaryStatistics function || It verifies that the function returns a DataFrame, if DataFrame has the expected columns and also that the DataFrame has the expected index || PASS
|-
| 4 || Test getHistogramData function || It verifies if function returns a Series, if series has the expected length and that the values are numeric || PASS
|-
| 5 || Test constructMetricsTable method || It verifies if the constructMetricsTable method generates the expected data frame with the correct columns and dimensions || PASS

|}

====Details====

*Browse File:

In this test, we verify that the browseFile() method of the FileWindow class opens a file dialog correctly.
A qtbot fixture is passed as an argument to this fixture. For testing PyQt-based GUI applications, the pytest-qt library provides the qtbot fixture.
It then asserts that the filename attribute of the FileWindow instance is not empty, indicating that the user has selected a file.

<nowiki>
@pytest.fixture
def file_window(qtbot):
# Create a FileWindow instance for testing and show it
file_window = FileWindow(None)
file_window.show()
# Test that the browseFile method opens the file dialog
with qtbot.waitSignal(file_window.ui.pathToFileTextbox.textChanged):
file_window.browseFile()
assert file_window.filename != ''
</nowiki>

*Load File:

A file can be selected from a local machine and loaded into the application(particularly CSV file). This functionality is essential to the application's primary purpose, which is to analyze data for users.

<nowiki>
# Test that the loadFile method loads the file correctly
file_window.loadFile()
assert file_window.data is not None
qtbot.addWidget(file_window)
return file_window
</nowiki>

*Valid / Invalid files:

The first test function, "test_is_valid_file", checks if a CSV file exists by mocking the "isfile" function from the "os.path" module. And the second test function, "test_invalid_file", checks if a file with a TXT format does not exist by mocking the "isfile" function to always return false.

<nowiki>
def test_is_valid_file(qtbot, file_window, monkeypatch):
# Test if the file is valid
filename = "CSV Files (*.csv)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return True
monkeypatch.setattr(os.path, "isfile", mock_return)

def test_invalid_file(qtbot, file_window, monkeypatch):
# Test if the file is invalid
filename = "TXT Files (*.txt)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return False
monkeypatch.setattr(os.path, "isfile", mock_return)
</nowiki>

* getSummaryStatistics:

This test determines whether a given input dataset's summary statistics, such as the median, 25th percentile, mean, 75th percentile, standard deviation, minimum, and maximum, are accurately computed by the getSummaryStatistics function. It makes use of NumPy and Pandas for creating a random dataset, which it then gives to the getSummaryStatistics method. The test verifies whether a Pandas DataFrame with the anticipated columns and index is properly returned by the function.

<nowiki>
def test_getSummaryStatistics():
# Test that the function returns a DataFrame
result = getSummaryStatistics(data)
assert isinstance(result, pd.DataFrame)

# Test that the DataFrame has the expected columns
expected_columns = ['Median', '25th', 'Mean', '75th', 'Stdev', 'Min', 'Max']
assert result.columns.tolist() == expected_columns

# Test that the DataFrame has the expected index
expected_index = data.columns.tolist()
assert result.index.tolist() == expected_index
</nowiki>

* getHistogramData:

This test checks whether a particular input dataset and metric has been utilized by the getHistogramData method to compute histogram data correctly. Using NumPy and Pandas, the program generates a random dataset and chooses the first column in that dataset as the metric. Following that, this dataset and metric are passed to the getHistogramData function. The function's accuracy in returning a Pandas Series with the desired length and data type is checked in this test. It also tests that the values are numeric.

<nowiki>

def test_getHistogramData():
# Test that the function returns a Series
metric = data.columns[0]
result = getHistogramData(data, metric)
assert isinstance(result, pd.Series)

# Test that the Series has the expected length
expected_length = len(data)
assert len(result) == expected_length

# Test that the values are numeric
assert result.dtype == 'float64'
</nowiki>

*constructMetricsTable:

This test validates whether the Metrics class' constructMetricsTable method correctly creates a Pandas DataFrame from the imported data. It first creates a Metrics object using the metrics_obj fixture mentioned above before invoking the constructMetricsTable function. The resulting Pandas DataFrame is tested to determine if the intended column names and shape are there.
<nowiki>
# Test for constructMetricsTable method
def test_constructMetricsTable(metrics_obj):
# Test the output of the method
metrics_obj.constructMetricsTable()
df = metrics_obj.get_datatable()
assert 'lifespan' in df.columns
assert 'A' in df.columns
assert 'B' in df.columns
assert 'C' in df.columns
assert 'D' in df.columns
assert 'E' in df.columns
assert 'F' in df.columns
assert 'G' in df.columns
assert 'H' in df.columns
assert 'I' in df.columns
assert 'J' in df.columns
assert 'K' in df.columns
assert 'L' in df.columns
assert 'M' in df.columns
assert df.shape == (52, 15)

</nowiki>

=== Test Result ===
[[File:TestResult.png |1000px|]]

== End point summary ==

==== Data Ingestion and Processing ====
We will use the python [https://docs.python.org/3/library/unittest.html unittest] framework to implement unit testing of classes responsible for reading in the input CSVs and executing the metrics within including the functions supporting boxplot, histogram, and basic statistics generation/calculations.

==== PyQt Interface ====
We will use the [https://pytest-qt.readthedocs.io/en/latest/intro.html pytest-qt] package to implement our testing of the user interface. We expect that given the nature of UI testing, our tests may not be fully comprehensive of all situations/environments, but we will attempt to test all major events within the UI (e.g., button presses triggering appropriate actions, data appearing correctly in tables).

See also: [https://doc.qt.io/qtforpython/overviews/qtest-overview.html Python unit testing for pyQt]

== Future Work ==
For this project, our goal is to develop a solid foundation for a desktop application that reports Github data in an informative manner. Our design focuses on displaying the most imperative information to users while avoiding requiring users to engage in complex and unnecessary interactions. We focus on a simple graphical view to avoid overwhelming users with multiple graphs and data.

As a front-end project, our application contains mainly front-end components with a few basic functions behind the scene that do computation and rendering graphs. The backend data pipeline is stubbed using pre-processed CSV files of data fetched manually from Github GraphQL API. However, the connection between the data and the GUI is designed so that the GUI can work with a full-fledged data pipeline. As a result, for future work, we hope to extend our application functionality so that it has a functional backend data pipeline that can take in a user input command to fetch data directly from Github API, process it, and then display information.

Besides having a fully functional application with a backend data pipeline, the following features can be added to the application:
* Users can combine graphs and compare metrics.
* Users can compare the performance and metrics of a Github account to another (or multiple other) account(s).
* Users can manually add texts and annotations to graphs generated by the application.
* Users can export graphs and reports into pdf or image formats (e.g., PNG, and JPEG)

Keeping the future direction in mind, we will design and build the UI to enable as clean as possible of a switch between loading the data from CSV to loading the data via API. One such area of potential reuse/repurpose would be the portions of the application (GUI, controller, and model classes) responsible for taking in an input file -- in our case, the data itself will be ingested, but in the future state, a CSV of GitHub usernames may serve as the entry point.

Additionally, our current code reads and processes .ui files (which are XML files of our app interface generated by the Qt Designer app) and then adds functions to the UI using Python code. The fact that our code has to read and process XML files first slows down our app on start-up. In the future, this could be avoided by converting the XML files into Python codes and objects and work with them directly without having to read and process the .ui files

== Contributors ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Related Links ==
* [https://github.ncsu.edu/anguyen9/pyqt_UI Github repo]

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-25T00:35:06Z

Jdjohns4: added info about how GUI is constructed

== Topic Overview ==

=== Motivation ===
Numerical data are important in providing insights. However, in raw format, numerical data are hard to grasp and introduce more confusion than information. Graphical presentations of numerical data are needed to draw insights and focus from the available data.

'''For this project, we are developing the front-end user interface for GraphQL query for a desktop application to display summary statistics of Github repository and Github users' contribution to said repository.''' Github provides [https://docs.github.com/en/graphql GraphQL API] for developers who are interested in the raw data surrounding each Github repository and user. Such data can be used to develop metrics to monitor a repository's activities, performance, community involvement, community usage, and contribution from the community and collaborators. The main focus of this project is developing a UI to display these metrics and summary statistics in graphical and tabular formats to provide clients with insights into their own Github repository or any Github repository they are interested in.

Our interface design will be developed from scratch based on client requirements ([https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2023_-G2335._Develop_Frontend_UI_Interface_for_GraphQL_Query#Feature_Requirements project requirements]). We aim to make this design and interface a building block and sound foundation for future projects that want to extend our use case or build similar applications.

=== Scope ===
As our project focuses on the design and front-end interface of the application, back-end calls to fetch and methods organize data from Github GraphQL API will not be handled. Instead, the data will be stubbed using pre-process datasets in CSV files. These files are the products of data fetched from Github API and organized for ease of accessing and rapid development of the front-end.

Additionally, as the interface will be developed from scratch and the time allotted for this project, we will be focusing on basic displays and graphs of the data.

== Feature Requirements ==

=== Raw Data ===
The raw data we are working with contain these fields

{| class="wikitable" style="width: 100%;
! Metrics !! Column Names !! Definition
|-
|Days
|<code>lifeSpan</code>
|Days of Github experience before class.
|-
|A
|<code>commitContributions</code>
|The number of private and public commits made by this user.
|-
|B
|<code>commitComments, issueComments, gistComments, repositoryDiscussionComments, repositoryDiscussions</code>
|The number of comments made by this user in commits, issues, and pull request discussions.
|-
|C
|<code>pullRequests, pullRequestReviewContributions</code>
|The number of PR and PR reviews made by this user.
|-
|D
|<code>issues, projects</code>
|The number of issues, and projects created by this user.
|-
|E
|<code>Alanguagecount + Clanguagecount</code>
|The number of different languages used in user's type I repositories.
|-
|F
|<code>Alanguagesizet + Clanguagesize</code>
|The size of code written in Github popular languages in user's type I repositories.
|-
|G
|<code>Blanguagecount + Dlanguagecount</code>
|The number of different languages used in user's type II repositories.
|-
|H
|<code>Blanguagesizet + Dlanguagesize</code>
|The size of code written in Github popular languages in user's type II repositories.
|-
|I
|<code>repoACount, repoBCount, repoCCount, repoDCount</code>
|The total number of type I, and type II repositories.
|-
|J
|<code>forkACount, stargazerACount, Awatchers, forkCCount, stargazerCCount, Cwatchers</code>
|The total number of forks, stars, and watchers in type I repositories.
|-
|K
|<code> forkBCount, stargazerBCount, Bwatchers, forkDCount, stargazerDCount, Dwatchers</code>
|The total number of forks, stars, and watchers in type II repositories.
|-
|L
|<code>repoASize, repoCSize</code>
|The total code size of type I repositories.
|-
|M
|<code>repoBSize, repoDSize</code>
|The total code size of type II repositories.
|}

=== Features ===
The followings are the features that the desktop application is required to have
* A table for basic statistics ((median, 25th, mean, 75th percentile, stdev) in the following format
{| class="wikitable" style="width: 100%;
! !! median!! 25th !! mean !! 75th !! stdev
|-
|Days
|
|
|
|
|
|-
|A
|
|
|
|
|
|-
|...''other metrics''...
|
|
|
|
|
|}

* A table for the lowest ranked 1/5 username in the following format
{| class="wikitable" style="width: 100%;
! !! 1st!! 2nd !! 3rd !! 4th !! 5th
|-
|Days
|USER 10
|USER 2
|USER 6
|USER 18
|USER 21
|-
|A
|USER 5
|USER 1
|USER 13
|USER 22
|USER 19
|-
|...''other metrics''...
|...
|...
|...
|...
|...
|}

* A boxplot for each of the metrics listed
* A histogram for each of the metrics listed

== Interface Design ==

=== User Interaction ===

With the GUI of our application, we aim to create an interactive workflow where users can drill into each metric, graph, and summary statistics table by clicking. Thus, prevent a ton of scrolling or production of unnecessary charts that flood the interface. The following graph shows the workflow of our ideal application design

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

=== App workflow ===
The visualization below presents the general workflow of our app.

Upon launch, the app starts with a open_file window dialog box which prompts user to load a local file (or enter query input, in the future). The open_file window allows file browsing (in the future, query to GitHub GraphQL API), and upon loading the data, the app will load and preprocess the data for display and computation. Once data is loaded and prepare, main_window opens and this event will close the initial ope_file dialog.

The main window contains two tabs: one for metrics summary statistics and one for ranking users (returned by the query or data file) for each metric. Next to each metric in the summary statistics tab, users will have the option to visualize the metric. Additionally, the main window contains a menu option that allows loading another file (or performing another query). This action will close the report and visualization of current data and load up the new data.

The visualization window contains two tabs: one for box plot and one for histogram. These visualizations provide graphical insights into the chosen metric.

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

=== Mockup Design ===
The mockups below were created using Qt Designer, a graphical interface builder that produces XML-based mockups that can be converted into working python-based pyQt code.

The current design consists of a desktop application that allows the user to browse for and select a csv-based data file (1), loads and processes the data from the csv into tables for summary stats (2) and the lowest ranked users (3) for each metric. On the summary stats table, the user can select the chart icon to bring up a popup that has details about the metric and tabs to show a boxplot (4) and histogram (5) for the selected metric.

==== 1. Open File ====
[[File:G2335_-_mockup_openfile.png]]

==== 2. Summary Stats ====
[[File:G2335_-_mockup_table_summary_stats.png]]

==== 3. Lowest Rank ====
[[File:G2335_-_mockup_table_lowest_ranked.png]]

==== 4. Boxplot ====
[[File:G2335_-_mockup_chart_boxplot.png]]

==== 5. Histogram ====
[[File:G2335_-_mockup_chart_histogram.png]]

== Implementation Details ==

=== Tools ===
The interface for the desktop application will be developed using
* [https://www.riverbankcomputing.com/software/pyqt/ pyQt6] to create front-end components,
* [https://www.python.org/ Python (v3)] to compute statistics from raw data
* [https://matplotlib.org/ matplotlib] to render graphs
* [https://build-system.fman.io/qt-designer-download Qt Designer] to mock-up the application UI using a drag-drop interface of pyQt

=== Project Setup and Application Execution ===
To set up and execute this project follow the instructions below:

*Create a new virtual environment
*Enter the virtual environment
*Install prerequisite Python libraries

===== Create Virtual Environment =====
*It is recommended to create a python3 virtual environment to set up and run this application within. To create a virtual environment, from the root of this project:

<code> python3 -m venv ./venv </code>

*Enter the virtual environment by running:

<code> source venv/bin/activate ## mac and linux</code>

<code> venv\Scripts\activate ## windows</code>

*You can exit the virtual environment at any time by running:
<code> deactivate </code>

==== Install Prereq Libraries ====
Once within the virtual environment, at initial setup, the prereq Python libraries need to be installed within the environment. To do this run the following from the root of this project:

<code>pip install -r requirements.txt</code>

=== Implementation ===

===== GUI =====
We implemented the graphical user interface of our application using PyQt6. Our interface consists of three main windows:

* File Browser Window -- the interface allowing the user to browse and load an input CSV file
* Report Window -- the interface showing two tabs, one for summary statistics for all metrics and one for the lowest ranked users in each metric
* Metric Detail Window -- the interface showing two tabs, one for an boxplot of the selected metric data, and one for a histogram of the selected metric data

We constructed our three windows using the Qt Designer [https://build-system.fman.io/qt-designer-download] application which allows the laying out and building of a user interface via graphical drag-and-drop methods. The output of Qt Designer are .ui files which are an XML format file that describes the user interface elements and properties.

With the .ui files, there are two methods to using them within the PyQt library:
* Generating python class source code directly from the .ui file(s) for insertion into the application or,
* Reading the .ui files in directly during the execution of the python application which constructs the GUI objects on the fly at runtime.

Since the application is small and performance with our sample data was not an issue, we elected for the second method to generate the GUI objects on the fly. Additionally we are able to version the XML .ui files and directly tweak elements within the XML to manipulate the interface.

Each of our windows has a python class and a paired .ui file that is loaded by the class when it is instantiated. An example of this from the FileWindow class within app/gui/file_window.py:

<nowiki>
ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
DESIGNER_OPEN_FILE = os.path.join(ROOT_DIR,"designer","file_window.ui")
self.ui = uic.loadUi(DESIGNER_OPEN_FILE, self)</nowiki>

From there the ui objects can be referenced to hook up interaction events with the rest of the application. Continuing the above example, the file browse and load buttons are hooked to downstream browseFile() and openReport() functions:

<nowiki>
self.ui.browseButton.clicked.connect(self.browseFile)
self.ui.loadFileButton.clicked.connect(self.openReport)</nowiki>

In addition to our three main windows, we use a singleton class called Main (app/gui/main.py) that is responsible for all programmatic opening/closing of windows such that a single version of the current state of the application is kept by that object. Instantiated window objects have a pointer to this Main class which allows windows to interact with one another, for instance to single the report window to open once the file window has loaded a CSV.

===== File browsing/loading and summary statistics tables =====
The app starts with a browse/load file dialog box that prompts the user to provide data for the report. ''Browse'' button opens file explorer on the user's machine and allows the user to search for the file they need. Based on how the data is organized behind the scene and the tools we're currently using, our app only accepts files with CSV extension. Our app accesses the machine's file explorer system and safeguards the file type using the following code.
<nowiki>
## browse csv file using file explorer
def browseFile(self):
filename = QFileDialog.getOpenFileName(self, 'Open File', '.', 'CSV Files (*.csv)')
self.filename = filename[0]
self.ui.pathToFileTextbox.setText(self.filename)</nowiki>

The text box next to ''browse'' button display the path of the chosen file on the user's machine. This text box will not allow the user to manually enter the path to the file or edit the path of the file browsed. This is to avoid human error while interacting with the file's path. The load function of the ''open_file'' window also further checks the validity of the path using the following code. If the path of a file is invalid, a dialog box will pop up to notify the user as such. Note that, the validity of the path to a file is not checked until the ''load'' button is clicked. This is to prevent situations in which the user browses a valid file through the machine's file explorer, but the file, under whatever circumstances, gets deleted between after browsing is done and before loading is finished.

<nowiki>
## check the validity of user-entered filename
def _isValidFile(self):
return self.filename and os.path.isfile(self.filename) and self.filename[-4:] == '.csv'

## load csv file
def loadFile(self):
if not self._isValidFile():
return self.raiseMissingFilenameError()
metric_constructor = Metrics(self.filename)
metric_constructor.constructMetricsTable()
self.data = metric_constructor.get_datatable()</nowiki>

Behind the scene, the ''load'' button also performs the following functionalities upon activation and before the main window loads
* Computes the metric values (columns) for each user (row) [1]
* Compute summary statistics for each metric using the data resulted from computation in [1]
* Compute user ranking for each metric using the data resulted from computation in [1]
* Organize the summary statistics into pandas dataframe for display
* Organize the ranking data into pandas dataframe for display

===== Visualization =====
''' Todo: ''' add visualization implementation details

== Testing ==

=== Test execution ===

*Before you run your test make sure you Install Prereq Libraries:
<code> pip install -r requirements.txt </code>
*To run different test cases:
<code> pytest tests/test.py </code>

=== Test plan ===
{| class="wikitable" style="margin-left:40px"
|-
! Test No !! Test Description !! Expected Output || Test Result
|-
| 1 || Test that the browseFile method opens the file dialog || A file dialog should appear and the file name should not be empty || PASS
|-
| 1.2 || Test that the loadFile method loads the file correctly || User should be able to load csv file in their device || PASS
|-
| 2 || Test if the file is valid || User should be able to select a valid CSV file is selected, Invalid files should trigger an error message || PASS
|-
| 3 || Test getSummaryStatistics function || It verifies that the function returns a DataFrame, if DataFrame has the expected columns and also that the DataFrame has the expected index || PASS
|-
| 4 || Test getHistogramData function || It verifies if function returns a Series, if series has the expected length and that the values are numeric || PASS
|-
| 5 || Test constructMetricsTable method || It verifies if the constructMetricsTable method generates the expected data frame with the correct columns and dimensions || PASS

|}

====Details====

*Browse File:

In this test, we verify that the browseFile() method of the FileWindow class opens a file dialog correctly.
A qtbot fixture is passed as an argument to this fixture. For testing PyQt-based GUI applications, the pytest-qt library provides the qtbot fixture.
It then asserts that the filename attribute of the FileWindow instance is not empty, indicating that the user has selected a file.

<nowiki>
@pytest.fixture
def file_window(qtbot):
# Create a FileWindow instance for testing and show it
file_window = FileWindow(None)
file_window.show()
# Test that the browseFile method opens the file dialog
with qtbot.waitSignal(file_window.ui.pathToFileTextbox.textChanged):
file_window.browseFile()
assert file_window.filename != ''
</nowiki>

*Load File:

A file can be selected from a local machine and loaded into the application(particularly CSV file). This functionality is essential to the application's primary purpose, which is to analyze data for users.

<nowiki>
# Test that the loadFile method loads the file correctly
file_window.loadFile()
assert file_window.data is not None
qtbot.addWidget(file_window)
return file_window
</nowiki>

*Valid / Invalid files:

The first test function, "test_is_valid_file", checks if a CSV file exists by mocking the "isfile" function from the "os.path" module. And the second test function, "test_invalid_file", checks if a file with a TXT format does not exist by mocking the "isfile" function to always return false.

<nowiki>
def test_is_valid_file(qtbot, file_window, monkeypatch):
# Test if the file is valid
filename = "CSV Files (*.csv)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return True
monkeypatch.setattr(os.path, "isfile", mock_return)

def test_invalid_file(qtbot, file_window, monkeypatch):
# Test if the file is invalid
filename = "TXT Files (*.txt)"
file_window.filename = filename
def mock_return(*args, **kwargs):
return False
monkeypatch.setattr(os.path, "isfile", mock_return)
</nowiki>

* getSummaryStatistics:

This test determines whether a given input dataset's summary statistics, such as the median, 25th percentile, mean, 75th percentile, standard deviation, minimum, and maximum, are accurately computed by the getSummaryStatistics function. It makes use of NumPy and Pandas for creating a random dataset, which it then gives to the getSummaryStatistics method. The test verifies whether a Pandas DataFrame with the anticipated columns and index is properly returned by the function.

<nowiki>
def test_getSummaryStatistics():
# Test that the function returns a DataFrame
result = getSummaryStatistics(data)
assert isinstance(result, pd.DataFrame)

# Test that the DataFrame has the expected columns
expected_columns = ['Median', '25th', 'Mean', '75th', 'Stdev', 'Min', 'Max']
assert result.columns.tolist() == expected_columns

# Test that the DataFrame has the expected index
expected_index = data.columns.tolist()
assert result.index.tolist() == expected_index
</nowiki>

* getHistogramData:

This test checks whether a particular input dataset and metric has been utilized by the getHistogramData method to compute histogram data correctly. Using NumPy and Pandas, the program generates a random dataset and chooses the first column in that dataset as the metric. Following that, this dataset and metric are passed to the getHistogramData function. The function's accuracy in returning a Pandas Series with the desired length and data type is checked in this test. It also tests that the values are numeric.

<nowiki>

def test_getHistogramData():
# Test that the function returns a Series
metric = data.columns[0]
result = getHistogramData(data, metric)
assert isinstance(result, pd.Series)

# Test that the Series has the expected length
expected_length = len(data)
assert len(result) == expected_length

# Test that the values are numeric
assert result.dtype == 'float64'
</nowiki>

*constructMetricsTable:

This test validates whether the Metrics class' constructMetricsTable method correctly creates a Pandas DataFrame from the imported data. It first creates a Metrics object using the metrics_obj fixture mentioned above before invoking the constructMetricsTable function. The resulting Pandas DataFrame is tested to determine if the intended column names and shape are there.
<nowiki>
# Test for constructMetricsTable method
def test_constructMetricsTable(metrics_obj):
# Test the output of the method
metrics_obj.constructMetricsTable()
df = metrics_obj.get_datatable()
assert 'lifespan' in df.columns
assert 'A' in df.columns
assert 'B' in df.columns
assert 'C' in df.columns
assert 'D' in df.columns
assert 'E' in df.columns
assert 'F' in df.columns
assert 'G' in df.columns
assert 'H' in df.columns
assert 'I' in df.columns
assert 'J' in df.columns
assert 'K' in df.columns
assert 'L' in df.columns
assert 'M' in df.columns
assert df.shape == (52, 15)

</nowiki>

=== Test Result ===
[[File:TestResult.png |1000px|]]

== End point summary ==

==== Data Ingestion and Processing ====
We will use the python [https://docs.python.org/3/library/unittest.html unittest] framework to implement unit testing of classes responsible for reading in the input CSVs and executing the metrics within including the functions supporting boxplot, histogram, and basic statistics generation/calculations.

==== PyQt Interface ====
We will use the [https://pytest-qt.readthedocs.io/en/latest/intro.html pytest-qt] package to implement our testing of the user interface. We expect that given the nature of UI testing, our tests may not be fully comprehensive of all situations/environments, but we will attempt to test all major events within the UI (e.g., button presses triggering appropriate actions, data appearing correctly in tables).

See also: [https://doc.qt.io/qtforpython/overviews/qtest-overview.html Python unit testing for pyQt]

== Future Work ==
For this project, our goal is to develop a solid foundation for a desktop application that reports Github data in an informative manner. Our design focuses on displaying the most imperative information to users while avoiding requiring users to engage in complex and unnecessary interactions. We focus on a simple graphical view to avoid overwhelming users with multiple graphs and data.

As a front-end project, our application contains mainly front-end components with a few basic functions behind the scene that do computation and rendering graphs. The backend data pipeline is stubbed using pre-processed CSV files of data fetched manually from Github GraphQL API. However, the connection between the data and the GUI is designed so that the GUI can work with a full-fledged data pipeline. As a result, for future work, we hope to extend our application functionality so that it has a functional backend data pipeline that can take in a user input command to fetch data directly from Github API, process it, and then display information.

Besides having a fully functional application with a backend data pipeline, the following features can be added to the application:
* Users can combine graphs and compare metrics.
* Users can compare the performance and metrics of a Github account to another (or multiple other) account(s).
* Users can manually add texts and annotations to graphs generated by the application.
* Users can export graphs and reports into pdf or image formats (e.g., PNG, and JPEG)

Keeping the future direction in mind, we will design and build the UI to enable as clean as possible of a switch between loading the data from CSV to loading the data via API. One such area of potential reuse/repurpose would be the portions of the application (GUI, controller, and model classes) responsible for taking in an input file -- in our case, the data itself will be ingested, but in the future state, a CSV of GitHub usernames may serve as the entry point.

Additionally, our current code reads and processes .ui files (which are XML files of our app interface generated by the Qt Designer app) and then adds functions to the UI using Python code. The fact that our code has to read and process XML files first slows down our app on start-up. In the future, this could be avoided by converting the XML files into Python codes and objects and work with them directly without having to read and process the .ui files

== Contributors ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Related Links ==
* [https://github.ncsu.edu/anguyen9/pyqt_UI Github repo]

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:24:55Z

Jdjohns4: /* PyQt Interface */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:24:36Z

Jdjohns4: /* Testing */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:23:49Z

Jdjohns4: /* Test results */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:21:58Z

Jdjohns4: /* Test plan */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:19:38Z

Jdjohns4: /* Test plan */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:12:18Z

Jdjohns4: /* Future Work */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:11:45Z

Jdjohns4: /* Future Direction */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-13T00:11:08Z

Jdjohns4: /* Topic Overview */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-08T01:44:30Z

Jdjohns4: /* Mockup Design */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-08T01:42:20Z

Jdjohns4: /* Mockup Design */

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-08T01:26:49Z

Jdjohns4: /* Mockup Design */

File:G2335 - mockup openfile.png

2023-04-08T01:26:11Z

Jdjohns4: Mockup showing file open dialogue

Mockup showing file open dialogue

File:G2335 - mockup chart histogram.png

2023-04-08T01:24:35Z

Jdjohns4: Mockup of chart popup showing histogram

Mockup of chart popup showing histogram

File:G2335 - mockup chart boxplot.png

2023-04-08T01:20:58Z

Jdjohns4: Mockup of chart popup showing matplotlib generated boxplot

Mockup of chart popup showing matplotlib generated boxplot

File:G2335 - mockup table lowest ranked.png

2023-04-08T01:20:14Z

Jdjohns4: Mockup table showing lowest ranked users

Mockup table showing lowest ranked users

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-08T01:16:44Z

Jdjohns4: /* Mockup Design */

File:G2335 - mockup table summary stats.png

2023-04-08T01:15:31Z

Jdjohns4: Mockup of summary stats panel

Mockup of summary stats panel

CSC/ECE 517 Spring 2023 -G2335. Develop Frontend UI Interface for GraphQL Query

2023-04-04T11:50:25Z

Jdjohns4: page created

== Background ==

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-28T01:57:11Z

Jdjohns4: /* edit */

== Background ==

=== Current State ===
Currently, in '''[https://github.com/expertiza/expertiza Expertiza]''' there is a model class called '''QuizQuestion''' which serves as a superclass of classes '''MultipleChoiceCheckbox''', '''MultipleChoiceRadio''', and '''TrueFalse'''.

There are four methods in the '''QuizQuestion''' superclass which return HTML strings, depending on the question type:
* ''edit'' -- What to display if an instructor (etc.) is creating or editing a questionnaire (questionnaires_controller.rb)
* ''view_question_text'' -- What to display if an instructor (etc.) is viewing a questionnaire (questionnaires_controller.rb)
* ''view_completed_question'' -- What to display if a student is viewing a filled-out questionnaire (response_controller.rb)
* ''complete'' -- What to display if a student is filling out a questionnaire (response_controller.rb)

Additionally, the inheriting classes contain a method ''isvalid'' that is not in '''QuizQuestion'''.

Included below is the UML diagram of the design of the QuizQuestion and its child classes in the current state

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

=== Our Implementation Project ===
For this project, we are tasked with '''redesigning the above UML diagram''' and '''reimplementing the five methods''' (mentioned in the previous section) in the superclass (''QuizQuestion''). The reimplementation of the methods in the superclass will provide inheritances to the subclasses (''MultipleChoiceCheckbox'', ''MultipleChoiceRadio'', and ''TrueFalse''), and will use overriding/overloading to avoid type-checking.

Included below is the redesign of the UML diagram of the relationship between ''QuizQuestion'' and its child classes. As shown in the diagram, all methods are moved to the parent class. Child classes either inherit purely from the parent class' methods or extend it through overriding/overloading.

'''Note''' that the methods reimplemented in the parent class (''QuizQuestion'') still render HTML components to provide to the front-end (through the ''response_controller.rb'' and ''questionnaires_controller.rb'').

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

=== Overview and Test Suite Video ===
A video summarizing our work and display our successful run of RSpec test cases can be viewed [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view here]

=== Future Direction ===
In the future, as the '''Expertiza''' app is being migrated to the combination of Ruby API and React front-end (instead of legacy Rails), these methods will be modified to use Ruby API, and to handle and return React objects for the front-end.

As part of our work on this project, we implemented a sample API controller that is able to return QuizQuestion child classes in JSON form. We believe this would be an initial step in converting the QuizQuestion models for use with a Ruby back-end / React front-end approach.

As this was not formally part of our project requirements, we have left our work in a draft pull request on our [https://github.com/amjacob2/reimplementation-back-end/pull/10 repository]

The following links are to our demonstration API instance on the NCSU VCL:
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Multiple Choice Checkbox]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceRadio Multiple Choice Radio]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=TrueFalse True False]

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Reimplementation Details==

=== isvalid ===
'''isvalid''' method is implemented in all subclasses but not the superclass. The majority of these implementations are repetitive. Hence, the method is reimplemented and moved to the superclass (''quiz_question.rb''). In the subclasses, this method is inherited ('''MultipleChoiceRadio''' and ''TrueFalse''') with the exception of '''MultipleChoiceCheckbox''' where the method is extended. The implementation of '''isvalid''' is shown below

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice', foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def isvalid(choice_info)
@valid = 'valid'
return @valid = 'Please make sure all questions have text' if txt == ''
@correct_count = 0
choice_info.each_value do |value|
if (value[:txt] == '') || value[:txt].empty? || value[:txt].nil?
@valid = 'Please make sure every question has text for all options'
return @valid
end
@correct_count += 1 if value[:iscorrect]
end
@valid = 'Please select a correct answer for all questions' if @correct_count.zero?
@valid = 'Please select only one correct answer for all questions' if @correct_count > 1
@valid
end
end </nowiki>

<nowiki>
# multiple_choice_checkbox.rb
class MultipleChoiceCheckbox < QuizQuestion
... [other methods] ...

def isvalid(choice_info)
super
if @correct_count == 1
@valid = 'A multiple-choice checkbox question should have more than one correct answer.'
end
@valid = 'valid' if @correct_count > 1
@valid
end
end </nowiki>

=== edit ===
The edit method was originally not implemented within ''QuizQuestion'' and each of the child classes had their own implementation. These implementations had the exact same beginning HTML block:

<nowiki>
html = '<tr><td>'
html += '<textarea cols="100" name="question[' + id.to_s + '][txt]" '
html += 'id="question_' + id.to_s + '_txt">' + txt + '</textarea>'
html += '</td></tr>'

html += '<tr><td>'
html += 'Question Weight: '
html += '<input type="number" name="question_weights[' + id.to_s + '][txt]" '
html += 'id="question_wt_' + id.to_s + '_txt" '
html += 'value="' + weight.to_s + '" min="0" />'
html += '</td></tr>' </nowiki>

Given this, we were able to move this block up to the edit method within the parent ''QuizQuesiton'' class, and extend the method in the child classes. Each of the child classes differed in how their type of question was displayed, so each still has a custom implementation of the edit method.

An example from ''TrueFalse'':
<nowiki>
def edit
html = super

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="True" '
html += 'checked="checked" ' if self.quiz_question_choices[0].iscorrect
html += '/>True'
html += '</td></tr>'

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="False" '
html += 'checked="checked" ' if self.quiz_question_choices[1].iscorrect
html += '/>False'
html += '</td></tr>'

html.html_safe
end </nowiki>

We implemented tests for the edit method in both the parent ''QuizQuestion'' class to verify the preamble HTML is being returned as expected, and in each test class for the three subclasses to verify their specific implementations of edit are returning the HTML as expected.

=== complete ===

The complete method was initially not implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, I removed it from its subclass and moved it to the superclass in quiz_question.rb. It generates HTML code for completing a question. The quiz question's associated answer alternatives are displayed and can be selected using radio buttons.
The implementation of '''complete''' is shown below-

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice',
foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def complete
quiz_question_choices = self.quiz_question_choices
html = '<label for="' + id.to_s + '">' + txt + '</label><br>'
[0, 1, 2, 3].each do |i|
html += '<input name = ' + "\"#{id}\" "
html += 'id = ' + "\"#{id}" + '_' + "#{i + 1}\" "
html += 'value = ' + "\"#{quiz_question_choices[i].txt}\" "
html += 'type="radio"/>'
html += quiz_question_choices[i].txt.to_s
html += '</br>'
end
html
end
</nowiki>

The following test case has been added to test complete method-
<nowiki>
describe "#complete" do
before do
id = quiz_question.id
expected_html = "<label for=\"" + id.to_s + "\">Question Text</label><br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_1\" value = \"Choice 1\" type=\"radio\"/>Choice 1</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_2\" value = \"Choice 2\" type=\"radio\"/>Choice 2</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_3\" value = \"Choice 3\" type=\"radio\"/>Choice 3</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_4\" value = \"Choice 4\" type=\"radio\"/>Choice 4</br>"
expect(quiz_question.complete).to eq(expected_html)
end
it "returns the completed HTML for the quiz question" do
end
end </nowiki>

=== view_completed_question ===

The view_completed_question method was also not initially implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, we removed it from its subclass and moved it to the superclass in quiz_question.rb. The HTML code generated by this program is used to check the completed question and also to verify the response of the user. An indication is provided that indicates whether the user's response was right or wrong, and it is highlighted with help of check or delete icon which you can find here-[https://github.com/amjacob2/reimplementation-back-end/tree/main/app/assets/images assets/images].

The implementation of '''view_completed_question''' is shown below-
<nowiki>
def view_completed_question(user_answer)
quiz_question_choices = self.quiz_question_choices

html = ''
quiz_question_choices.each do |answer|
html += if answer.iscorrect
'<b>' + answer.txt + '</b> -- Correct <br>'
else
answer.txt + '<br>'
end
end

html += '<br>Your answer is: '
html += '<b>' + user_answer.first.comments.to_s + '</b>'
html += if user_answer.first.answer == 1
'<img src="/assets/Check-icon.png"/>'
else
'<img src="/assets/delete_icon.png"/>'
end
html += '</b>'
html += '<br><br><hr>'
html.html_safe
end </nowiki>

The following test case has been added to test view_completed_question method-
<nowiki>
describe '#view_completed_question' do
it 'returns the correct HTML for a completed question' do
quiz_question = QuizQuestion.new(txt: 'which is the latest Iphone?')
quiz_question_choice_1 = QuizQuestionChoice.new(txt: 'Iphone14', iscorrect: true)
quiz_question_choice_2 = QuizQuestionChoice.new(txt: 'Iphone13', iscorrect: false)
quiz_question_choice_3 = QuizQuestionChoice.new(txt: 'Iphone12', iscorrect: false)
quiz_question.quiz_question_choices << quiz_question_choice_1
quiz_question.quiz_question_choices << quiz_question_choice_2
quiz_question.quiz_question_choices << quiz_question_choice_3
user_answer = double('user_answer')
allow(user_answer).to receive_message_chain(:first, :comments).and_return('Iphone14')
allow(user_answer).to receive_message_chain(:first, :answer).and_return(1)
expected_html = '<b>Iphone14</b> -- Correct <br>Iphone13<br>Iphone12<br><br>Your answer is: <b>Iphone14</b><img src="/assets/Check-icon.png"/></b><br><br><hr>'
expect(quiz_question.view_completed_question(user_answer)).to eq(expected_html)
end
end </nowiki>

=== QuizQuestionChoice ===
The ''QuizQuestionChoice'' class represents a single choice in a true/false or multiple choice question. A QuizQuestion or QuizQuestion subclass has a 'has_many' relationship with QuizQuestionChoice. In the original implementation, every method that referenced the QuizQuestion's QuizQuestionChoices would do a retrieve -- this single line of code was duplicated multiple times through the four classes.

In order to improve this, we moved the fetching of a QuizQuestion's QuizQuestionChoices into a method that is run after an instance is initialized. From there the QuizQuestionChoices can be referenced as an instance variable instead of having the same fetch referenced over and over.

The referenced method from the new implementation of QuizQuestion:
<nowiki>
after_initialize :load_choices
def load_choices
@quiz_question_choices = QuizQuestionChoice.where(question_id: id)
end </nowiki>

== Test Plan ==

=== Overall Plan ===
The overall plan is to perform automated RSpec testing of all the methods that have been moved to the superclass, namely ''QuizQuestion''. These methods are:
* ''edit''
* ''view_question_text''
* ''complete''
* ''view_completed_question''
* ''isvalid''

Most tests will test the methods in ''QuizQuestion'' class as the subclasses mainly inherit these methods without extension. These test will be included in ''quiz_question_spec.rb'' (full path: /spec/requests/model/quiz_question_spec.rb). Methods that are extended by subclasses will also be tested in a separate spec file. For example, ''isvalid'' method is fully tested for ''QuizQuestion'' model in ''quiz_question_spec.rb''. Since ''TrueFalse'' and ''MultipleChoiceRadio'' inherit this method fully from the superclass without extension, no extra test is created to test the method for the two subclasses. However, ''MultipleChoiceCheckbox'' extended the ''isvalid'' method. As a result, extra tests are created to test ''isvalid'' for ''MultipleChoiceCheckbox''; these tests are then included in ''multiple_choice_checkbox_spec.rb''

=== edit ===
The goal in our automated testing of the edit function is to ensure that, given a QuizQuestion or QuizQuestion subclass object, the edit method of the class should display the HTML returned for the edit functionality as expected. In each of our Rspec test files, an object of the class under test (QuizQuestion or subclasses) is created to simulate what a similar database-driven object would appear like to our model classes.

As the edit function in each class is slightly different, we implemented specific tests for each of the classes we reimplemented.

* Within ''spec/requests/model/quiz_question_spec.rb'' the edit method is tested to ensure the default question prefix HTML is returned.
* Within ''spec/requests/model/true_false_spec.rb'', ''spec/requests/model/multiple_choice_radio_spec.rb'', and ''spec/requests/model/multiple_choice_checkbox_spec.rb'' the edit method is tested to ensure given an object filled out with QuizQuestionChoices, question text, question id, and weight the HTML is rendered appropriately.

These tests will fail if the underlying HTML returned from the model changes, which would be indicative of possible negative downstream effects in the application where the QuizQuestion subclasses are used.

=== isvalid ===
To test '''isvalid''' several tests were written to check for the behavior and returns of the method:
* Test the return message if the input contains text for the question prompt, text for all question choices, and only one of the choices is correct '''(expect "valid")'''
* Test the return message if the input is missing text for the question prompt '''(expect "Please make sure all questions have text")'''
* Test the return message if the input is missing text for at least one of the question choices '''(expect "Please make sure every question has text for all options")'''
* Test the return message if the input provides no correct answer '''(expect "Please select a correct answer for all questions")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "Please select only one correct answer for all questions")'''

'''isvalid''' is extended in '''MultipleChoiceCheckbox''' as the requirements for '''MultipleChoiceCheckbox''' to be valid are slightly different from those of '''QuizQuestion''', '''TrueFalse''', and '''MultipleChoiceRadio'''
* Test the return message if the input provides only 1 correct answer '''(expect "A multiple-choice checkbox question should have more than one correct answer.")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "valid")'''

<nowiki>
# quiz_question_spec.rb
require 'swagger_helper'

describe QuizQuestion do
let(:quiz_question) { QuizQuestion.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when the question and its choices have valid text' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('valid')
end
end
end
describe '#isvaid' do
let(:no_text_question) {QuizQuestion.new}
context 'when the question itself does not have txt' do
it 'returns "Please make sure all questions have text"' do
allow(no_text_question).to receive(:txt).and_return('')
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(no_text_question.isvalid(questions)).to eq('Please make sure all questions have text')
end
end
end
describe '#isvalid' do
context 'when a choice does not have text' do
it 'returns "Please make sure every question has text for all options"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: '', iscorrect: true },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please make sure every question has text for all options')
end
end
end
describe '#isvalid' do
context 'when no choices are correct' do
it 'returns "Please select a correct answer for all questions"' do
questions = { '1' => { txt: 'question text', iscorrect: false }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please select a correct answer for all questions')
end
end
end
describe '#isvalid' do
context 'when there are more than one correct choices' do
it 'returns "Please select only one correct answer for all questions"' do
questions = questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(quiz_question.isvalid(questions)).to eq('Please select only one correct answer for all questions')
end
end
end
end </nowiki>

Extended tests for '''isvalid''' in '''MultipleChoiceCheckbox'''
<nowiki>
# multiple_choice_checkbox+spec.rb
require 'swagger_helper'

describe MultipleChoiceCheckbox do
let(:multiple_choice_question) { MultipleChoiceCheckbox.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when there is only 1 correct answer' do
it 'returns "A multiple-choice checkbox question should have more than one correct answer."' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(multiple_choice_question.isvalid(questions)).to eq('A multiple-choice checkbox question should have more than one correct answer.')
end
end
end

describe '#isvalid' do
context 'when there is more than 1 correct answer' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(multiple_choice_question.isvalid(questions)).to eq('valid')
end
end
end
end </nowiki>

=== view_question_text ===
The test for '''view_question_text''' is fairly straight forward as once the question input passes '''isvalid''', we only need to make sure that view_question_text display the information in a predetermined format. The test for '''view_question_text''' is shown below
<nowiki>
describe '#view_question_text' do
it 'returns the text of the questions' do
weight = quiz_question.weight
expect(quiz_question.view_question_text).to eq('<b>Question Text</b><br />Question Type: MultipleChoiceRadio<br />Question Weight: ' +
weight.to_s + '<br /> - <b>Choice 1</b><br /> - Choice 2<br /> - Choice 3<br /> -
Choice 4<br /> <br />')
end
end </nowiki>

=== RSpec Test Setup ===
Note that for each test file we included a ''before'' block that setup a QuizQuestion subclass object of the given type being tested, assigned it the required parameters, and assigned ''QuizQuestionChoices'' that matched the type of question. Doing this allowed us to simulate in the test how the object would be used within the greater context of the application.

Example test setup from ''quiz_question_spec.rb'':
<nowiki>
let(:quiz_question) { QuizQuestion.new }
let(:quiz_question_choice1) { QuizQuestionChoice.new }
let(:quiz_question_choice2) { QuizQuestionChoice.new }
let(:quiz_question_choice3) { QuizQuestionChoice.new }
let(:quiz_question_choice4) { QuizQuestionChoice.new }
before(:each) do
quiz_question.quiz_question_choices = [quiz_question_choice1, quiz_question_choice2, quiz_question_choice3, quiz_question_choice4]
quiz_question.txt = 'Question Text'
allow(quiz_question).to receive(:type).and_return('MultipleChoiceRadio')
allow(quiz_question).to receive(:id).and_return(99)
allow(quiz_question).to receive(:weight).and_return(5)
allow(quiz_question_choice1).to receive(:txt).and_return('Choice 1')
allow(quiz_question_choice1).to receive(:question_id).and_return(99)
allow(quiz_question_choice1).to receive(:iscorrect?).and_return(true)
allow(quiz_question_choice2).to receive(:txt).and_return('Choice 2')
allow(quiz_question_choice2).to receive(:question_id).and_return(99)
allow(quiz_question_choice2).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice3).to receive(:txt).and_return('Choice 3')
allow(quiz_question_choice3).to receive(:question_id).and_return(99)
allow(quiz_question_choice3).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice4).to receive(:txt).and_return('Choice 4')
allow(quiz_question_choice4).to receive(:question_id).and_return(99)
allow(quiz_question_choice4).to receive(:iscorrect?).and_return(false)
end </nowiki>

== Methods in Files Modified/Created ==
'''isvalid''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb'' and ''true_false.rb''
* Extended in ''multiple_choice_checkbox.rb''
* Modified ''quiz_question_spec.rb'' and ''multiple_choice_checkbox_spec.rb'' to include tests for the method.

'''view_question_text''' method
* left as is in ''quiz_question.rb''

'''complete''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for complete method in ''quiz_question_spec.rb''.

'''view_completed_question''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for view_completed_question method in ''quiz_question_spec.rb''.

'''edit''' method
* Implemented in ''quiz_question.rb''
* Extended in ''multiple_choice_radio.rb'', ''multiple_choice_checkbox.rb'', and ''true_false.rb''
* Tests cases added in ''quiz_question_spec.rb'', ''multiple_choice_checkbox_spec.rb'', and ''true_false_spec.rb''

== Additional Files Created ==
As part of our reimplementation, we needed to pull in some existing model classes from Expertiza in order to allow us to fully test our reimplemented models. These files were copied from the latest Expteriza main branch as of Program 3 assignment and were not modified. These files include:
* app/models/question.rb
* app/models/questionnaire.rb
* app/models/quiz_quesiton_choice.rb

Additionally we created migration from these models (and our reimplemented classes):
* db/migrate/20230311214056_create_quiz_questions.rb
* db/migrate/20230314152206_create_questionnaires.rb
* db/migrate/20230314152945_create_questions.rb
* db/migrate/20230314153211_add_key_to_questions.rb
* db/migrate/20230315172116_create_quiz_question_choices.rb

== Executing Tests ==
* To run the test suite written for our project, use the following command:
<nowiki> bundle exec rspec spec/requests/model </nowiki>
* To run individual test files (separated by model that is being tested), use the following command:
<nowiki> bundle exec rspec spec/requests/model/test_file_name.rb </nowiki>

==Useful Links==
* [https://github.com/amjacob2/reimplementation-back-end.git Our Github Forked Repo]
* [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view Demo and Test Suite Video]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Future Work API demo]
* [https://github.com/amjacob2/reimplementation-back-end/pull/10 Future Work API sample]
* [https://github.com/expertiza/reimplementation-back-end/pull/6 Pull request]

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-28T01:56:21Z

Jdjohns4: /* Overall Plan */

== Background ==

=== Current State ===
Currently, in '''[https://github.com/expertiza/expertiza Expertiza]''' there is a model class called '''QuizQuestion''' which serves as a superclass of classes '''MultipleChoiceCheckbox''', '''MultipleChoiceRadio''', and '''TrueFalse'''.

There are four methods in the '''QuizQuestion''' superclass which return HTML strings, depending on the question type:
* ''edit'' -- What to display if an instructor (etc.) is creating or editing a questionnaire (questionnaires_controller.rb)
* ''view_question_text'' -- What to display if an instructor (etc.) is viewing a questionnaire (questionnaires_controller.rb)
* ''view_completed_question'' -- What to display if a student is viewing a filled-out questionnaire (response_controller.rb)
* ''complete'' -- What to display if a student is filling out a questionnaire (response_controller.rb)

Additionally, the inheriting classes contain a method ''isvalid'' that is not in '''QuizQuestion'''.

Included below is the UML diagram of the design of the QuizQuestion and its child classes in the current state

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

=== Our Implementation Project ===
For this project, we are tasked with '''redesigning the above UML diagram''' and '''reimplementing the five methods''' (mentioned in the previous section) in the superclass (''QuizQuestion''). The reimplementation of the methods in the superclass will provide inheritances to the subclasses (''MultipleChoiceCheckbox'', ''MultipleChoiceRadio'', and ''TrueFalse''), and will use overriding/overloading to avoid type-checking.

Included below is the redesign of the UML diagram of the relationship between ''QuizQuestion'' and its child classes. As shown in the diagram, all methods are moved to the parent class. Child classes either inherit purely from the parent class' methods or extend it through overriding/overloading.

'''Note''' that the methods reimplemented in the parent class (''QuizQuestion'') still render HTML components to provide to the front-end (through the ''response_controller.rb'' and ''questionnaires_controller.rb'').

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

=== Overview and Test Suite Video ===
A video summarizing our work and display our successful run of RSpec test cases can be viewed [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view here]

=== Future Direction ===
In the future, as the '''Expertiza''' app is being migrated to the combination of Ruby API and React front-end (instead of legacy Rails), these methods will be modified to use Ruby API, and to handle and return React objects for the front-end.

As part of our work on this project, we implemented a sample API controller that is able to return QuizQuestion child classes in JSON form. We believe this would be an initial step in converting the QuizQuestion models for use with a Ruby back-end / React front-end approach.

As this was not formally part of our project requirements, we have left our work in a draft pull request on our [https://github.com/amjacob2/reimplementation-back-end/pull/10 repository]

The following links are to our demonstration API instance on the NCSU VCL:
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Multiple Choice Checkbox]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceRadio Multiple Choice Radio]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=TrueFalse True False]

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Reimplementation Details==

=== isvalid ===
'''isvalid''' method is implemented in all subclasses but not the superclass. The majority of these implementations are repetitive. Hence, the method is reimplemented and moved to the superclass (''quiz_question.rb''). In the subclasses, this method is inherited ('''MultipleChoiceRadio''' and ''TrueFalse''') with the exception of '''MultipleChoiceCheckbox''' where the method is extended. The implementation of '''isvalid''' is shown below

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice', foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def isvalid(choice_info)
@valid = 'valid'
return @valid = 'Please make sure all questions have text' if txt == ''
@correct_count = 0
choice_info.each_value do |value|
if (value[:txt] == '') || value[:txt].empty? || value[:txt].nil?
@valid = 'Please make sure every question has text for all options'
return @valid
end
@correct_count += 1 if value[:iscorrect]
end
@valid = 'Please select a correct answer for all questions' if @correct_count.zero?
@valid = 'Please select only one correct answer for all questions' if @correct_count > 1
@valid
end
end </nowiki>

<nowiki>
# multiple_choice_checkbox.rb
class MultipleChoiceCheckbox < QuizQuestion
... [other methods] ...

def isvalid(choice_info)
super
if @correct_count == 1
@valid = 'A multiple-choice checkbox question should have more than one correct answer.'
end
@valid = 'valid' if @correct_count > 1
@valid
end
end </nowiki>

=== edit ===
The edit method was originally not implemented within ''QuizQuestion'' and each of the child classes had their own implementation. These implementations had the exact same beginning HTML block:

<nowiki>
html = '<tr><td>'
html += '<textarea cols="100" name="question[' + id.to_s + '][txt]" '
html += 'id="question_' + id.to_s + '_txt">' + txt + '</textarea>'
html += '</td></tr>'

html += '<tr><td>'
html += 'Question Weight: '
html += '<input type="number" name="question_weights[' + id.to_s + '][txt]" '
html += 'id="question_wt_' + id.to_s + '_txt" '
html += 'value="' + weight.to_s + '" min="0" />'
html += '</td></tr>' </nowiki>

Given this, we were able to move this block up to the edit method within the parent ''QuizQuesiton'' class, and extend the method in the child classes. Each of the child classes differed in how their type of question was displayed, so each still has a custom implementation of the edit method.

An example from ''TrueFalse'':
<nowiki>
def edit
html = super

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="True" '
html += 'checked="checked" ' if self.quiz_question_choices[0].iscorrect
html += '/>True'
html += '</td></tr>'

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="False" '
html += 'checked="checked" ' if self.quiz_question_choices[1].iscorrect
html += '/>False'
html += '</td></tr>'

html.html_safe
end </nowiki>

We implemented tests for the edit method in both the parent ''QuizQuestion'' class to verify the preamble HTML is being returned as expected, and in each test class for the three subclasses to verify their specific implementations of edit are returning the HTML as expected.

=== complete ===

The complete method was initially not implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, I removed it from its subclass and moved it to the superclass in quiz_question.rb. It generates HTML code for completing a question. The quiz question's associated answer alternatives are displayed and can be selected using radio buttons.
The implementation of '''complete''' is shown below-

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice',
foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def complete
quiz_question_choices = self.quiz_question_choices
html = '<label for="' + id.to_s + '">' + txt + '</label><br>'
[0, 1, 2, 3].each do |i|
html += '<input name = ' + "\"#{id}\" "
html += 'id = ' + "\"#{id}" + '_' + "#{i + 1}\" "
html += 'value = ' + "\"#{quiz_question_choices[i].txt}\" "
html += 'type="radio"/>'
html += quiz_question_choices[i].txt.to_s
html += '</br>'
end
html
end
</nowiki>

The following test case has been added to test complete method-
<nowiki>
describe "#complete" do
before do
id = quiz_question.id
expected_html = "<label for=\"" + id.to_s + "\">Question Text</label><br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_1\" value = \"Choice 1\" type=\"radio\"/>Choice 1</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_2\" value = \"Choice 2\" type=\"radio\"/>Choice 2</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_3\" value = \"Choice 3\" type=\"radio\"/>Choice 3</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_4\" value = \"Choice 4\" type=\"radio\"/>Choice 4</br>"
expect(quiz_question.complete).to eq(expected_html)
end
it "returns the completed HTML for the quiz question" do
end
end </nowiki>

=== view_completed_question ===

The view_completed_question method was also not initially implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, we removed it from its subclass and moved it to the superclass in quiz_question.rb. The HTML code generated by this program is used to check the completed question and also to verify the response of the user. An indication is provided that indicates whether the user's response was right or wrong, and it is highlighted with help of check or delete icon which you can find here-[https://github.com/amjacob2/reimplementation-back-end/tree/main/app/assets/images assets/images].

The implementation of '''view_completed_question''' is shown below-
<nowiki>
def view_completed_question(user_answer)
quiz_question_choices = self.quiz_question_choices

html = ''
quiz_question_choices.each do |answer|
html += if answer.iscorrect
'<b>' + answer.txt + '</b> -- Correct <br>'
else
answer.txt + '<br>'
end
end

html += '<br>Your answer is: '
html += '<b>' + user_answer.first.comments.to_s + '</b>'
html += if user_answer.first.answer == 1
'<img src="/assets/Check-icon.png"/>'
else
'<img src="/assets/delete_icon.png"/>'
end
html += '</b>'
html += '<br><br><hr>'
html.html_safe
end </nowiki>

The following test case has been added to test view_completed_question method-
<nowiki>
describe '#view_completed_question' do
it 'returns the correct HTML for a completed question' do
quiz_question = QuizQuestion.new(txt: 'which is the latest Iphone?')
quiz_question_choice_1 = QuizQuestionChoice.new(txt: 'Iphone14', iscorrect: true)
quiz_question_choice_2 = QuizQuestionChoice.new(txt: 'Iphone13', iscorrect: false)
quiz_question_choice_3 = QuizQuestionChoice.new(txt: 'Iphone12', iscorrect: false)
quiz_question.quiz_question_choices << quiz_question_choice_1
quiz_question.quiz_question_choices << quiz_question_choice_2
quiz_question.quiz_question_choices << quiz_question_choice_3
user_answer = double('user_answer')
allow(user_answer).to receive_message_chain(:first, :comments).and_return('Iphone14')
allow(user_answer).to receive_message_chain(:first, :answer).and_return(1)
expected_html = '<b>Iphone14</b> -- Correct <br>Iphone13<br>Iphone12<br><br>Your answer is: <b>Iphone14</b><img src="/assets/Check-icon.png"/></b><br><br><hr>'
expect(quiz_question.view_completed_question(user_answer)).to eq(expected_html)
end
end </nowiki>

=== QuizQuestionChoice ===
The ''QuizQuestionChoice'' class represents a single choice in a true/false or multiple choice question. A QuizQuestion or QuizQuestion subclass has a 'has_many' relationship with QuizQuestionChoice. In the original implementation, every method that referenced the QuizQuestion's QuizQuestionChoices would do a retrieve -- this single line of code was duplicated multiple times through the four classes.

In order to improve this, we moved the fetching of a QuizQuestion's QuizQuestionChoices into a method that is run after an instance is initialized. From there the QuizQuestionChoices can be referenced as an instance variable instead of having the same fetch referenced over and over.

The referenced method from the new implementation of QuizQuestion:
<nowiki>
after_initialize :load_choices
def load_choices
@quiz_question_choices = QuizQuestionChoice.where(question_id: id)
end </nowiki>

== Test Plan ==

=== Overall Plan ===
The overall plan is to perform automated RSpec testing of all the methods that have been moved to the superclass, namely ''QuizQuestion''. These methods are:
* ''edit''
* ''view_question_text''
* ''complete''
* ''view_completed_question''
* ''isvalid''

Most tests will test the methods in ''QuizQuestion'' class as the subclasses mainly inherit these methods without extension. These test will be included in ''quiz_question_spec.rb'' (full path: /spec/requests/model/quiz_question_spec.rb). Methods that are extended by subclasses will also be tested in a separate spec file. For example, ''isvalid'' method is fully tested for ''QuizQuestion'' model in ''quiz_question_spec.rb''. Since ''TrueFalse'' and ''MultipleChoiceRadio'' inherit this method fully from the superclass without extension, no extra test is created to test the method for the two subclasses. However, ''MultipleChoiceCheckbox'' extended the ''isvalid'' method. As a result, extra tests are created to test ''isvalid'' for ''MultipleChoiceCheckbox''; these tests are then included in ''multiple_choice_checkbox_spec.rb''

=== edit ===
The goal in our automated testing of the edit function is to ensure that, given a QuizQuestion or QuizQuestion subclass object, the edit method of the class should display the HTML returned for the edit functionality as expected. In each of our Rspec test files, an object of the class under test (QuizQuestion or subclasses) is created to simulate what a similar database-driven object would appear like to our model classes.

* Within ''spec/requests/model/quiz_question_spec.rb'' the edit method is tested to ensure the default question prefix HTML is returned.
* Within ''spec/requests/model/true_false_spec.rb'', ''spec/requests/model/multiple_choice_radio_spec.rb'', and ''spec/requests/model/multiple_choice_checkbox_spec.rb'' the edit method is tested to ensure given an object filled out with QuizQuestionChoices, question text, question id, and weight the HTML is rendered appropriately.

These tests will fail if the underlying HTML returned from the model changes, which would be indicative of possible negative downstream effects in the application where the QuizQuestion subclasses are used.

=== isvalid ===
To test '''isvalid''' several tests were written to check for the behavior and returns of the method:
* Test the return message if the input contains text for the question prompt, text for all question choices, and only one of the choices is correct '''(expect "valid")'''
* Test the return message if the input is missing text for the question prompt '''(expect "Please make sure all questions have text")'''
* Test the return message if the input is missing text for at least one of the question choices '''(expect "Please make sure every question has text for all options")'''
* Test the return message if the input provides no correct answer '''(expect "Please select a correct answer for all questions")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "Please select only one correct answer for all questions")'''

'''isvalid''' is extended in '''MultipleChoiceCheckbox''' as the requirements for '''MultipleChoiceCheckbox''' to be valid are slightly different from those of '''QuizQuestion''', '''TrueFalse''', and '''MultipleChoiceRadio'''
* Test the return message if the input provides only 1 correct answer '''(expect "A multiple-choice checkbox question should have more than one correct answer.")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "valid")'''

<nowiki>
# quiz_question_spec.rb
require 'swagger_helper'

describe QuizQuestion do
let(:quiz_question) { QuizQuestion.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when the question and its choices have valid text' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('valid')
end
end
end
describe '#isvaid' do
let(:no_text_question) {QuizQuestion.new}
context 'when the question itself does not have txt' do
it 'returns "Please make sure all questions have text"' do
allow(no_text_question).to receive(:txt).and_return('')
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(no_text_question.isvalid(questions)).to eq('Please make sure all questions have text')
end
end
end
describe '#isvalid' do
context 'when a choice does not have text' do
it 'returns "Please make sure every question has text for all options"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: '', iscorrect: true },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please make sure every question has text for all options')
end
end
end
describe '#isvalid' do
context 'when no choices are correct' do
it 'returns "Please select a correct answer for all questions"' do
questions = { '1' => { txt: 'question text', iscorrect: false }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please select a correct answer for all questions')
end
end
end
describe '#isvalid' do
context 'when there are more than one correct choices' do
it 'returns "Please select only one correct answer for all questions"' do
questions = questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(quiz_question.isvalid(questions)).to eq('Please select only one correct answer for all questions')
end
end
end
end </nowiki>

Extended tests for '''isvalid''' in '''MultipleChoiceCheckbox'''
<nowiki>
# multiple_choice_checkbox+spec.rb
require 'swagger_helper'

describe MultipleChoiceCheckbox do
let(:multiple_choice_question) { MultipleChoiceCheckbox.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when there is only 1 correct answer' do
it 'returns "A multiple-choice checkbox question should have more than one correct answer."' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(multiple_choice_question.isvalid(questions)).to eq('A multiple-choice checkbox question should have more than one correct answer.')
end
end
end

describe '#isvalid' do
context 'when there is more than 1 correct answer' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(multiple_choice_question.isvalid(questions)).to eq('valid')
end
end
end
end </nowiki>

=== view_question_text ===
The test for '''view_question_text''' is fairly straight forward as once the question input passes '''isvalid''', we only need to make sure that view_question_text display the information in a predetermined format. The test for '''view_question_text''' is shown below
<nowiki>
describe '#view_question_text' do
it 'returns the text of the questions' do
weight = quiz_question.weight
expect(quiz_question.view_question_text).to eq('<b>Question Text</b><br />Question Type: MultipleChoiceRadio<br />Question Weight: ' +
weight.to_s + '<br /> - <b>Choice 1</b><br /> - Choice 2<br /> - Choice 3<br /> -
Choice 4<br /> <br />')
end
end </nowiki>

=== RSpec Test Setup ===
Note that for each test file we included a ''before'' block that setup a QuizQuestion subclass object of the given type being tested, assigned it the required parameters, and assigned ''QuizQuestionChoices'' that matched the type of question. Doing this allowed us to simulate in the test how the object would be used within the greater context of the application.

Example test setup from ''quiz_question_spec.rb'':
<nowiki>
let(:quiz_question) { QuizQuestion.new }
let(:quiz_question_choice1) { QuizQuestionChoice.new }
let(:quiz_question_choice2) { QuizQuestionChoice.new }
let(:quiz_question_choice3) { QuizQuestionChoice.new }
let(:quiz_question_choice4) { QuizQuestionChoice.new }
before(:each) do
quiz_question.quiz_question_choices = [quiz_question_choice1, quiz_question_choice2, quiz_question_choice3, quiz_question_choice4]
quiz_question.txt = 'Question Text'
allow(quiz_question).to receive(:type).and_return('MultipleChoiceRadio')
allow(quiz_question).to receive(:id).and_return(99)
allow(quiz_question).to receive(:weight).and_return(5)
allow(quiz_question_choice1).to receive(:txt).and_return('Choice 1')
allow(quiz_question_choice1).to receive(:question_id).and_return(99)
allow(quiz_question_choice1).to receive(:iscorrect?).and_return(true)
allow(quiz_question_choice2).to receive(:txt).and_return('Choice 2')
allow(quiz_question_choice2).to receive(:question_id).and_return(99)
allow(quiz_question_choice2).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice3).to receive(:txt).and_return('Choice 3')
allow(quiz_question_choice3).to receive(:question_id).and_return(99)
allow(quiz_question_choice3).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice4).to receive(:txt).and_return('Choice 4')
allow(quiz_question_choice4).to receive(:question_id).and_return(99)
allow(quiz_question_choice4).to receive(:iscorrect?).and_return(false)
end </nowiki>

== Methods in Files Modified/Created ==
'''isvalid''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb'' and ''true_false.rb''
* Extended in ''multiple_choice_checkbox.rb''
* Modified ''quiz_question_spec.rb'' and ''multiple_choice_checkbox_spec.rb'' to include tests for the method.

'''view_question_text''' method
* left as is in ''quiz_question.rb''

'''complete''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for complete method in ''quiz_question_spec.rb''.

'''view_completed_question''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for view_completed_question method in ''quiz_question_spec.rb''.

'''edit''' method
* Implemented in ''quiz_question.rb''
* Extended in ''multiple_choice_radio.rb'', ''multiple_choice_checkbox.rb'', and ''true_false.rb''
* Tests cases added in ''quiz_question_spec.rb'', ''multiple_choice_checkbox_spec.rb'', and ''true_false_spec.rb''

== Additional Files Created ==
As part of our reimplementation, we needed to pull in some existing model classes from Expertiza in order to allow us to fully test our reimplemented models. These files were copied from the latest Expteriza main branch as of Program 3 assignment and were not modified. These files include:
* app/models/question.rb
* app/models/questionnaire.rb
* app/models/quiz_quesiton_choice.rb

Additionally we created migration from these models (and our reimplemented classes):
* db/migrate/20230311214056_create_quiz_questions.rb
* db/migrate/20230314152206_create_questionnaires.rb
* db/migrate/20230314152945_create_questions.rb
* db/migrate/20230314153211_add_key_to_questions.rb
* db/migrate/20230315172116_create_quiz_question_choices.rb

== Executing Tests ==
* To run the test suite written for our project, use the following command:
<nowiki> bundle exec rspec spec/requests/model </nowiki>
* To run individual test files (separated by model that is being tested), use the following command:
<nowiki> bundle exec rspec spec/requests/model/test_file_name.rb </nowiki>

==Useful Links==
* [https://github.com/amjacob2/reimplementation-back-end.git Our Github Forked Repo]
* [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view Demo and Test Suite Video]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Future Work API demo]
* [https://github.com/amjacob2/reimplementation-back-end/pull/10 Future Work API sample]
* [https://github.com/expertiza/reimplementation-back-end/pull/6 Pull request]

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-28T01:55:15Z

Jdjohns4: /* edit */

== Background ==

=== Current State ===
Currently, in '''[https://github.com/expertiza/expertiza Expertiza]''' there is a model class called '''QuizQuestion''' which serves as a superclass of classes '''MultipleChoiceCheckbox''', '''MultipleChoiceRadio''', and '''TrueFalse'''.

There are four methods in the '''QuizQuestion''' superclass which return HTML strings, depending on the question type:
* ''edit'' -- What to display if an instructor (etc.) is creating or editing a questionnaire (questionnaires_controller.rb)
* ''view_question_text'' -- What to display if an instructor (etc.) is viewing a questionnaire (questionnaires_controller.rb)
* ''view_completed_question'' -- What to display if a student is viewing a filled-out questionnaire (response_controller.rb)
* ''complete'' -- What to display if a student is filling out a questionnaire (response_controller.rb)

Additionally, the inheriting classes contain a method ''isvalid'' that is not in '''QuizQuestion'''.

Included below is the UML diagram of the design of the QuizQuestion and its child classes in the current state

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

=== Our Implementation Project ===
For this project, we are tasked with '''redesigning the above UML diagram''' and '''reimplementing the five methods''' (mentioned in the previous section) in the superclass (''QuizQuestion''). The reimplementation of the methods in the superclass will provide inheritances to the subclasses (''MultipleChoiceCheckbox'', ''MultipleChoiceRadio'', and ''TrueFalse''), and will use overriding/overloading to avoid type-checking.

Included below is the redesign of the UML diagram of the relationship between ''QuizQuestion'' and its child classes. As shown in the diagram, all methods are moved to the parent class. Child classes either inherit purely from the parent class' methods or extend it through overriding/overloading.

'''Note''' that the methods reimplemented in the parent class (''QuizQuestion'') still render HTML components to provide to the front-end (through the ''response_controller.rb'' and ''questionnaires_controller.rb'').

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

=== Overview and Test Suite Video ===
A video summarizing our work and display our successful run of RSpec test cases can be viewed [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view here]

=== Future Direction ===
In the future, as the '''Expertiza''' app is being migrated to the combination of Ruby API and React front-end (instead of legacy Rails), these methods will be modified to use Ruby API, and to handle and return React objects for the front-end.

As part of our work on this project, we implemented a sample API controller that is able to return QuizQuestion child classes in JSON form. We believe this would be an initial step in converting the QuizQuestion models for use with a Ruby back-end / React front-end approach.

As this was not formally part of our project requirements, we have left our work in a draft pull request on our [https://github.com/amjacob2/reimplementation-back-end/pull/10 repository]

The following links are to our demonstration API instance on the NCSU VCL:
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Multiple Choice Checkbox]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceRadio Multiple Choice Radio]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=TrueFalse True False]

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Reimplementation Details==

=== isvalid ===
'''isvalid''' method is implemented in all subclasses but not the superclass. The majority of these implementations are repetitive. Hence, the method is reimplemented and moved to the superclass (''quiz_question.rb''). In the subclasses, this method is inherited ('''MultipleChoiceRadio''' and ''TrueFalse''') with the exception of '''MultipleChoiceCheckbox''' where the method is extended. The implementation of '''isvalid''' is shown below

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice', foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def isvalid(choice_info)
@valid = 'valid'
return @valid = 'Please make sure all questions have text' if txt == ''
@correct_count = 0
choice_info.each_value do |value|
if (value[:txt] == '') || value[:txt].empty? || value[:txt].nil?
@valid = 'Please make sure every question has text for all options'
return @valid
end
@correct_count += 1 if value[:iscorrect]
end
@valid = 'Please select a correct answer for all questions' if @correct_count.zero?
@valid = 'Please select only one correct answer for all questions' if @correct_count > 1
@valid
end
end </nowiki>

<nowiki>
# multiple_choice_checkbox.rb
class MultipleChoiceCheckbox < QuizQuestion
... [other methods] ...

def isvalid(choice_info)
super
if @correct_count == 1
@valid = 'A multiple-choice checkbox question should have more than one correct answer.'
end
@valid = 'valid' if @correct_count > 1
@valid
end
end </nowiki>

=== edit ===
The edit method was originally not implemented within ''QuizQuestion'' and each of the child classes had their own implementation. These implementations had the exact same beginning HTML block:

<nowiki>
html = '<tr><td>'
html += '<textarea cols="100" name="question[' + id.to_s + '][txt]" '
html += 'id="question_' + id.to_s + '_txt">' + txt + '</textarea>'
html += '</td></tr>'

html += '<tr><td>'
html += 'Question Weight: '
html += '<input type="number" name="question_weights[' + id.to_s + '][txt]" '
html += 'id="question_wt_' + id.to_s + '_txt" '
html += 'value="' + weight.to_s + '" min="0" />'
html += '</td></tr>' </nowiki>

Given this, we were able to move this block up to the edit method within the parent ''QuizQuesiton'' class, and extend the method in the child classes. Each of the child classes differed in how their type of question was displayed, so each still has a custom implementation of the edit method.

An example from ''TrueFalse'':
<nowiki>
def edit
html = super

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="True" '
html += 'checked="checked" ' if self.quiz_question_choices[0].iscorrect
html += '/>True'
html += '</td></tr>'

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="False" '
html += 'checked="checked" ' if self.quiz_question_choices[1].iscorrect
html += '/>False'
html += '</td></tr>'

html.html_safe
end </nowiki>

We implemented tests for the edit method in both the parent ''QuizQuestion'' class to verify the preamble HTML is being returned as expected, and in each test class for the three subclasses to verify their specific implementations of edit are returning the HTML as expected.

=== complete ===

The complete method was initially not implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, I removed it from its subclass and moved it to the superclass in quiz_question.rb. It generates HTML code for completing a question. The quiz question's associated answer alternatives are displayed and can be selected using radio buttons.
The implementation of '''complete''' is shown below-

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice',
foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def complete
quiz_question_choices = self.quiz_question_choices
html = '<label for="' + id.to_s + '">' + txt + '</label><br>'
[0, 1, 2, 3].each do |i|
html += '<input name = ' + "\"#{id}\" "
html += 'id = ' + "\"#{id}" + '_' + "#{i + 1}\" "
html += 'value = ' + "\"#{quiz_question_choices[i].txt}\" "
html += 'type="radio"/>'
html += quiz_question_choices[i].txt.to_s
html += '</br>'
end
html
end
</nowiki>

The following test case has been added to test complete method-
<nowiki>
describe "#complete" do
before do
id = quiz_question.id
expected_html = "<label for=\"" + id.to_s + "\">Question Text</label><br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_1\" value = \"Choice 1\" type=\"radio\"/>Choice 1</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_2\" value = \"Choice 2\" type=\"radio\"/>Choice 2</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_3\" value = \"Choice 3\" type=\"radio\"/>Choice 3</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_4\" value = \"Choice 4\" type=\"radio\"/>Choice 4</br>"
expect(quiz_question.complete).to eq(expected_html)
end
it "returns the completed HTML for the quiz question" do
end
end </nowiki>

=== view_completed_question ===

The view_completed_question method was also not initially implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, we removed it from its subclass and moved it to the superclass in quiz_question.rb. The HTML code generated by this program is used to check the completed question and also to verify the response of the user. An indication is provided that indicates whether the user's response was right or wrong, and it is highlighted with help of check or delete icon which you can find here-[https://github.com/amjacob2/reimplementation-back-end/tree/main/app/assets/images assets/images].

The implementation of '''view_completed_question''' is shown below-
<nowiki>
def view_completed_question(user_answer)
quiz_question_choices = self.quiz_question_choices

html = ''
quiz_question_choices.each do |answer|
html += if answer.iscorrect
'<b>' + answer.txt + '</b> -- Correct <br>'
else
answer.txt + '<br>'
end
end

html += '<br>Your answer is: '
html += '<b>' + user_answer.first.comments.to_s + '</b>'
html += if user_answer.first.answer == 1
'<img src="/assets/Check-icon.png"/>'
else
'<img src="/assets/delete_icon.png"/>'
end
html += '</b>'
html += '<br><br><hr>'
html.html_safe
end </nowiki>

The following test case has been added to test view_completed_question method-
<nowiki>
describe '#view_completed_question' do
it 'returns the correct HTML for a completed question' do
quiz_question = QuizQuestion.new(txt: 'which is the latest Iphone?')
quiz_question_choice_1 = QuizQuestionChoice.new(txt: 'Iphone14', iscorrect: true)
quiz_question_choice_2 = QuizQuestionChoice.new(txt: 'Iphone13', iscorrect: false)
quiz_question_choice_3 = QuizQuestionChoice.new(txt: 'Iphone12', iscorrect: false)
quiz_question.quiz_question_choices << quiz_question_choice_1
quiz_question.quiz_question_choices << quiz_question_choice_2
quiz_question.quiz_question_choices << quiz_question_choice_3
user_answer = double('user_answer')
allow(user_answer).to receive_message_chain(:first, :comments).and_return('Iphone14')
allow(user_answer).to receive_message_chain(:first, :answer).and_return(1)
expected_html = '<b>Iphone14</b> -- Correct <br>Iphone13<br>Iphone12<br><br>Your answer is: <b>Iphone14</b><img src="/assets/Check-icon.png"/></b><br><br><hr>'
expect(quiz_question.view_completed_question(user_answer)).to eq(expected_html)
end
end </nowiki>

=== QuizQuestionChoice ===
The ''QuizQuestionChoice'' class represents a single choice in a true/false or multiple choice question. A QuizQuestion or QuizQuestion subclass has a 'has_many' relationship with QuizQuestionChoice. In the original implementation, every method that referenced the QuizQuestion's QuizQuestionChoices would do a retrieve -- this single line of code was duplicated multiple times through the four classes.

In order to improve this, we moved the fetching of a QuizQuestion's QuizQuestionChoices into a method that is run after an instance is initialized. From there the QuizQuestionChoices can be referenced as an instance variable instead of having the same fetch referenced over and over.

The referenced method from the new implementation of QuizQuestion:
<nowiki>
after_initialize :load_choices
def load_choices
@quiz_question_choices = QuizQuestionChoice.where(question_id: id)
end </nowiki>

== Test Plan ==

=== Overall Plan ===
The overall plan is to test all the methods that have been moved to the superclass, namely ''QuizQuestion''. These methods are:
* ''edit''
* ''view_question_text''
* ''complete''
* ''view_completed_question''
* ''isvalid''

Most tests will test the methods in ''QuizQuestion'' class as the subclasses mainly inherit these methods without extension. These test will be included in ''quiz_question_spec.rb'' (full path: /spec/requests/model/quiz_question_spec.rb). Methods that are extended by subclasses will also be tested in a separate spec file. For example, ''isvalid'' method is fully tested for ''QuizQuestion'' model in ''quiz_question_spec.rb''. Since ''TrueFalse'' and ''MultipleChoiceRadio'' inherit this method fully from the superclass without extension, no extra test is created to test the method for the two subclasses. However, ''MultipleChoiceCheckbox'' extended the ''isvalid'' method. As a result, extra tests are created to test ''isvalid'' for ''MultipleChoiceCheckbox''; these tests are then included in ''multiple_choice_checkbox_spec.rb''

=== edit ===
The goal in our automated testing of the edit function is to ensure that, given a QuizQuestion or QuizQuestion subclass object, the edit method of the class should display the HTML returned for the edit functionality as expected. In each of our Rspec test files, an object of the class under test (QuizQuestion or subclasses) is created to simulate what a similar database-driven object would appear like to our model classes.

* Within ''spec/requests/model/quiz_question_spec.rb'' the edit method is tested to ensure the default question prefix HTML is returned.
* Within ''spec/requests/model/true_false_spec.rb'', ''spec/requests/model/multiple_choice_radio_spec.rb'', and ''spec/requests/model/multiple_choice_checkbox_spec.rb'' the edit method is tested to ensure given an object filled out with QuizQuestionChoices, question text, question id, and weight the HTML is rendered appropriately.

These tests will fail if the underlying HTML returned from the model changes, which would be indicative of possible negative downstream effects in the application where the QuizQuestion subclasses are used.

=== isvalid ===
To test '''isvalid''' several tests were written to check for the behavior and returns of the method:
* Test the return message if the input contains text for the question prompt, text for all question choices, and only one of the choices is correct '''(expect "valid")'''
* Test the return message if the input is missing text for the question prompt '''(expect "Please make sure all questions have text")'''
* Test the return message if the input is missing text for at least one of the question choices '''(expect "Please make sure every question has text for all options")'''
* Test the return message if the input provides no correct answer '''(expect "Please select a correct answer for all questions")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "Please select only one correct answer for all questions")'''

'''isvalid''' is extended in '''MultipleChoiceCheckbox''' as the requirements for '''MultipleChoiceCheckbox''' to be valid are slightly different from those of '''QuizQuestion''', '''TrueFalse''', and '''MultipleChoiceRadio'''
* Test the return message if the input provides only 1 correct answer '''(expect "A multiple-choice checkbox question should have more than one correct answer.")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "valid")'''

<nowiki>
# quiz_question_spec.rb
require 'swagger_helper'

describe QuizQuestion do
let(:quiz_question) { QuizQuestion.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when the question and its choices have valid text' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('valid')
end
end
end
describe '#isvaid' do
let(:no_text_question) {QuizQuestion.new}
context 'when the question itself does not have txt' do
it 'returns "Please make sure all questions have text"' do
allow(no_text_question).to receive(:txt).and_return('')
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(no_text_question.isvalid(questions)).to eq('Please make sure all questions have text')
end
end
end
describe '#isvalid' do
context 'when a choice does not have text' do
it 'returns "Please make sure every question has text for all options"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: '', iscorrect: true },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please make sure every question has text for all options')
end
end
end
describe '#isvalid' do
context 'when no choices are correct' do
it 'returns "Please select a correct answer for all questions"' do
questions = { '1' => { txt: 'question text', iscorrect: false }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please select a correct answer for all questions')
end
end
end
describe '#isvalid' do
context 'when there are more than one correct choices' do
it 'returns "Please select only one correct answer for all questions"' do
questions = questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(quiz_question.isvalid(questions)).to eq('Please select only one correct answer for all questions')
end
end
end
end </nowiki>

Extended tests for '''isvalid''' in '''MultipleChoiceCheckbox'''
<nowiki>
# multiple_choice_checkbox+spec.rb
require 'swagger_helper'

describe MultipleChoiceCheckbox do
let(:multiple_choice_question) { MultipleChoiceCheckbox.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when there is only 1 correct answer' do
it 'returns "A multiple-choice checkbox question should have more than one correct answer."' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(multiple_choice_question.isvalid(questions)).to eq('A multiple-choice checkbox question should have more than one correct answer.')
end
end
end

describe '#isvalid' do
context 'when there is more than 1 correct answer' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(multiple_choice_question.isvalid(questions)).to eq('valid')
end
end
end
end </nowiki>

=== view_question_text ===
The test for '''view_question_text''' is fairly straight forward as once the question input passes '''isvalid''', we only need to make sure that view_question_text display the information in a predetermined format. The test for '''view_question_text''' is shown below
<nowiki>
describe '#view_question_text' do
it 'returns the text of the questions' do
weight = quiz_question.weight
expect(quiz_question.view_question_text).to eq('<b>Question Text</b><br />Question Type: MultipleChoiceRadio<br />Question Weight: ' +
weight.to_s + '<br /> - <b>Choice 1</b><br /> - Choice 2<br /> - Choice 3<br /> -
Choice 4<br /> <br />')
end
end </nowiki>

=== RSpec Test Setup ===
Note that for each test file we included a ''before'' block that setup a QuizQuestion subclass object of the given type being tested, assigned it the required parameters, and assigned ''QuizQuestionChoices'' that matched the type of question. Doing this allowed us to simulate in the test how the object would be used within the greater context of the application.

Example test setup from ''quiz_question_spec.rb'':
<nowiki>
let(:quiz_question) { QuizQuestion.new }
let(:quiz_question_choice1) { QuizQuestionChoice.new }
let(:quiz_question_choice2) { QuizQuestionChoice.new }
let(:quiz_question_choice3) { QuizQuestionChoice.new }
let(:quiz_question_choice4) { QuizQuestionChoice.new }
before(:each) do
quiz_question.quiz_question_choices = [quiz_question_choice1, quiz_question_choice2, quiz_question_choice3, quiz_question_choice4]
quiz_question.txt = 'Question Text'
allow(quiz_question).to receive(:type).and_return('MultipleChoiceRadio')
allow(quiz_question).to receive(:id).and_return(99)
allow(quiz_question).to receive(:weight).and_return(5)
allow(quiz_question_choice1).to receive(:txt).and_return('Choice 1')
allow(quiz_question_choice1).to receive(:question_id).and_return(99)
allow(quiz_question_choice1).to receive(:iscorrect?).and_return(true)
allow(quiz_question_choice2).to receive(:txt).and_return('Choice 2')
allow(quiz_question_choice2).to receive(:question_id).and_return(99)
allow(quiz_question_choice2).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice3).to receive(:txt).and_return('Choice 3')
allow(quiz_question_choice3).to receive(:question_id).and_return(99)
allow(quiz_question_choice3).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice4).to receive(:txt).and_return('Choice 4')
allow(quiz_question_choice4).to receive(:question_id).and_return(99)
allow(quiz_question_choice4).to receive(:iscorrect?).and_return(false)
end </nowiki>

== Methods in Files Modified/Created ==
'''isvalid''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb'' and ''true_false.rb''
* Extended in ''multiple_choice_checkbox.rb''
* Modified ''quiz_question_spec.rb'' and ''multiple_choice_checkbox_spec.rb'' to include tests for the method.

'''view_question_text''' method
* left as is in ''quiz_question.rb''

'''complete''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for complete method in ''quiz_question_spec.rb''.

'''view_completed_question''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for view_completed_question method in ''quiz_question_spec.rb''.

'''edit''' method
* Implemented in ''quiz_question.rb''
* Extended in ''multiple_choice_radio.rb'', ''multiple_choice_checkbox.rb'', and ''true_false.rb''
* Tests cases added in ''quiz_question_spec.rb'', ''multiple_choice_checkbox_spec.rb'', and ''true_false_spec.rb''

== Additional Files Created ==
As part of our reimplementation, we needed to pull in some existing model classes from Expertiza in order to allow us to fully test our reimplemented models. These files were copied from the latest Expteriza main branch as of Program 3 assignment and were not modified. These files include:
* app/models/question.rb
* app/models/questionnaire.rb
* app/models/quiz_quesiton_choice.rb

Additionally we created migration from these models (and our reimplemented classes):
* db/migrate/20230311214056_create_quiz_questions.rb
* db/migrate/20230314152206_create_questionnaires.rb
* db/migrate/20230314152945_create_questions.rb
* db/migrate/20230314153211_add_key_to_questions.rb
* db/migrate/20230315172116_create_quiz_question_choices.rb

== Executing Tests ==
* To run the test suite written for our project, use the following command:
<nowiki> bundle exec rspec spec/requests/model </nowiki>
* To run individual test files (separated by model that is being tested), use the following command:
<nowiki> bundle exec rspec spec/requests/model/test_file_name.rb </nowiki>

==Useful Links==
* [https://github.com/amjacob2/reimplementation-back-end.git Our Github Forked Repo]
* [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view Demo and Test Suite Video]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Future Work API demo]
* [https://github.com/amjacob2/reimplementation-back-end/pull/10 Future Work API sample]
* [https://github.com/expertiza/reimplementation-back-end/pull/6 Pull request]

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-28T01:54:48Z

Jdjohns4: added edit function details to test plan

== Background ==

=== Current State ===
Currently, in '''[https://github.com/expertiza/expertiza Expertiza]''' there is a model class called '''QuizQuestion''' which serves as a superclass of classes '''MultipleChoiceCheckbox''', '''MultipleChoiceRadio''', and '''TrueFalse'''.

There are four methods in the '''QuizQuestion''' superclass which return HTML strings, depending on the question type:
* ''edit'' -- What to display if an instructor (etc.) is creating or editing a questionnaire (questionnaires_controller.rb)
* ''view_question_text'' -- What to display if an instructor (etc.) is viewing a questionnaire (questionnaires_controller.rb)
* ''view_completed_question'' -- What to display if a student is viewing a filled-out questionnaire (response_controller.rb)
* ''complete'' -- What to display if a student is filling out a questionnaire (response_controller.rb)

Additionally, the inheriting classes contain a method ''isvalid'' that is not in '''QuizQuestion'''.

Included below is the UML diagram of the design of the QuizQuestion and its child classes in the current state

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

=== Our Implementation Project ===
For this project, we are tasked with '''redesigning the above UML diagram''' and '''reimplementing the five methods''' (mentioned in the previous section) in the superclass (''QuizQuestion''). The reimplementation of the methods in the superclass will provide inheritances to the subclasses (''MultipleChoiceCheckbox'', ''MultipleChoiceRadio'', and ''TrueFalse''), and will use overriding/overloading to avoid type-checking.

Included below is the redesign of the UML diagram of the relationship between ''QuizQuestion'' and its child classes. As shown in the diagram, all methods are moved to the parent class. Child classes either inherit purely from the parent class' methods or extend it through overriding/overloading.

'''Note''' that the methods reimplemented in the parent class (''QuizQuestion'') still render HTML components to provide to the front-end (through the ''response_controller.rb'' and ''questionnaires_controller.rb'').

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

=== Overview and Test Suite Video ===
A video summarizing our work and display our successful run of RSpec test cases can be viewed [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view here]

=== Future Direction ===
In the future, as the '''Expertiza''' app is being migrated to the combination of Ruby API and React front-end (instead of legacy Rails), these methods will be modified to use Ruby API, and to handle and return React objects for the front-end.

As part of our work on this project, we implemented a sample API controller that is able to return QuizQuestion child classes in JSON form. We believe this would be an initial step in converting the QuizQuestion models for use with a Ruby back-end / React front-end approach.

As this was not formally part of our project requirements, we have left our work in a draft pull request on our [https://github.com/amjacob2/reimplementation-back-end/pull/10 repository]

The following links are to our demonstration API instance on the NCSU VCL:
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Multiple Choice Checkbox]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceRadio Multiple Choice Radio]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=TrueFalse True False]

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Reimplementation Details==

=== isvalid ===
'''isvalid''' method is implemented in all subclasses but not the superclass. The majority of these implementations are repetitive. Hence, the method is reimplemented and moved to the superclass (''quiz_question.rb''). In the subclasses, this method is inherited ('''MultipleChoiceRadio''' and ''TrueFalse''') with the exception of '''MultipleChoiceCheckbox''' where the method is extended. The implementation of '''isvalid''' is shown below

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice', foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def isvalid(choice_info)
@valid = 'valid'
return @valid = 'Please make sure all questions have text' if txt == ''
@correct_count = 0
choice_info.each_value do |value|
if (value[:txt] == '') || value[:txt].empty? || value[:txt].nil?
@valid = 'Please make sure every question has text for all options'
return @valid
end
@correct_count += 1 if value[:iscorrect]
end
@valid = 'Please select a correct answer for all questions' if @correct_count.zero?
@valid = 'Please select only one correct answer for all questions' if @correct_count > 1
@valid
end
end </nowiki>

<nowiki>
# multiple_choice_checkbox.rb
class MultipleChoiceCheckbox < QuizQuestion
... [other methods] ...

def isvalid(choice_info)
super
if @correct_count == 1
@valid = 'A multiple-choice checkbox question should have more than one correct answer.'
end
@valid = 'valid' if @correct_count > 1
@valid
end
end </nowiki>

=== edit ===
The edit method was originally not implemented within ''QuizQuestion'' and each of the child classes had their own implementation. These implementations had the exact same beginning HTML block:

<nowiki>
html = '<tr><td>'
html += '<textarea cols="100" name="question[' + id.to_s + '][txt]" '
html += 'id="question_' + id.to_s + '_txt">' + txt + '</textarea>'
html += '</td></tr>'

html += '<tr><td>'
html += 'Question Weight: '
html += '<input type="number" name="question_weights[' + id.to_s + '][txt]" '
html += 'id="question_wt_' + id.to_s + '_txt" '
html += 'value="' + weight.to_s + '" min="0" />'
html += '</td></tr>' </nowiki>

Given this, we were able to move this block up to the edit method within the parent ''QuizQuesiton'' class, and extend the method in the child classes. Each of the child classes differed in how their type of question was displayed, so each still has a custom implementation of the edit method.

An example from ''TrueFalse'':
<nowiki>
def edit
html = super

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="True" '
html += 'checked="checked" ' if self.quiz_question_choices[0].iscorrect
html += '/>True'
html += '</td></tr>'

html += '<tr><td>'
html += '<input type="radio" name="quiz_question_choices[' + id.to_s + '][TrueFalse][1][iscorrect]" '
html += 'id="quiz_question_choices_' + id.to_s + '_TrueFalse_1_iscorrect_True" value="False" '
html += 'checked="checked" ' if self.quiz_question_choices[1].iscorrect
html += '/>False'
html += '</td></tr>'

html.html_safe
end </nowiki>

We implemented tests for the edit method in both the parent ''QuizQuestion'' class to verify the preamble HTML is being returned as expected, and in each test class for the three subclasses to verify their specific implementations of edit are returning the HTML as expected.

=== complete ===

The complete method was initially not implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, I removed it from its subclass and moved it to the superclass in quiz_question.rb. It generates HTML code for completing a question. The quiz question's associated answer alternatives are displayed and can be selected using radio buttons.
The implementation of '''complete''' is shown below-

<nowiki>
# quiz_question.rb
class QuizQuestion < Question
has_many :quiz_question_choices, class_name: 'QuizQuestionChoice',
foreign_key: 'question_id', inverse_of: false, dependent: :nullify

... [other methods] ...
def complete
quiz_question_choices = self.quiz_question_choices
html = '<label for="' + id.to_s + '">' + txt + '</label><br>'
[0, 1, 2, 3].each do |i|
html += '<input name = ' + "\"#{id}\" "
html += 'id = ' + "\"#{id}" + '_' + "#{i + 1}\" "
html += 'value = ' + "\"#{quiz_question_choices[i].txt}\" "
html += 'type="radio"/>'
html += quiz_question_choices[i].txt.to_s
html += '</br>'
end
html
end
</nowiki>

The following test case has been added to test complete method-
<nowiki>
describe "#complete" do
before do
id = quiz_question.id
expected_html = "<label for=\"" + id.to_s + "\">Question Text</label><br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_1\" value = \"Choice 1\" type=\"radio\"/>Choice 1</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_2\" value = \"Choice 2\" type=\"radio\"/>Choice 2</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_3\" value = \"Choice 3\" type=\"radio\"/>Choice 3</br><input name = \"" + id.to_s + "\" id = \"" + id.to_s + "_4\" value = \"Choice 4\" type=\"radio\"/>Choice 4</br>"
expect(quiz_question.complete).to eq(expected_html)
end
it "returns the completed HTML for the quiz question" do
end
end </nowiki>

=== view_completed_question ===

The view_completed_question method was also not initially implemented within QuizQuestion and each of the child classes had its own implementation. To reimplement this method, we removed it from its subclass and moved it to the superclass in quiz_question.rb. The HTML code generated by this program is used to check the completed question and also to verify the response of the user. An indication is provided that indicates whether the user's response was right or wrong, and it is highlighted with help of check or delete icon which you can find here-[https://github.com/amjacob2/reimplementation-back-end/tree/main/app/assets/images assets/images].

The implementation of '''view_completed_question''' is shown below-
<nowiki>
def view_completed_question(user_answer)
quiz_question_choices = self.quiz_question_choices

html = ''
quiz_question_choices.each do |answer|
html += if answer.iscorrect
'<b>' + answer.txt + '</b> -- Correct <br>'
else
answer.txt + '<br>'
end
end

html += '<br>Your answer is: '
html += '<b>' + user_answer.first.comments.to_s + '</b>'
html += if user_answer.first.answer == 1
'<img src="/assets/Check-icon.png"/>'
else
'<img src="/assets/delete_icon.png"/>'
end
html += '</b>'
html += '<br><br><hr>'
html.html_safe
end </nowiki>

The following test case has been added to test view_completed_question method-
<nowiki>
describe '#view_completed_question' do
it 'returns the correct HTML for a completed question' do
quiz_question = QuizQuestion.new(txt: 'which is the latest Iphone?')
quiz_question_choice_1 = QuizQuestionChoice.new(txt: 'Iphone14', iscorrect: true)
quiz_question_choice_2 = QuizQuestionChoice.new(txt: 'Iphone13', iscorrect: false)
quiz_question_choice_3 = QuizQuestionChoice.new(txt: 'Iphone12', iscorrect: false)
quiz_question.quiz_question_choices << quiz_question_choice_1
quiz_question.quiz_question_choices << quiz_question_choice_2
quiz_question.quiz_question_choices << quiz_question_choice_3
user_answer = double('user_answer')
allow(user_answer).to receive_message_chain(:first, :comments).and_return('Iphone14')
allow(user_answer).to receive_message_chain(:first, :answer).and_return(1)
expected_html = '<b>Iphone14</b> -- Correct <br>Iphone13<br>Iphone12<br><br>Your answer is: <b>Iphone14</b><img src="/assets/Check-icon.png"/></b><br><br><hr>'
expect(quiz_question.view_completed_question(user_answer)).to eq(expected_html)
end
end </nowiki>

=== QuizQuestionChoice ===
The ''QuizQuestionChoice'' class represents a single choice in a true/false or multiple choice question. A QuizQuestion or QuizQuestion subclass has a 'has_many' relationship with QuizQuestionChoice. In the original implementation, every method that referenced the QuizQuestion's QuizQuestionChoices would do a retrieve -- this single line of code was duplicated multiple times through the four classes.

In order to improve this, we moved the fetching of a QuizQuestion's QuizQuestionChoices into a method that is run after an instance is initialized. From there the QuizQuestionChoices can be referenced as an instance variable instead of having the same fetch referenced over and over.

The referenced method from the new implementation of QuizQuestion:
<nowiki>
after_initialize :load_choices
def load_choices
@quiz_question_choices = QuizQuestionChoice.where(question_id: id)
end </nowiki>

== Test Plan ==

=== Overall Plan ===
The overall plan is to test all the methods that have been moved to the superclass, namely ''QuizQuestion''. These methods are:
* ''edit''
* ''view_question_text''
* ''complete''
* ''view_completed_question''
* ''isvalid''

Most tests will test the methods in ''QuizQuestion'' class as the subclasses mainly inherit these methods without extension. These test will be included in ''quiz_question_spec.rb'' (full path: /spec/requests/model/quiz_question_spec.rb). Methods that are extended by subclasses will also be tested in a separate spec file. For example, ''isvalid'' method is fully tested for ''QuizQuestion'' model in ''quiz_question_spec.rb''. Since ''TrueFalse'' and ''MultipleChoiceRadio'' inherit this method fully from the superclass without extension, no extra test is created to test the method for the two subclasses. However, ''MultipleChoiceCheckbox'' extended the ''isvalid'' method. As a result, extra tests are created to test ''isvalid'' for ''MultipleChoiceCheckbox''; these tests are then included in ''multiple_choice_checkbox_spec.rb''

=== edit ===
The goal in our automated testing of the edit function is to ensure that, given a QuizQuestion or QuizQuestion subclass object, the edit method of the class should display the HTML returned for the edit functionality as expected. In each of our Rspec test files, an object of the class under test (QuizQuestion or subclasses) is created to simulate what a similar database-driven object would appear like to our model classes.

* Within ''spec/requests/model/quiz_question_spec.rb'' the edit method is tested to ensure the default question prefix HTML is returned.
* Within ''spec/requests/model/true_false_spec.rb'', ''spec/requests/model/multiple_choice_radio_spec.rb'', and ''spec/requests/model/multiple_choice_checkbox_spec.rb'' the edit method is tested to ensure given an object filled out with QuizQuestionChoices, question text, question id, and weight the HTML is rendered appropriately.

These tests will fail if the underlying HTML returned from the model changes, which would be indicative of possible negative downstream effects in the application where the QuizQuestion subclasses are used.

=== isvalid ===
To test '''isvalid''' several tests were written to check for the behavior and returns of the method:
* Test the return message if the input contains text for the question prompt, text for all question choices, and only one of the choices is correct '''(expect "valid")'''
* Test the return message if the input is missing text for the question prompt '''(expect "Please make sure all questions have text")'''
* Test the return message if the input is missing text for at least one of the question choices '''(expect "Please make sure every question has text for all options")'''
* Test the return message if the input provides no correct answer '''(expect "Please select a correct answer for all questions")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "Please select only one correct answer for all questions")'''

'''isvalid''' is extended in '''MultipleChoiceCheckbox''' as the requirements for '''MultipleChoiceCheckbox''' to be valid are slightly different from those of '''QuizQuestion''', '''TrueFalse''', and '''MultipleChoiceRadio'''
* Test the return message if the input provides only 1 correct answer '''(expect "A multiple-choice checkbox question should have more than one correct answer.")'''
* Test the return message if the input provides more than 1 correct answer '''(expect "valid")'''

<nowiki>
# quiz_question_spec.rb
require 'swagger_helper'

describe QuizQuestion do
let(:quiz_question) { QuizQuestion.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when the question and its choices have valid text' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('valid')
end
end
end
describe '#isvaid' do
let(:no_text_question) {QuizQuestion.new}
context 'when the question itself does not have txt' do
it 'returns "Please make sure all questions have text"' do
allow(no_text_question).to receive(:txt).and_return('')
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(no_text_question.isvalid(questions)).to eq('Please make sure all questions have text')
end
end
end
describe '#isvalid' do
context 'when a choice does not have text' do
it 'returns "Please make sure every question has text for all options"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: '', iscorrect: true },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please make sure every question has text for all options')
end
end
end
describe '#isvalid' do
context 'when no choices are correct' do
it 'returns "Please select a correct answer for all questions"' do
questions = { '1' => { txt: 'question text', iscorrect: false }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(quiz_question.isvalid(questions)).to eq('Please select a correct answer for all questions')
end
end
end
describe '#isvalid' do
context 'when there are more than one correct choices' do
it 'returns "Please select only one correct answer for all questions"' do
questions = questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(quiz_question.isvalid(questions)).to eq('Please select only one correct answer for all questions')
end
end
end
end </nowiki>

Extended tests for '''isvalid''' in '''MultipleChoiceCheckbox'''
<nowiki>
# multiple_choice_checkbox+spec.rb
require 'swagger_helper'

describe MultipleChoiceCheckbox do
let(:multiple_choice_question) { MultipleChoiceCheckbox.new }
... [setup] ...
end

... [other tests] ...

describe '#isvalid' do
context 'when there is only 1 correct answer' do
it 'returns "A multiple-choice checkbox question should have more than one correct answer."' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: false } }
expect(multiple_choice_question.isvalid(questions)).to eq('A multiple-choice checkbox question should have more than one correct answer.')
end
end
end

describe '#isvalid' do
context 'when there is more than 1 correct answer' do
it 'returns "valid"' do
questions = { '1' => { txt: 'question text', iscorrect: true }, '2' => { txt: 'question text', iscorrect: false },
'3' => { txt: 'question text', iscorrect: false }, '4' => { txt: 'question text', iscorrect: true } }
expect(multiple_choice_question.isvalid(questions)).to eq('valid')
end
end
end
end </nowiki>

=== view_question_text ===
The test for '''view_question_text''' is fairly straight forward as once the question input passes '''isvalid''', we only need to make sure that view_question_text display the information in a predetermined format. The test for '''view_question_text''' is shown below
<nowiki>
describe '#view_question_text' do
it 'returns the text of the questions' do
weight = quiz_question.weight
expect(quiz_question.view_question_text).to eq('<b>Question Text</b><br />Question Type: MultipleChoiceRadio<br />Question Weight: ' +
weight.to_s + '<br /> - <b>Choice 1</b><br /> - Choice 2<br /> - Choice 3<br /> -
Choice 4<br /> <br />')
end
end </nowiki>

=== RSpec Test Setup ===
Note that for each test file we included a ''before'' block that setup a QuizQuestion subclass object of the given type being tested, assigned it the required parameters, and assigned ''QuizQuestionChoices'' that matched the type of question. Doing this allowed us to simulate in the test how the object would be used within the greater context of the application.

Example test setup from ''quiz_question_spec.rb'':
<nowiki>
let(:quiz_question) { QuizQuestion.new }
let(:quiz_question_choice1) { QuizQuestionChoice.new }
let(:quiz_question_choice2) { QuizQuestionChoice.new }
let(:quiz_question_choice3) { QuizQuestionChoice.new }
let(:quiz_question_choice4) { QuizQuestionChoice.new }
before(:each) do
quiz_question.quiz_question_choices = [quiz_question_choice1, quiz_question_choice2, quiz_question_choice3, quiz_question_choice4]
quiz_question.txt = 'Question Text'
allow(quiz_question).to receive(:type).and_return('MultipleChoiceRadio')
allow(quiz_question).to receive(:id).and_return(99)
allow(quiz_question).to receive(:weight).and_return(5)
allow(quiz_question_choice1).to receive(:txt).and_return('Choice 1')
allow(quiz_question_choice1).to receive(:question_id).and_return(99)
allow(quiz_question_choice1).to receive(:iscorrect?).and_return(true)
allow(quiz_question_choice2).to receive(:txt).and_return('Choice 2')
allow(quiz_question_choice2).to receive(:question_id).and_return(99)
allow(quiz_question_choice2).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice3).to receive(:txt).and_return('Choice 3')
allow(quiz_question_choice3).to receive(:question_id).and_return(99)
allow(quiz_question_choice3).to receive(:iscorrect?).and_return(false)
allow(quiz_question_choice4).to receive(:txt).and_return('Choice 4')
allow(quiz_question_choice4).to receive(:question_id).and_return(99)
allow(quiz_question_choice4).to receive(:iscorrect?).and_return(false)
end </nowiki>

== Methods in Files Modified/Created ==
'''isvalid''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb'' and ''true_false.rb''
* Extended in ''multiple_choice_checkbox.rb''
* Modified ''quiz_question_spec.rb'' and ''multiple_choice_checkbox_spec.rb'' to include tests for the method.

'''view_question_text''' method
* left as is in ''quiz_question.rb''

'''complete''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for complete method in ''quiz_question_spec.rb''.

'''view_completed_question''' method
* Reimplemented the method in ''quiz_question.rb''
* Removed from ''multiple_choice_radio.rb''
* Removed from ''multiple_choice_checkbox.rb''
* Added test case for view_completed_question method in ''quiz_question_spec.rb''.

'''edit''' method
* Implemented in ''quiz_question.rb''
* Extended in ''multiple_choice_radio.rb'', ''multiple_choice_checkbox.rb'', and ''true_false.rb''
* Tests cases added in ''quiz_question_spec.rb'', ''multiple_choice_checkbox_spec.rb'', and ''true_false_spec.rb''

== Additional Files Created ==
As part of our reimplementation, we needed to pull in some existing model classes from Expertiza in order to allow us to fully test our reimplemented models. These files were copied from the latest Expteriza main branch as of Program 3 assignment and were not modified. These files include:
* app/models/question.rb
* app/models/questionnaire.rb
* app/models/quiz_quesiton_choice.rb

Additionally we created migration from these models (and our reimplemented classes):
* db/migrate/20230311214056_create_quiz_questions.rb
* db/migrate/20230314152206_create_questionnaires.rb
* db/migrate/20230314152945_create_questions.rb
* db/migrate/20230314153211_add_key_to_questions.rb
* db/migrate/20230315172116_create_quiz_question_choices.rb

== Executing Tests ==
* To run the test suite written for our project, use the following command:
<nowiki> bundle exec rspec spec/requests/model </nowiki>
* To run individual test files (separated by model that is being tested), use the following command:
<nowiki> bundle exec rspec spec/requests/model/test_file_name.rb </nowiki>

==Useful Links==
* [https://github.com/amjacob2/reimplementation-back-end.git Our Github Forked Repo]
* [https://drive.google.com/file/d/1WWgir8u_10FblUVBFtBPd7RRgiJVqbOA/view Demo and Test Suite Video]
* [http://152.7.178.122:3000/api/v1/quiz_questions/show?type=MultipleChoiceCheckbox Future Work API demo]
* [https://github.com/amjacob2/reimplementation-back-end/pull/10 Future Work API sample]
* [https://github.com/expertiza/reimplementation-back-end/pull/6 Pull request]

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:51:58Z

Jdjohns4: /* Detailed Description of Changes */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:40:24Z

Jdjohns4: /* Useful Links */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:38:23Z

Jdjohns4: /* Methods in Files Modified/Created */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:28:58Z

Jdjohns4: /* edit */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:27:43Z

Jdjohns4: /* Detailed Description of Changes */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:18:31Z

Jdjohns4: /* Background */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:17:43Z

Jdjohns4: /* Our Implementation Project */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:16:19Z

Jdjohns4: /* Files Modified/Created */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-22T00:14:08Z

Jdjohns4: /* Future Direction */

CSC/ECE 517 Spring 2023 - E2311. Reimplement QuizQuestion and its child classes

2023-03-19T02:45:01Z

Jdjohns4: created outline of documentation

== Background ==

=== Current State ===
Currently, in Expertiza there is a model class called '''QuizQuestion''' which serves as a superclass of classes '''MultipleChoiceCheckbox''', '''MultipleChoiceRadio''', and '''TrueFalse'''.

There are four methods in the '''QuizQuestion''' superclass which return HTML strings, depending on the question type:
* ''edit'' -- What to display if an instructor (etc.) is creating or editing a questionnaire (questionnaires_controller.rb)
* ''view_question_text'' -- What to display if an instructor (etc.) is viewing a questionnaire (questionnaires_controller.rb)
* ''view_completed_question'' -- What to display if a student is viewing a filled-out questionnaire (response_controller.rb)
* ''complete'' -- What to display if a student is filling out a questionnaire (response_controller.rb)

Additionally, the inheriting classes contain a method ''isvalid'' that is not in '''QuizQuestion'''.

=== Our Implementation Project ===
[insert details about what we've been tasked in this project]

=== Future Direction ===
[insert notes about ruby api + react, vs legacy rails]

== Team ==
* Aileen Jacob (amjacob2)
* Anh Nguyen (anguyen9)
* Joe Johnson (jdjohns4)
* '''Mentor''' Jialin Cui (jcui9)

== Detailed Description of Changes ==

== Files Modified/Created ==

== Executing Tests ==