DeveloperGuide.adoc

Test Bank - Developer Guide

By: Group F10-3      Since: Aug 2019      Licence: MIT

• 1. Setting up
• 2. Design
  • 2.1. Architecture
  • 2.2. UI component
  • 2.3. Logic component
  • 2.4. Model component
  • 2.5. Storage component
  • 2.6. Common classes
• 3. Implementation
  • 3.1. [Proposed] Add questions feature
  • 3.2. [Proposed] Data Encryption
  • 3.3. Logging
  • 3.4. Configuration
• 4. Documentation
• 5. Testing
• 6. Dev Ops
• Appendix A: Product Scope
• Appendix B: User Stories
• Appendix C: Use Cases
• Appendix D: Non Functional Requirements
• Appendix E: Glossary
• Appendix F: Product Survey
• Appendix G: Instructions for Manual Testing
  • G.1. Launch and Shutdown
  • G.2. Deleting a person
  • G.3. Saving data

1. Setting up

Refer to the guide here.

2. Design

2.1. Architecture

Figure 1. Architecture Diagram

The Architecture Diagram given above explains the high-level design of the App. Given below is a quick overview of each component.

💡	The .puml files used to create diagrams in this document can be found in the diagrams folder. Refer to the Using PlantUML guide to learn how to create and edit diagrams.

Main has two classes called Main and MainApp. It is responsible for,

• At app launch: Initializes the components in the correct sequence, and connects them up with each other.

• At shut down: Shuts down the components and invokes cleanup method where necessary.

Commons represents a collection of classes used by multiple other components. The following class plays an important role at the architecture level:

• LogsCenter : Used by many classes to write log messages to the App’s log file.

The rest of the App consists of four components.

• UI: The UI of the App.

• Logic: The command executor.

• Model: Holds the data of the App in-memory.

• Storage: Reads data from, and writes data to, the hard disk.

Each of the four components

• Defines its API in an interface with the same name as the Component.

• Exposes its functionality using a {Component Name}Manager class.

For example, the Logic component (see the class diagram given below) defines it’s API in the Logic.java interface and exposes its functionality using the LogicManager.java class.

Figure 2. Class Diagram of the Logic Component

How the architecture components interact with each other

The Sequence Diagram below shows how the components interact with each other for the scenario where the user issues the command delete 1.

Figure 3. Component interactions for delete 1 command

The sections below give more details of each component.

2.2. UI component

Figure 4. Structure of the UI Component

API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel, StatusBarFooter etc. All these, including the MainWindow, inherit from the abstract UiPart class.

The UI component uses JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

• Executes user commands using the Logic component.

• Listens for changes to Model data so that the UI can be updated with the modified data.

2.3. Logic component

Figure 5. Structure of the Logic Component

API : Logic.java

1. Logic uses the TestBankParser class to parse the user command.

2. This results in a Command object which is executed by the LogicManager.

3. The command execution can affect the Model (e.g. adding a question).

4. The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui.

5. In addition, the CommandResult object can also instruct the Ui to perform certain actions, such as displaying help to the user.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delete 1") API call.

Figure 6. Interactions Inside the Logic Component for the delete 1 Command

ℹ️	The lifeline for DeleteCommandParser should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.

2.4. Model component

Figure 7. Structure of the Model Component

API : Model.java

The Model,

• stores a Question Bank object that represents the Question Bank.

• stores the Test Bank data.

• exposes an unmodifiable ObservableList<Question> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.

• does not depend on any of the other three components.

ℹ️	As a more OOP model, we can store a Tag list in Test Bank, which Question can reference. This would allow Test Bank to only require one Tag object per unique Tag, instead of each Question needing their own Tag object. An example of how such a model may look like is given below.

2.5. Storage component

Figure 8. Structure of the Storage Component

API : Storage.java

The Storage component,

• can save Question Bank objects in json format and read it back.

• can save the Test Bank data in json format and read it back.

2.6. Common classes

Classes used by multiple components are in the seedu.addressbook.commons package.

