Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dominikpanzer/cacamber-BDD-for-ABAP

Cacamber is the BDD-Framework for ABAP
https://github.com/dominikpanzer/cacamber-BDD-for-ABAP

abap bdd bdd-framework sap

Last synced: about 2 months ago
JSON representation

Cacamber is the BDD-Framework for ABAP

Host: GitHub
URL: https://github.com/dominikpanzer/cacamber-BDD-for-ABAP
Owner: dominikpanzer
License: mit
Created: 2023-05-01T18:06:31.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2023-05-30T20:35:26.000Z (over 1 year ago)
Last Synced: 2024-10-29T22:36:31.905Z (2 months ago)
Topics: abap, bdd, bdd-framework, sap
Language: ABAP
Homepage:
Size: 191 KB
Stars: 17
Watchers: 2
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

abap-florilegium - Cacamber

README

[![Run abaplint](https://github.com/dominikpanzer/cacamber-BDD-for-ABAP/actions/workflows/lint.yml/badge.svg)](https://github.com/dominikpanzer/cacamber-BDD-for-ABAP/actions/workflows/lint.yml)
[![Run Unit Tests](https://github.com/dominikpanzer/cacamber-BDD-for-ABAP/actions/workflows/unittest.yml/badge.svg)](https://github.com/dominikpanzer/cacamber-BDD-for-ABAP/actions/workflows/unittest.yml)
[![abap package version](https://img.shields.io/endpoint?url=https://shield.abap.space/version-shield-json/github/dominikpanzer/cacamber-BDD-for-ABAP/src/zif_cacamber_version.intf.abap/version&label=version)]()
[![Twitter](https://img.shields.io/twitter/follow/PanzerDominik?style=social)](https://twitter.com/PanzerDominik)

# Cacamber - the BDD-Framework for ABAP

Hi! Cacamber makes it possible for you to run BDD-style tests in a SAP-system. [Behavior driven development](https://en.wikipedia.org/wiki/Behavior-driven_development) is an agile approach to software development. It focusses on collaboration through a common language between the customer and developers, testers etc. by defining examples which describe the behavior of a software system in a natural language. This language has a specific format and is called [Gherkin](https://cucumber.io/docs/gherkin/). When using the [ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html) it looks like this (note: Cacamber supports different languages):
```
Feature: Discount calculation

Scenario: Discount on Slayer albums for VIP Slayer fans (exclusive contract with BMG)

Given the customers first name is Dominik and his last name is Panzer
and his birthdate according to our CRM system is 06.06.2006
when the sales clerk lets the system calculate the customers discount on a Slayer album
then the discount is 66% \m/
```
These scenarios or examples will be delivered by the business or ideally by the [3 amigos](https://automationpanda.com/2017/02/20/the-behavior-driven-three-amigos/) and will be used as executable specifications. You guessed it right: automated tests! So how can we execute these scenarios as automated tests?

You might already know the `Given ... When ... Then` pattern. It's quite similar to `arrange ... act ... assert`. They are both techniques to give tests a clear structure. In ABAP this usually looks like this. We focus on the the feature, give the test method an according name and write an acceptance test:

```ABAP
METHOD discount_calculation.
* Given
sut->do_this( parameter ).
sut->do_that( parameter ).
"more complex stuff here
DATA(product) = |Slayer Album|.

* When
DATA(discount) = sut->calculate( product ).

* Then
cl_abap_unit_assert=>assert_equals( exp = 66 act = discount ).
ENDMETHOD
```
The `Given ... When ... Then` comments are not very helpful. Also the individual parts of the test are not reusable. And the whole test is not very domain-centric compared to the scenario the business actually defined.

So some people wanted to do better and started writing their tests like this:

```ABAP
METHOD discount_on_slayer_albums.
given_cstmr_first_last_brthdy( EXPORTING first_name = 'Dominik'
last_name = 'Panzer'
birthdate = '20060606' ).
when_the_price_is_calculated_for( 'Slayer Album' ).
then_the_discount_is_correct( ).
ENDMETHOD
```
That's way better! Personally I only know one ABAP project with such kind of tests. Most of the details and complexity are hidden behind well named methods - another level of abstraction has been introduced. Also, there is the possibility to change the test parameters. This makes the steps of the test more flexible and reusable. But using parameterless methods would make the code more readable.

But this solution is no way near our original test case description. It's not natural language, it is mainly code. Also, this approach is limited by ABAPs maximum method length. Developers are forced to use abbreviations etc.

If you choose to use Cacamber as a bridge between the scenario written in plain Gherkin and ABAP Unit, your test steps will look like this:
```ABAP
METHOD discount_on_slayer_albums.
scenario( 'Discount on Slayer albums for VIP Slayer fans (exclusive contract with BMG)' ).

given( 'the customers first name is Dominik and his last name is Panzer' ).
and( 'his birthdate according to our CRM system is 06.06.2006' ).
when( 'the sales clerk lets the system calculate the customers discount on a Slayer album' ).
then( 'the discount is 66% \m/' ).
ENDMETHOD.
```

If it fails ABAP Unit can tell you this way:
```
...
Critical Assertion Error: 'Discount Calcuation: Discount on Slayer Albums for VIP Slayer fans (exclusive contract with BMG)'
...
```
Your tests can even look like this:
```ABAP
METHOD discount_on_a_shopping_cart.
scenario( 'Discount voucher applied to whole shopping card' ).

given( 'the customers has the following items in his shopping cart:' &&
'| 2 | Slayer | Reign In Blood | LP | 9,99€ |' &&
'| 1 | Slayer | South Of Heaven | LP | 9,99€ |' &&
'| 1 | David Hasselhoff | Crazy For You | LP | 9,99€ |' ).
and( 'he adds a valid 10% voucher' ).
when( 'the customer checks out' ).
then( 'the discount is 4€.' ).
ENDMETHOD.
```

Or like that:
```ABAP
METHOD no_discount_on_shopping_cart.
verify( 'Scenario: Customer is not eligible for a discount on the shopping cart' &&
'Given the customers first name is Dominik and his last name is Panzer' &&
'And his birthdate according to our CRM system is 06.06.2006' &&
'And in his shopping cart are the following items:' &&
'| 1 | Scooter - Hyper Hyper |' &&
'| 1 | Scooter - How Much Is The Fish |' &&
'| 1 | Scooter - Maria (I like it loud) |' &&
'When the sales clerk lets the system calculate the customers discount on the shopping cart' &&
'Then the discount is 0% \m/' ).
ENDMETHOD.
```
Cacamber supports keywords in different languages, so there is no need for you to translate your test cases to english.
Have I sparked your interest? Great.

## Give a Star! :star:
If you like or are using this project please give it a star. Thanks!

## Examples
If you don't like to read docs, check out the example class `ZCL_BDD_EXAMPLE` and `ZCL_BDD_EXAMPLE_2`, which show how to use Cacamber. They provide implementations of the above scenario "Discount on Slayer albums for VIP Slayer fans (exclusive contract with BMG)".

## The BDD cycle when using Cacamber
BDDs main target is to deliver quality software by making the communication between different team members easier. But most people just think about tools like Cucumber (or Cacamber ;-)) and test automation whenever they hear about BDD.

So how does BDD work and how does Cacamber fit in? Let us have a look:
1. Identify the important business features of your software and prioritize them.
1. Identify different scenarios of these features and prioritize them.
1. Define acceptance test descriptions for these scenarios. Use the Gherkin language for this. Make sure the whole team understands them. Scenarios are no technical descriptions. They describe the users intention, what the user actually does and what he wants to achieve.
1. Write the first scenario with Cacamber consisting of the relevant steps and place an `ASSERT` in the `THEN` step method. A step method needs to be a public method of your test class. Make sure there is just one `THEN`. You will need to inherit your test class from `ZCL_CACAMBER` and define a `FEATURE` and the `CONFIGURATION` for the steps in the `SETUP` of your test class. You will also need a test method `FOR TESTING`, put a `SCENARIO` and different steps using `GIVEN`, `WHEN`, `THEN` and the other available methods into the test method.
1. The new test method will most likely fail with an exception because the step methods are not implemented or the `ASSERT` failed. It might also go green if the step methods are already implemented and the existing business logic is able to pass the criteria of the `ASSERT`. Then you are done.
1. If the scenario fails, you will most likely need to write a new method for your business logic. Use TDD for this: Red-Green-Refactor. When your TDD tests are green, place the newly created or changed method into your step method. There might be more than one method call to your business logic in a single step method. You will also need to save the results of your business logic in attributes, so other step methods can access it (one step calculates a value, the next step validates it etc.)
1. Repeat until your scenario is green.
1. Refactor.
1. Start with the next scenario and reuse your steps methods.

If this is too abstract or too high level for you, have a look at the example implementation `ZCL_BDD_EXAMPLE` and `ZCL_BDD_EXAMPLE_2` or check out the Cacamber API documentation.

## Advantages of BDD
* Increases / improves collaboration between business, development and QA
* Makes communication in the team easier by using natural domain centric language
* The team can talk about the system behavior instead of technical implementation details
* Devs know when they are "done", because the clearly defined scenarios can be used as acceptance criteria
* Test scenarios are easily readable for new devs because they are written in a natural language
* Test steps can be reused
* Tests can be easily parameterized
* Tests are a living and up-to-date documentation
* Testing is shifted to the left of the dev process
* Automated BDD tests give the devs the security that the code still works and nothing breaks
* Fosters unit testing to implement the scenarios
* Hides complexity of implementations behind an abstraction layer
* etc.

## How does Cacamber technically work?
Cacamber basically works like this:
* When you call one of Cacambers methods like `GIVEN`, `WHEN`, `THEN`, etc or `VERIFY`, you provide a string as a parameter of these methods. This string is a single step in your test (when using `GIVEN` etc.) or also a complete scenario (when using `VERIFY`) written in natural language.
* Cacamber will take this string and check it against the configuration that was provided via the `CONFIGURE` method in the `SETUP` of your test class.
* The configuration consists of different entries. The first entry will be used to check if the regular expression ("pattern") and the provided string match. If it does Cacamber will extract the variables from the string.
* It then will call the method that was provided via the configuration and use the variables as parameters.
* If no regular expression matches, the next configuration entry will be checked etc.
* If no configuration entry can be found, Cacamber throws an exception.

## Cacamber API

This part of the document describes the public methods of Cacambers main class `ZCL_CACAMBER`. It provies methods for english Gherkin keywords. If you want to use another language, have a look at this mapping table:
| English | German |
|---------|----------|
| `ZCL_CACAMBER` | `ZCL_CACAMBER_GERMAN` |
| Given | Angenommen |
| And | Und |
| Or | Oder |
| But | Aber |
| _ | _ |
| When | Wenn |
| Then | Dann |
| Feature | Funktion |
| Scenario | Szenario |
| Example | Beispiel |
| Rule | Regel |

To get startet with Cacamber using english keywords, your local test class needs to inherit from `ZCL_CACAMBER`. For other languages have a look at the previous table.

`ZCL_CACAMBER` as your superclass provides the following public methods:

### FEATURE
The `FEATURE` method is optional and can be used to structure your test cases in a domain-centric way. Usually one test class will represents one feature, e.g. "discount calculation". This method has to be used in the `SETUP` of your test class. A `FEATURE` can be used to enhance the `MSG` parameter of your asserts.

Importing parameters:
* `FEATURE` - the name of your feature, max. 255 characters long

Example:
```ABAP
...
feature( 'Discount Calcuation' ).
...
cl_abap_unit_assert=>assert_equals( msg = current_feature exp = expected act = actual ).
...
```

### CONFIGURE
The method `CONFIGURE` maps a regex-string to a method, which should be executed whenever the regex matches. This is called a step. If you are not a regex-pro, you can use tools like [regex101](https://regex101.com/) to make things easier. Inside the regex you can use (.+) or other matchers to extract the variables from the string, which will be used by Cacamber as parameters for the method call. The order of the variables must match the order of the parameters of the step method which should be called when the regex matches. Your method is only allowed to have `IMPORTING`parameters. The configuration is usually done in the `SETUP`-method of your test class.

Supported types and regular expressions:
Currently Cacamber is able to handle the following basic datatypes, which you can use in your step methods parameters. You can also use DDIC types based on these.
| datatype | example matcher | description | example value |
|----------|-----------------|-------------|---------|
| `STRING` | ^hello (.+)$ | a string can basically by anything, use this as a fallback, ALPHA IN will be applied | Dominik |
| `DATE` | ^today is (.+)$ | DD.MM.YYYY a date will automatically be converted to internal format | 24.12.2023 |
| `TIMS`| ^it's (.+) o'clock$ | HH:MM:SS a time will automatically be converted to internal format | 14:01:00 |
| `CHAR`| ^add (.+) to cart$ | a character sequence | book |
| `INTEGER`| ^I am (.+) years old$ | for positive or negative integers | -200 |
| `PACKED` | ^the price is (.+)$ | a number with decimals seperated by a _dot_ | 1001.50 |
| datatable | ^Slayer had the following members:(.+)$ | a line or a table | see section about datatables |

Importing parameters:
* `PATTERN` - a REGEX-string which is used as a matcher
* `METHODNAME` - name of a _public_ method of your _test class_ with a matching interface. Can be upper or lower case.

Example:
```ABAP
...
configure->( pattern = '^the customers first name is (.+) and his last name is (.+)$' methodname = 'set_first_and_second_name' ).
...
```
The public method of your test class then must look like this:
```ABAP
...
PUBLIC SECTION.
METHODS set_first_and_second_name IMPORTING first_name TYPE char30
last_name TYPE char30.
...
METHOD set_first_and_second_name.
discount_calculator->set_first_name( first_name ).
discount_calculator->set_last_name( last_name ).
ENDMETHOD.
```
Your test method looks like this:
```ABAP
METHOD discount_on_slayer_albums.
...
given( 'the customers first name is Dominik and his last name is Panzer' ).
...
ENDMETHOD.
```

### SCENARIO
A scenario describes a variant of a feature and represents a test case. Therefore the `SCENARIO` method is usually used as the first method call in a test method of your local test class. A `SCENARIO` can be used to enhance the `MSG` parameter of your asserts.

Importing parameters:
* `SCENARIO` - the name of the scenario, max. 255 characters long

Example:
```ABAP
...
scenario( 'Discount on Slayer Albums for VIP Slayer fans (exclusive contract with BMG)' ).
...
cl_abap_unit_assert=>assert_equals( msg = current_scenario exp = expected act = actual ).
...
```

### EXAMPLE
The method `EXAMPLE` works the same way `SCENARIO` does.

Importing parameters:
* `SCENARIO` - the name of the scenario, max. 255 characters long

Example:
```ABAP
...
example( 'Discount on Slayer Albums for VIP Slayer fans (exclusive contract with BMG)' ).
...
cl_abap_unit_assert=>assert_equals( msg = current_scenario exp = expected act = actual ).
...
```

### RULE
With the method `RULE` you can describe a single business rule which will be implemented. It can be used in your local test methods just like `SCENARIO` or `EXAMPLE`. A `RULE` can be used to enhance the `MSG` parameter of your asserts.

Importing parameters:
* `RULE` - description of a business rule, max. 255 characters long

Example:
```ABAP
...
rule( 'only VIP customers can buy the album 7 days before the officiall realease date' ).
...
cl_abap_unit_assert=>assert_equals( msg = current_rule exp = expected act = actual ).
...
```

### GIVEN
The `GIVEN` method is an actual keyword of the Gherkin language. It represents a step. A BDD test case consists of steps which combined represent an expectation of the bahavior of the system. The paramter `STEP` will be matched against the regex-patterns of the configuration to find an actual method to process the data provided by the step.
A step can use any supported data type. If this doesnt suit your usecase, import the variable as a `STRING` into your step method and convert it there.