README.md

# Sitodo (PMPL Variant)

[![pipeline status](https://gitlab.cs.ui.ac.id/pmpl/examples/sitodo-pmpl/badges/main/pipeline.svg)](https://gitlab.cs.ui.ac.id/pmpl/examples/sitodo-pmpl/-/commits/main)
[![coverage report](https://gitlab.cs.ui.ac.id/pmpl/examples/sitodo-pmpl/badges/main/coverage.svg)](https://gitlab.cs.ui.ac.id/pmpl/examples/sitodo-pmpl/-/commits/main)

A basic todo app project for teaching basic Web programming, Git workflows, and
CI/CD. Heavily inspired by the running example in "Test-Driven Development with
Python" book by Harry Percival.

> Note: The project has been customised from [the upstream](https://github.com/addianto/sitodo)
> in order to be used in PMPL (SQA) course at the Faculty of Computer Science Universitas Indonesia.

## Table of Contents

1. [Getting Started](#getting-started)
   1. [Setting Up Development Environment](#setting-up-development-environment)
   2. [Build & Run](#build--run)
   3. [Running Example](#running-example)
2. [Behavior-Driven Development (BDD)](#behavior-driven-development-bdd)
3. [License](#license)
4. [Written Exercise Report (For PMPL (SQA) Course Participants)](#written-exercise-report-for-pmpl-sqa-course-participants)

## Getting Started

### Setting Up Development Environment

The following tools need to be installed in order to build and run the project:

-  [Java 17 JDK (Java Development Kit)](https://adoptium.net)
-  PostgreSQL 14
    -  You can install PostgreSQL system-wide or use container (Docker/Podman).
-  [Apache Maven 3.8.5](https://maven.apache.org/download.cgi)
-  [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/)
    - Required by the functional (Selenium) test suite and BDD test suite.

Ensure `java`, `javac`, and `mvn` commands can be invoked from inside the shell:

```shell
$ java --version
openjdk 17.0.3 2022-04-19
OpenJDK Runtime Environment Temurin-17.0.3+7 (build 17.0.3+7)
OpenJDK 64-Bit Server VM Temurin-17.0.3+7 (build 17.0.3+7, mixed mode, sharing)
$ javac --version
javac 17.0.3
$ mvn --version
Apache Maven 3.8.2 (ea98e05a04480131370aa0c110b8c54cf726c06f)
```

We recommend [IntelliJ IDEA](https://www.jetbrains.com/idea/) Community Edition
as the IDE for developing the project. Other IDE or text editors, such as Eclipse
and Visual Studio Code, might work. However, we may not be able to help troubleshoot
any IDE-related issues. In addition, we include IntelliJ-specific **run configurations**
in the codebase that will add shortcuts for running the test suites and coverage
reporting from within IntelliJ.

### Build & Run

To run the whole test suite, execute:

```shell
mvn test
```

> To run a select test suite, e.g. unit or functional test, add `-Dgroups`
> parameter. For example, to run only the unit test suite, execute
> `mvn test -Dgroups=unit`.  Similarly, to run only the functional test suite,
> execute `mvn test -Dgroups=e2e`.

To build an executable Spring Boot application, execute:

```shell
mvn package -DskipTests
```

> The `-DskipTests` option lets `package` task to build the app into executable
> JAR file without running all test suites. If the option was omitted, then
> all test suites will run, thus increasing the duration of the building process,
> especially the functional test suite that runs much longer than the unit test
> suite.

The JAR file will be generated at [`./target`](./target) directory. To run it,
execute:

```shell
java -jar sitodo.jar
```

You can customise the configuration by providing an `application.properties`
file in the same directory as the executable JAR file. See the built-in
configuration in the [source code](./src/main/resources/application.properties).

You can also set the configuration during runtime using environment variables.
Following Spring Boot convention, properties are named in all uppercase and dot separators are replaced with underscores.
For instance, `spring.datasource.url` becomes `SPRING_DATASOURCE_URL` when configured using an environment variable.
See the example in the [GitLab CI/CD configuration](./.gitlab-ci.yml), specifically in the job for running tests.

### Running Example

See the running example based on the [upstream's `main` branch](https://gitlab.cs.ui.ac.id/pmpl/examples/sitodo-pmpl/-/tree/main) at [Fly.io](https://sitodo-pmpl.fly.dev).

## Behavior-Driven Development (BDD)

The executable test scenario in BDD usually follows a structured outline.
In this example, we follow the `Given-When-Then` format.
`Given` is to set up the pre-conditions, `When` is to perform the action, and `Then` is to verify the result.

For example, look at the following test scenario for ["Add new todo" feature](./src/test/resources/features/todo/add_new_todo.feature):

```gherkin
Feature: Add items into the todo list

    Scenario: Add single item into the list
        Given Alice is looking at the TODO list
        When she adds "Touch grass" to the list
        Then she sees "Touch grass" as an item in the TODO list

    Scenario: Add multiple items into the list
        Given Alice is looking at the TODO list
        When she adds "Buy bread" to the list
        And she adds "Buy candy" to the list
        Then she sees "Buy bread" as an item in the TODO list
        And she sees "Buy candy" as an item in the TODO list
```

One of the advantages of following this format is that the test scenario can be easily written by non-technical roles.
They can focus on writing the test scenario without worrying about the implementation details.

Eventually, there needs some way to "glue" the test scenario into the actual test code.
That is, the test scenario that is written in Gherkin format drives the test procedures in the test code.

To achieve that, we follow two patterns in writing the "glue" code: Screenplay & Page Object Model (POM).

We use the Page Object Model pattern to represent the significant elements of the user interface (UI)
(i.e. the HTML elements) in a more readable and reusable way for the test code.
While we can use the selector method provided by Selenium or Selenide to obtain the reference to a UI element,
it is more preferred to follow the Page Object Model since the BDD test scenarios has to be writable and readable both
by technical (e.g. developer, QA) and non-technical (e.g. user, business analyst) roles.

For example, see the code in `helpers` and `stepdefinitions`.

## Tasks

Your tasks are to write new test scenarios for two existing features that yet to be covered by the BDD test suite.
The two features are: "see motivation message" and "mark a todo item."
At minimum, you need to write **two new test scenarios** for both features.
The test scenarios can be as simple as covering the positive and negative case that can occur on both features.

### Mandatory Tasks

- [ ] Set up the development environment for the project locally
  - Refer to [Setting Up Development Environment](#setting-up-development-environment) section
- [ ] Run the project locally and try the existing features
  - Try to add new todo items and mark their completion status
  - See how the motivation message is updated based on the number of completed todo items
- [ ] Run the test suites locally, ensure all test passes
- [ ] Write two test scenarios for "see motivation message" feature
- [ ] Write two test scenarios for "mark a todo item" feature
- [ ] Write the required "glue" code to support the new test scenarios

> Note: You are allowed to modify the production code (i.e. the `src/main/java` directory) to make your test code can obtain the reference to the UI elements in the page.
> For example, you can add a new HTML attribute, CSS class, or CSS id to an element in the page to make it easier to be located.

### Additional Tasks

TBD.

> Outline:
> - Gherkin format (Given-When-Then) as executable scenarios
> - Glue code, step definitions
> - Screenplay & Page Object pattern
>
> Quotes:
> 
> - Ideally, if all of the acceptance criteria for a feature have been automated and run successfully, you can say that this feature is finished and ready for production.
> 
> References:
> - https://livebook.manning.com/book/bdd-in-action-second-edition/chapter-8
> - See chapter 8.5.1 of the BDD reference book to learn how to perform setup & teardown phase in BDD test.
>
> Draft Scenario: Todo item cannot be empty
> 
> - Given Alice is looking at the todo list
> - When she accidentally adds an empty item
> - Then she should be presented with a warning message containing "Todo item cannot be empty"

## License

This project is licensed under the terms of the [MIT license](./LICENSE).

## Written Exercise Report (For PMPL (SQA) Course Participants)

> You can write your report in English or Bahasa Indonesia.
>
> TODO: Write the URL to your deployed application in this section.
> 
> TODO: Write your report in this section.