3. Implementation

This section describes some noteworthy details on how certain features are implemented.

3.1. [Proposed] Add questions feature

3.1.1. Proposed Implementation

The add questions mechanism is facilitated by AddCommand. It extends Command that will read a user command and execute the command result. Additionally, it implements the following operations:

• AddCommand#addMcq() — Adds a mcq question to the test bank.

• AddCommand#addShortAns() — Adds a short answer question to the test bank.

These operations are exposed in the Model interface as Model#addMcqCommand() and Model#addShortAnsCommand() respectively.

Given below is an example usage scenario and how the add questions mechanism behaves at each step.

Step 1. The user types add mcq q/"string of question" x/option1 x/option2 y/option3 x/option4 cat/[UML] diff/[easy], this command adds a easy difficulty mcq question about UML with 4 options and option3 being the correct answer.

Step 2. The command is being parse into the parser and the AddCommand object of type Command will be created.

Step 3. The AddCommand object will call its addMcq() method, this method will read the command and store the question with the answers into the test bank accordingly.

ℹ️	If a command fails its execution, it will not save the question into the test bank. It will however throw an invalid command exception.

The following sequence diagram shows how the add question operation works:

ℹ️	The lifeline for UndoCommand should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.

3.1.2. Design Considerations

Aspect: How add executes

• Alternative 1 (current choice): Read and parse the command to execute it

  • Pros: Easy to implement.

  • Cons: May have performance issues in terms of memory usage.

Aspect: Format of the add command

• Alternative 1 (current choice): Use a single line containing all the information of the question.

  • Pros: Faster for user to add a question.

  • Cons: Hard for user to memorize the long sequence which may cause invalid command input.

• Alternative 2: Use multiple steps to guide user on adding the question.

  • Pros: User do not have to memorize the correct format and less chance for an invalid command input.

  • Cons: Slow to add questions, requiring multiple steps to fully complete a question.

3.2. [Proposed] Data Encryption

{Explain here how the data encryption feature will be implemented}

3.3. Logging

We are using java.util.logging package for logging. The LogsCenter class is used to manage the logging levels and logging destinations.

• The logging level can be controlled using the logLevel setting in the configuration file (See Section 3.4, “Configuration”)

• The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level

• Currently log messages are output through: Console and to a .log file.

Logging Levels

• SEVERE : Critical problem detected which may possibly cause the termination of the application

• WARNING : Can continue, but with caution

• INFO : Information showing the noteworthy actions by the App

• FINE : Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size

3.4. Configuration

Certain properties of the application can be controlled (e.g user prefs file location, logging level) through the configuration file (default: config.json).

4. Documentation

Refer to the guide here.

5. Testing

Refer to the guide here.

6. Dev Ops

Refer to the guide here.

Appendix A: Product Scope

Target user profile:

• is a CS2103/T student

• prefer to use an app to help them to revise

• can type fast

• prefers typing over mouse input

• is reasonably comfortable using CLI apps

Value proposition: helps student to ace CS2103/T

