Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@yanjustino
yanjustino authored May 3, 2021
1 parent 78ab657 commit 92e1fe5
Showing 1 changed file with 57 additions and 89 deletions.
146 changes: 57 additions & 89 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,113 +11,81 @@ It's a DSL based on the [Given-When-Then](https://martinfowler.com/bliki/GivenWh
# Getting Started

## Instalation
This package is available through Nuget Packages: ( 🇬🇧 ) https://www.nuget.org/packages/Gwtdo ou ( 🇧🇷 ) https://www.nuget.org/packages/Gwtdo.PtBr
This package is available through Nuget Packages (https://www.nuget.org/packages/Gwtdo).

| Package | Version | Downloads | Maintainability |
| ------- | ----- | ----- |----- |
| 🇬🇧 `GWTdo` | [![NuGet](https://img.shields.io/nuget/v/Gwtdo.svg)](https://www.nuget.org/packages/Gwtdo) | [![Nuget](https://img.shields.io/nuget/dt/Gwtdo.svg)](https://www.nuget.org/packages/Gwtdo) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/51e1962835f24f65a3813d078061a9ef)](https://www.codacy.com/gh/8T4/gwtdo/dashboard?utm_source=github.com&utm_medium=referral&utm_content=8T4/gwtdo&utm_campaign=Badge_Grade) |
| 🇧🇷 `GWTdo.PtBr` | [![NuGet](https://img.shields.io/nuget/v/Gwtdo.PtBr.svg)](https://www.nuget.org/packages/Gwtdo.PtBr) | [![Nuget](https://img.shields.io/nuget/dt/Gwtdo.PtBr.svg)](https://www.nuget.org/packages/Gwtdo.PtBr) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/51e1962835f24f65a3813d078061a9ef)](https://www.codacy.com/gh/8T4/gwtdo/dashboard?utm_source=github.com&utm_medium=referral&utm_content=8T4/gwtdo&utm_campaign=Badge_Grade) |

## Example
In our demonstration, we want to test class `Stock.cs`([see the code](src/Gwtdo.Sample/Stocks/Stock.cs)) and make sure it covers the following specification.

```yaml
Feature: User trades stocks
Scenario: User requests a sell before close of trading
Given I have 100 shares of MSFT stock
When I ask to sell 20 shares of MSFT stock
Then I should have 80 shares of MSFT stock
| `GWTdo` | [![NuGet](https://img.shields.io/nuget/v/Gwtdo.svg)](https://www.nuget.org/packages/Gwtdo) | [![Nuget](https://img.shields.io/nuget/dt/Gwtdo.svg)](https://www.nuget.org/packages/Gwtdo) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/51e1962835f24f65a3813d078061a9ef)](https://www.codacy.com/gh/8T4/gwtdo/dashboard?utm_source=github.com&utm_medium=referral&utm_content=8T4/gwtdo&utm_campaign=Badge_Grade) |

## Approaches

#### Natural Language
use the `GWTdo` DSL to facilitate natural language writing. With it, you write more readable tests with low formal language interference.

```c#
public void user_requests_a_sell()
{
SCENARIO["User trades stocks"] =
DESCRIBE | "User requests a sell before close of trading" |
GIVEN | "I have 100 shares of MSFT stock" |
WHEN | "I ask to sell 20 shares of MSFT stock" |
THEN | "I should have 80 shares of MSFT stock";
...
}
```

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>
Then map your specification as follows

```yaml
Feature: O usuário negocia ações
Scenario: O usuário solicita uma venda antes do fechamento da negociação
Dado que tenho 100 acoes MSFT
Quando eu peço para vender 20 ações da MSFT
Entao Eu deveria ter 80 ações da MSFT
```
Sessions "1. Test fixture", "Extension methods" and "Test" show how to implements this specification.
### 1. Test Fixtures
A test fixture is an environment used to consistently test some item, device, or piece of software. [[2]]()
In our example, the `StockFixture` is just a simple `record` ([C# 9.0](https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-9#record-types)) type that contains a
`Stock` instance as a property. All fixtures using `GWTdo` should have implemented `IFixture` interface.

![image](https://user-images.githubusercontent.com/357114/115149792-16723f00-a03c-11eb-8bbe-0685e15e76c4.png)

### 2. Extension methods

#### Alias directive
Use [alias directive](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-directive)
to make your extension methods more readable.

![image](https://user-images.githubusercontent.com/357114/115149879-6f41d780-a03c-11eb-859e-b04181d070bc.png)

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>

![image](https://user-images.githubusercontent.com/357114/115150857-8e426880-a040-11eb-8454-243888cd1170.png)


#### Arrange
Set up the object to be tested. We may need to surround the object with collaborators. For testing purposes, those collaborators might be test objects (mocks, fakes, etc.) or the real thing.
[[3]](https://xp123.com/articles/3a-arrange-act-assert/)

![image](https://user-images.githubusercontent.com/357114/115150066-2b030700-a03d-11eb-8442-bc4eb64b670b.png)

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>

![image](https://user-images.githubusercontent.com/357114/115150839-79fe6b80-a040-11eb-9d59-f12a9347e2ea.png)
```c#
public void Setup_user_trades_stocks_scenario()
{
SCENARIO["User trades stocks"] =
DESCRIBE | "User requests a sell before close of trading" |
GIVEN | "I have 100 shares of MSFT stock".MapAction(Have100SharesOfMsftStock) |
WHEN | "I ask to sell 20 shares of MSFT stock".MapAction(AskToSell20SharesOfMsftStock) |
THEN | "I should have 80 shares of MSFT stock".MapAction(ShouldHave80SharesOfMsftStock);
}

private static Action<StockFixture> Have100SharesOfMsftStock => f => f.Stocks.Buy("MSFT", 100);

#### Act
Act on the object (through some mutator). You may need to give it parameters (again, possibly test objects).
[[3]](https://xp123.com/articles/3a-arrange-act-assert/)
private static Action<StockFixture> Have150SharesOfApplStock => f => f.Stocks.Buy("APPL", 150);

![image](https://user-images.githubusercontent.com/357114/115150212-d57b2a00-a03d-11eb-8939-2933b68bc3d5.png)
private static Action<StockFixture> AskToSell20SharesOfMsftStock => f => f.Stocks.Sell("MSFT", 20);

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>

![image](https://user-images.githubusercontent.com/357114/115150807-66eb9b80-a040-11eb-8975-b0c546486226.png)


#### Assert
Make claims about the object, its collaborators, its parameters, and possibly (rarely!!) global state.
[[3]](https://xp123.com/articles/3a-arrange-act-assert/)

![image](https://user-images.githubusercontent.com/357114/115150366-605c2480-a03e-11eb-8b56-cf33f64beae6.png)

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>

![image](https://user-images.githubusercontent.com/357114/115150788-4cb1bd80-a040-11eb-9e74-1317073b046a.png)


### 3. Test
Now we are ready to test our code using the `StockFixture` and their extension methods (`Arrange`, `Act` and `Assert`).
For this, you should extend the `Feature<T>` class and instantiate the fixture in their `Fixture` property.

#### basic usage

![image](https://user-images.githubusercontent.com/357114/115150548-3e16d680-a03f-11eb-81a2-afd5bf38c8ea.png)

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>

![image](https://user-images.githubusercontent.com/357114/115150699-e88ef980-a03f-11eb-9afe-99c705ad96b0.png)
```
See the complete code in the [Natural Languange sample code](https://github.com/8T4/gwtdo/blob/main/src/samples/Gwtdo.Sample.Test/NaturalLanguange/Tests.cs).


#### Just code

#### example (3) - A little bit complex
If you prefer, you can only use code to write your specifications

![image](https://user-images.githubusercontent.com/357114/115150606-8209db80-a03f-11eb-9921-e78b28c1a9e2.png)
```c#

<p align="center"><b>🇧🇷 "Versão brasileira..."</b></p>
using arrange = Arrange<StockFixture>;
using act = Act<StockFixture>;
using assert = Assert<StockFixture>;

![image](https://user-images.githubusercontent.com/357114/115150659-c2695980-a03f-11eb-99f5-7b73f4575c5a.png)
[Fact]
public void user_requests_a_sell()
{
GIVEN.I_have_100_shares_of_MSFT_stock();
WHEN.I_ask_to_sell_20_shares_of_MSFT_stock();
THEN.I_should_have_80_shares_of_MSFT_stock();
}

public static arrange I_have_100_shares_of_MSFT_stock(this arrange fixtures) =>
fixtures.Setup((f) => f.Stocks.Buy("MSFT", 100));

public static act I_ask_to_sell_20_shares_of_MSFT_stock(this act fixtures) =>
fixtures.Excecute(f => f.Stocks.Sell("MSFT", 20));

public static assert I_should_have_80_shares_of_MSFT_stock(this assert fixtures) =>
fixtures.Verify(x => x.Stocks.Shares["MSFT"].Should().Be(80));
```
See the complete code in the [Just Code sample](https://github.com/8T4/gwtdo/blob/main/src/samples/Gwtdo.Sample.Test/JustCode/Tests.cs).

See those examples in the [sample 🇬🇧](src/Gwtdo.Sample.Test/Stocks) project ou, se preferir, veja nossa versão [brazuca 🇧🇷](src/Gwtdo.Sample.PtBr.Test/Stocks)

## Guide to contributing to a GitHub project
This is a guide to contributing to this open source project that uses GitHub. It’s mostly based on how many open sorce projects operate. That’s all there is to it. The fundamentals are:
Expand Down

0 comments on commit 92e1fe5

Please sign in to comment.