# Week 8
## Developer Testing
- **Developer testing is the testing done by the developers themselves** as opposed to professional testers or end-users.
- Delaying testing until the full product is complete has a number of disadvantages:
- **Locating the cause of such a test case failure is difficult due to a large search space**.
- **Fixing a bug found during such testing could result in major rework**, especially if the bug originated during the design or during requirements specification.
- **One bug might 'hide' other bugs**, which could emerge only after the first bug is fixed.
- **The delivery may have to be delayed** if too many bugs were found during testing.
- **A test driver is the code that ‘drives’ the SUT(Software Under Test) for the purpose of testing** i.e. invoking the SUT with test inputs and verifying the behavior is as expected.
> PayrollTest ‘drives’ the Payroll class by sending it test inputs and verifies if the output is as expected.

public class PayrollTestDriver {
    public static void main(String[] args) throws Exception {

        //test setup
        Payroll p = new Payroll();

        //test case 1
        p.setEmployees(new String[]{"E001", "E002"});
        // automatically verify the response
        if (p.totalSalary() != 6400) {
            throw new Error("case 1 failed ");
        }

        //test case 2
        p.setEmployees(new String[]{"E001"});
        if (p.totalSalary() != 2300) {
            throw new Error("case 2 failed ");
        }

        //more tests...

        System.out.println("All tests passed");
    }
}

> This an automated test for a Payroll class, written using JUnit libraries.

@Test
public void testTotalSalary(){
    Payroll p = new Payroll();

    //test case 1
    p.setEmployees(new String[]{"E001", "E002"});
    assertEquals(6400, p.totalSalary());

    //test case 2
    p.setEmployees(new String[]{"E001"});
    assertEquals(2300, p.totalSalary());

    //more tests...
}

> Suppose we want to write tests for the IntPair class below.

public class IntPair {
    int first;
    int second;

    public IntPair(int first, int second) {
        this.first = first;
        this.second = second;
    }

    public int intDivision() throws Exception {
        if (second == 0){
            throw new Exception("Divisor is zero");
        }
        return first/second;
    }

    @Override
    public String toString() {
        return first + "," + second;
    }
}

> Here's a IntPairTest class to match (using JUnit 5).

import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.fail;

public class IntPairTest {


    @Test
    public void testStringConversion() {
        assertEquals("4,7", new IntPair(4, 7).toString());
    }

    @Test
    public void intDivision_nonZeroDivisor_success() throws Exception {
        assertEquals(2, new IntPair(4, 2).intDivision());
        assertEquals(0, new IntPair(1, 2).intDivision());
        assertEquals(0, new IntPair(0, 5).intDivision());
    }

    @Test
    public void intDivision_zeroDivisor_exceptionThrown() {
        try {
            assertEquals(0, new IntPair(1, 0).intDivision());
            fail(); // the test should not reach this line
        } catch (Exception e) {
            assertEquals("Divisor is zero", e.getMessage());
        }
    }
}

- Note:
- Each test method is marked with a **`@Test`** annotation.
- Tests use **`Assert.assertEquals(expected, actual)`** methods to compare the expected output with the actual output. If they do not match, the test will fail. JUnit comes with other similar methods such as **`Assert.assertNull`** and **`Assert.assertTrue`**.
- Java code normally use **camelCase** for method names e.g., `testStringConversion` but when writing test methods, sometimes another convention is used: `whatIsBeingTested_descriptionOfTestInputs_expectedOutcome` e.g., `intDivision_zeroDivisor_exceptionThrown`

## Writing Developer Documents
1. **Documentation for developer-as-user**: Software components are written by developers and reused by other developers, which means there is a need to document how such components are to be used. Such documentation can take several forms:
- **API** documentation: APIs expose functionality in small-sized, independent and easy-to-use chunks, each of which can be documented systematically.
- **Tutorial-style** instructional documentation: In addition to explaining functions/methods independently, some higher-level explanations of how to use an API can be useful.
2. **Documentation for developer-as-maintainer**: There is a need to document how a system or a component is designed, implemented and tested so that other developers can maintain and evolve the code. Writing documentation of this type is **harder because of the need to explain complex internal details**. However, given that readers of this type of documentation usually have access to the source code itself, only some information need to be included in the documentation, as code (and code comments) can also serve as a complementary source of information.

- TUTORIALS:
is learning-oriented
allows the newcomer to get started
is a lesson
Analogy: teaching a small child how to cook
- HOW-TO GUIDES:
is goal-oriented
shows how to solve a specific problem
is a series of steps
Analogy: a recipe in a cookery book
- EXPLANATION:
is understanding-oriented
explains
provides background and context
Analogy: an article on culinary social history
- REFERENCE:
is information-oriented
describes the machinery
is accurate and complete
Analogy: a reference encyclopedia article
- **Software documentation is best kept in a text format**, for the ease of version tracking. A writer friendly source format is also desirable as non-programmers (e.g., technical writers) may need to author/edit such documents. As a result, formats such as Markdown, Asciidoc, and PlantUML are often used for software documentation.