Appendix B: User Stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Priority	As a …​	I want to …​	So that I can…​
* * *	lazy CS2103 student	refer to the revision tool solely for my consolidated module revision	do not have to refer to Luminus
* * *	CS2103 student	have a personalised application to store all my questions and answers in one place	refer to it conveniently for revision.
* * *	CS2103 student	have a revision tool to test my coding skills and concepts through writing short codes	test myself on coding proficiency too.
* * *	CS2103 student	keep track and see how much progress I have made in completing the questions	gauge my level of progress in completing the syllabus.
* * *	vim-using CS2103/T student	use the keyboard-based commands	further increase my efficiency
* * *	busy CS2103/T	use quick revision tools	learn using spaced-retrieval
* * *	busy CS2103 student	mark certain concepts as easy	will not have to spend as much time studying the easy concepts.
* * *	CS2103 student with a lot of things on my mind	mark certain questions that I am unsure of	refer back to the question when I am free.
* * *	CS2103 student	import questions from my peers	study on my own.
* * *	conscientious CS2103 student	export the questions I am unsure of	raise them up during tutorials.
* * *	indecisive student	be recommended questions instead of me having to plan my own study plan	go directly to studying
* *	competitive CS2103 student	at least know where I stand among my cohort	look at who is the next person I can beat.
* *	gamer CS2103/T student	accomplish tasks that give me a sense of achievement, preferably through in application rewards	I feel good.
* *	A+ CS2103 student	review and give suggestions to improve the application	benefit more CS2103 students.
* *	CS2103 student	port this application over to my other modules	revise for my other modules using this application as well.
* *	unorganized CS2103 student	get reminders about my quiz deadlines	complete my quizzes on time
* *	organized CS2103 student	schedule reminders to remind me when I should use the application to do revision	will not forget to do revision.
* *	user of the application	get an estimate of my final grade for CS2103	know what to expect on result release day.
* *	CS2103 peer tutor	use this as a form of teaching tool	teach better
* *	CAP 5.0 CS2103 student	show off my IQ by perfecting my test scores	motivate other students.
* *	CS2103 student	view the questions/topics that most students answered wrongly	revise for those topics.
* *	visual oriented student	the app to have different colours as compared to the regular black and white	learn better
* *	non-motivated CS2103 student	use the application to remind me to study	I will study
* *	student that wants shortcuts	type a partial command and have it be auto-completed	I can save time.
* *	CS2103 student new to Git	have a help function which lists all the commonly used Git commands	become more proficient with Git.
* *	master software engineer taking CS2103	be able to access the source code	to make the application better and customise it for myself.
* *	CS2103 student	get recommended a list of questions that I frequently get wrong	learn from my mistakes
*	lonely CS2103 student	have someone to talk to, even if it’s a computer	I won’t feel lonely
*	CS2103 student who keeps having stomach ache	the application to tell me where the nearest toilet is	go and shit

Appendix C: Use Cases

(For all use cases below, the System is the AddressBook and the Actor is the user, unless specified otherwise)

Use case: Delete person

MSS

1. User requests to list persons

2. AddressBook shows a list of persons

3. User requests to delete a specific person in the list

4. AddressBook deletes the person

   Use case ends.

Extensions

• 2a. The list is empty.

  Use case ends.

• 3a. The given index is invalid.

  • 3a1. AddressBook shows an error message.

    Use case resumes at step 2.

{More to be added}

Appendix D: Non Functional Requirements

1. Should work on any mainstream OS as long as it has Java 11 or above installed.

2. Should be able to hold up to 1000 persons without a noticeable sluggishness in performance for typical usage.

3. A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.

{More to be added}

Appendix E: Glossary

Mainstream OS

Windows, Linux, Unix, OS-X

Private contact detail

A contact detail that is not meant to be shared with others

Appendix F: Product Survey

Product Name

Author: …​

Pros:

• …​

• …​

Cons:

• …​

• …​

Appendix G: Instructions for Manual Testing

Given below are instructions to test the app manually.

ℹ️	These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

G.1. Launch and Shutdown

1. Initial launch

   1. Download the jar file and copy into an empty folder

   2. Double-click the jar file
      Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.

2. Saving window preferences

   1. Resize the window to an optimum size. Move the window to a different location. Close the window.

   2. Re-launch the app by double-clicking the jar file.
      Expected: The most recent window size and location is retained.

{ more test cases …​ }

G.2. Deleting a person

1. Deleting a person while all persons are listed

   1. Prerequisites: List all persons using the list command. Multiple persons in the list.

   2. Test case: delete 1
      Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated.

   3. Test case: delete 0
      Expected: No person is deleted. Error details shown in the status message. Status bar remains the same.

   4. Other incorrect delete commands to try: delete, delete x (where x is larger than the list size) {give more}
      Expected: Similar to previous.

{ more test cases …​ }

G.3. Saving data

1. Dealing with missing/corrupted data files

   1. {explain how to simulate a missing/corrupted file and the expected behavior}

{ more test cases …​ }