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 Serenity Dojo Online Training Programme.

Setting up your environment

To run this tutorial, you will need JDK 8 or higher, Maven and Git.

You will also need a modern Java IDE such as IntelliJ IDE (this is our recommendation - the free Community Edition will do fine). Make sure that the bundled Cucumber for Java plugin is enabled.

You can also use 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 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

To check that the application is running correctly, open http://localhost:9000/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:9000/swagger-ui.html

kanohapierre / bddtrader