## Design: Models
- two main aspects:
- **Product/external design: designing the external behavior of the product to meet the users' requirements.** This is usually done by product designers with the input from business analysts, user experience experts, user representatives, etc.
- **Implementation/internal design: designing how the product will be implemented to meet the required external behavior.** This is usually done by software architects and software engineers.
- A model provides a simpler view of a complex entity because a model captures only a selected aspect.

## Class/Object Diagrams: Basics
- Object structures within the same software can change over time.
- However, object structures do not change at random; they change based on a set of rules, as was decided by the designer of that software. Those rules that **object structures need to follow can be illustrated as a class structure** i.e. a structure that exists among the relevant classes.

### Class Diagrams
- **UML class diagrams describe the structure (but not the behavior) of an OOP solution.**
- The basic UML notations used to represent a class:
- **The 'Operations' compartment and/or the 'Attributes' compartment may be omitted** if such details are not important for the task at hand. 'Attributes' always appear above the 'Operations' compartment. All operations should be in one compartment rather than each operation in a separate compartment. Same goes for attributes.
- The visibility of attributes and operations is used to indicate **the level of access allowed for each attribute or operation**. The types of visibility and their exact meanings depend on the programming language used. Here are some common visibilities and how they are indicated in a class diagram:
`+` : public
`-` : private
`#` : protected
`~` : package private
- In UML class diagrams, **underlines denote class-level attributes and variables.**
- **Associations are the main connections among the classes in a class diagram.**
- We use a solid line to show an association between two classes.

#### Labels
- **Association labels describe the meaning of the association**. The arrow head indicates the **direction** in which the label is to be read.
- Diagram on the left: Admin class is associated with Student class because an Admin object uses a Student object.
- Diagram on the right: Admin class is associated with Student class because a Student object is used by an Admin object.

#### Roles
- **Association Role labels are used to indicate the role played by the classes in the association.**
-This association represents a marriage between a Man object and a Woman object. The respective roles played by objects of these two classes are husband and wife.

class Man{
    Woman wife;
}

class Woman{
    Man husband;
}

#### Multiplicity
- Multiplicity is the aspect of an OOP solution that **dictates how many objects take part in each association**.

##### Implementing multiplicity
- **A normal instance-level variable gives us a `0..1` multiplicity** (also called optional associations) because a variable can hold a reference to a single object or `null`.
- **Bi-directional associations require matching variables in both classes.**

class Foo {
    Bar bar;
    //...
}

class Bar {
    Foo foo;
    //...
}

- **To implement other multiplicities, choose a suitable data structure** such as Arrays, ArrayLists, HashMaps, Sets, etc.
- Commonly used multiplicities:
`0..1` : optional, can be linked to 0 or 1 objects
`1` : compulsory, must be linked to one object at all times.
`*` : can be linked to 0 or more objects.
`n..m` : the number of linked objects must be n to m inclusive

#### Navigability
- The concept of which **class in the association knows about the other class** is called navigability.
- We **use arrow heads** to indication the navigability of an association.
> `Logic` is aware of `Minefield`, but `Minefield` is not aware of `Logic`


class Logic{
    Minefield minefield;
}

class Minefield{
    ...
}

- **Navigability can be shown in class diagrams as well as object diagrams.**

### Object Diagrams
- **An object diagram shows an object structure at a given point of time.**
- Notes:
- The class name and object name e.g. `car1:Car` are **underlined**.
- `objectName:ClassName` is meant to say 'an instance of `ClassName` identified as `objectName`'.
- Unlike classes, there is **no compartment for methods**.
- Attributes compartment can be omitted if it is not relevant to the task at hand.
- Object name can be omitted too e.g. :Car which is meant to say 'an unnamed instance of a Car object'.

### Associations as Attributes
- **An association can be shown as an attribute instead of a line.**
**`name: type [multiplicity] = default value`**
> A `Piece` may or may not be on a `Square`. Note how that association can be replaced by an `isOn` attribute of the `Piece` class. The `isOn` attribute can either be `null` or hold a reference to a `Square` object, matching the `0..1` multiplicity of the association it replaces. The default value is `null`

> The association that a `Board` has 100 `Square`s can be shown in either of these two ways:


### Notes
- **UML notes can augment UML diagrams with additional information.** These notes can be shown connected to a particular element in the diagram or can be shown without a connection.

## Project Mgt: Scheduling and Tracking
- A **milestone** is the end of a stage which **indicates a significant progress.**
- Each **intermediate product release** is a milestone.

### Buffer
- **A buffer is a time set aside to absorb any unforeseen delays.**
- **Do not inflate task estimates to create hidden buffers**; have explicit buffers instead.

### Issue tracker
- Issue trackers (sometimes called bug trackers) are commonly used to **track task assignment and progress.**

### Work Breakdown Structure
- A Work Breakdown Structure (WBS) **depicts information about tasks and their details in terms of subtasks.** When managing projects it is useful to divide the total work into smaller, well-defined units. Relatively complex tasks can be further split into subtasks. In complex projects a WBS can also include prerequisite tasks and effort estimates for each task.
- The effort is traditionally measured in man **hour/day/month**