# bdd-trader

**Repository Path**: mirrors_andyglick/bdd-trader

## Basic Information

- **Project Name**: bdd-trader
- **Description**: The BDD Trader application is a demo application used for exercises in the Serenity Dojo BDD workshops
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

= BDD Trader application

The BDD Trader application demonstrates BDD and test automation techniques using Serenity BDD and the Screenplay pattern.
These exercises are used as part of the upcoming **BDD for REST APIs with Cucumber and Serenity Screenplay** course
in the https://serenitydojo.teachable.com/p/the-programme[Serenity Dojo Online Training Programme].

== Setting up your environment
To run this tutorial, you will need http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html[JDK 8] or higher,
https://maven.apache.org[Maven] and https://git-scm.com/downloads[Git].

You will also need a modern Java IDE such as https://www.jetbrains.com/idea/download[IntelliJ IDE]
(this is our recommendation - the free Community Edition will do fine). Make sure that the bundled
https://plugins.jetbrains.com/plugin/7212-cucumber-for-java[Cucumber for Java] plugin is enabled.

You can also use https://www.getpostman.com[Postman] to experiment with the REST end points -
there is a set of preconfigured Postman queries in `src/test/resources/BDDTrader.postman_collection`.

Now clone this project to your local machine (you will need to setup a https://github.com[Github] account if you do not already have one):

-----
git clone git@github.com:serenity-bdd/bdd-trader.git
-----

== Building the project

This project uses a Maven build. To run the tests and build an executable jar, run:

----
mvn install
----

The first time you run this it may take some time to download the dependencies.

=== Running the application

You can run the application from the command line by running:

----
mvn spring-boot:run
----

or, to run the application using live market data, you can run

----
mvn spring-boot:run -Ddata.source=IEX
----

To check that the application is running correctly, open http://localhost:8080/api/status in your browser.

=== Running the tests

You can run the full test suite by running `mvn verify`.

=== The application domain

The application allows users to buy and sell shares using real market data.
Each **Client** is given a **Portfolio**, a special account where the client keeps track
of the shares they buy and sell. At any point in time, the client's **Position** represents
the number of shares they have in their portfolio, the amount of cash they have available,
and the current value of these shares. A client buys and sells shares by placing an **Order**.
When the order is executed, a **Trade** is recorded in the portfolio **history**.

=== The Client service
Clients need to register with the service by providing their first and last name via the `client` REST end-point.
When clients register, they are given a portfolio with $1000.

=== The Portfolio service

Each client has a portfolio to invest with.
You can view the details of a portfolio via the `/api/client/{clientId}/portfolio` endpoint.
Each portfolio has a unique identifier, and we use the portfolio identifier to interact with the portfolio.

You can place orders for trades to buy or sell shares through the portfolio.
In the DEV environment, a number of shares are predefined, including:

  * Amazon (AMZN)
  * Google (GOOG)
  * Apple (AAPL)
  * IBM (IBM)

You can see them all by using the `/api/stock/popular` endpoint.

Users place orders to buy or sell shares by posting a trade order to the `/api/portfolio/{portfolioId}/order` endpoint.
The share price and cost of the order can be provided (so that you can inject historical trades),
or will be based on the current market price if the price is set to 0. If the user has insufficient funds,
a 402 PAYMENT REQUIRED error will be returned.

You can see a client's current position via the `/api/portfolio/{portfolioId}/positions` endpoint.
You can also view a list of the trading history of a portfolio using `/api/portfolio/{portfolioId}/history`.

=== Swagger REST Documentation

When the application is running, you can see the REST API documentation at http://localhost:8080/swagger-ui.html

=== Tutorial

Continue learning with the **link:exercises.adoc[tutorial]**