Skip to content

Commit 555240c

Browse files
vidakovicvidakovic
committed
FINERACT-1607: Improve documentation on Cucumber usage
1 parent 6111e69 commit 555240c

21 files changed

Lines changed: 384 additions & 22 deletions

‎build.gradle‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,7 @@ allprojects {
9696

9797
jgitver {
9898
strategy 'PATTERN'
99-
versionPattern '${M}.${m}.${p}-${meta.GIT_SHA1_8}'
100-
// versionPattern '${v}'
99+
versionPattern ( project.hasProperty('fineract.release.version') ? '${v}' : '${M}.${m}.${p}-${meta.GIT_SHA1_8}' )
101100
}
102101

103102
repositories {
@@ -265,6 +264,7 @@ configure(project.fineractJavaProjects) {
265264
apply plugin: 'se.thinkcode.cucumber-runner'
266265
apply from: "${rootDir}/buildSrc/src/main/groovy/org.apache.fineract.dependencies.gradle"
267266

267+
group = 'org.apache.fineract'
268268

269269
/* define the valid syntax level for source files */
270270
sourceCompatibility = JavaVersion.VERSION_17
@@ -590,10 +590,15 @@ configure(project.fineractJavaProjects) {
590590

591591
configure(project.fineractPublishProjects) {
592592
apply plugin: 'maven-publish'
593+
apply plugin: 'signing'
593594

594595
publishing {
595596
publications {
596597
mavenJava(MavenPublication) {
598+
groupId 'org.apache.fineract'
599+
artifactId project.name
600+
version "${project.version}-SNAPSHOT"
601+
597602
from components.java
598603

599604
versionMapping {
@@ -606,7 +611,7 @@ configure(project.fineractPublishProjects) {
606611
}
607612

608613
pom {
609-
name = 'Fineract'
614+
name = "Fineract: ${project.name}"
610615
description = 'A secure, multi-tenanted microfinance platform'
611616
url = 'https://fineract.apache.org'
612617
licenses {
@@ -624,7 +629,23 @@ configure(project.fineractPublishProjects) {
624629
}
625630
}
626631

627-
// TODO FINERACT-1102: Actually use this to deploy to ASF (Apache Software Foundation) Nexus Maven Repository
632+
repositories {
633+
def releaseUrl = 'https://repository.apache.org/content/repositories/releases'
634+
def stagingUrl = 'https://repository.apache.org/content/repositories/snapshots'
635+
636+
maven {
637+
name 'apache'
638+
url hasProperty('fineract.release.version') ? releaseUrl : stagingUrl
639+
credentials {
640+
username "${findProperty('fineract.config.username')}"
641+
password "${findProperty('fineract.config.password')}"
642+
}
643+
}
644+
}
645+
}
646+
647+
signing {
648+
sign publishing.publications.mavenJava
628649
}
629650
}
630651

‎fineract-doc/src/docs/en/chapters/release/index.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,5 @@ include::{diagramsdir}/release-schedule.puml[]
1111
include::configuration.adoc[leveloffset=+1]
1212

1313
include::process.adoc[leveloffset=+1]
14+
15+
include::publish.adoc[leveloffset=+1]

‎fineract-doc/src/docs/en/chapters/release/publish.adoc‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
= Publish Release Artifacts
2+
3+
NOTE: More on releases at the ASF see https://www.apache.org/legal/release-policy.html#distribute-raw-artifact
4+
5+
== Requirements
6+
7+
You need to have your GPG keypairs properly set up. The JAR release artifacts (currently only `fineract-client`) are signed with a Gradle plugin just before being uploaded to the Maven repository. Please make sure that the following properties are set in your private `gradle.properties` file in your home folder:
8+
9+
[source,properties]
10+
----
11+
signing.keyId=7890ABCD
12+
signing.password=*****
13+
signing.secretKeyRingFile=~/.gnupg/secring.gpg
14+
----
15+
16+
This is quite similiar to the Fineract release plugin properties for GPG. In one of the next release we'll merge these two setups to avoid this duplicated configuration.
17+
18+
== Maven Repository
19+
20+
We are using the ASF's official https://repository.apache.org[Nexus Maven repository] to publish our snapshot and release artifacts.
21+
22+
NOTE: Find more information at https://infra.apache.org/publishing-maven-artifacts.html
23+
24+
== NPM Registry
25+
26+
For convenience we will be using Github Packages to publish Fineract's Typescript API client.
27+
28+
TBD
29+
30+
== Docker Hub
31+
32+
TBD

‎fineract-doc/src/docs/en/chapters/testing/cucumber-cheatsheet.adoc‎

Lines changed: 108 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,109 @@
1-
= Cheatsheet
1+
= Cucumber Cheatsheet
22

3-
TBD
3+
Cucumber is a test framework based on Behavior-Driven Development (BDD). Tests are written in plain text with very basic syntax rules. These rules form a mini language that is called Gherkin.
4+
5+
A specification resembles spoken language. This makes it ideal for use with non-technical people that have domain specific knowledge. The emphasis of Cucumber lies on finding examples to describe your test cases. The few keywords and language rules are easy to explain to anyone (compared JUnit for example).
6+
7+
== Keywords
8+
9+
The Gherkin language has the following keywords:
10+
11+
* `Feature`
12+
* `Rule`
13+
* `Scenario Outline` or `Scenario Template`
14+
* `Example` or `Scenario`
15+
* `Examples` or `Scenarios`
16+
* `Background`
17+
* `Given`
18+
* `And`
19+
* `But`
20+
* `When`
21+
* `Then`
22+
23+
There are a couple of additional signs used in Gherkin:
24+
25+
* `|` is as column delimiters in `Examples` tables
26+
* with `@` you can assign any kind of tags to categorize the specs (or e.g. relate them to certain Jira tickets)
27+
* `#` is used to indicate line comments
28+
29+
IMPORTANT: The tag `@ignore` is used to skip tests. This is a somewhat arbitrary choice (we could use any other tag to indicate temporarily disabled tests).
30+
31+
Each non-empty line of a test specification needs to start with one of these keywords. The text blocks that follows the keywords are mapped to so called step definitions that contain the actual test code.
32+
33+
A typical Cucumber test specification written in Gherkin looks like this:
34+
35+
[source,gherkin,subs="attributes+,+macros"]
36+
----
37+
include::{rootdir}/fineract-provider/src/test/resources/features/template/template.service.feature[lines=19..]
38+
----
39+
40+
The corresponding step definitions would look like this:
41+
42+
[source,java,subs="attributes+,+macros"]
43+
----
44+
include::{rootdir}/fineract-provider/src/test/java/org/apache/fineract/template/service/TemplateServiceStepDefinitions.java[lines=19..]
45+
----
46+
47+
NOTE: This example is an actual test specification that you can find in the `fineract-provider` module.
48+
49+
=== Feature
50+
51+
This keyword is used to group scenarios and to group related scenarios. All Gherkin specifications must start with the word `Feature`.
52+
53+
=== Descriptions
54+
55+
A description is any non-empty line that doesn't start with a keyword. Descriptions can be placed under the keywords:
56+
57+
* `Feature`
58+
* `Rule`
59+
* `Background`
60+
* `Example`/`Scenario`
61+
* `Scenario Outline`
62+
63+
=== Rule
64+
65+
Rule is used to group multiple related scenarios together.
66+
67+
=== Example/Scenario
68+
69+
This is the important part of the specification as it should describe the business logic in more detail with the usage of steps (usually `Given`, `When`, `Then`)
70+
71+
=== Steps
72+
73+
TBD
74+
75+
=== Given
76+
77+
TBD
78+
79+
=== When
80+
81+
TBD
82+
83+
=== Then
84+
85+
TBD
86+
87+
=== And, But
88+
89+
TBD
90+
91+
=== Background
92+
93+
TBD
94+
95+
=== Scenario Outline
96+
97+
TBD
98+
99+
=== Examples/Tables
100+
101+
TBD
102+
103+
== Outlook
104+
105+
As a proof of concept we've converted all unit tests in `fineract-provider` into Cucumber tests. The more interesting part starts when we'll attack the integration tests with over 400 mostly business logic related tests. These tests fit very well in Cucumber's test specification structure (a lot of _if-then-else_ or in Gherkin: _Given-When-Then_). Migrating all tests will take a while, but we would already recommend trying to implement tests as Cucumber specifications. It should be relatively easy to convert these tests into the new syntax.
106+
107+
Hopefully this will motivate even more people from the broader Fineract community to participate in the project by sharing their domain specific knowledge as Cucumber specifications. Specifications are written in Englisch (although not a technical requirement).
108+
109+
NOTE: Have a look at the specifications in `fineract-provider` for an initial inspiration. For more information please see https://cucumber.io/docs

‎fineract-doc/src/docs/en/chapters/testing/cucumber-introduction.adoc‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎fineract-doc/src/docs/en/chapters/testing/cucumber-tutorial.adoc‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎fineract-doc/src/docs/en/chapters/testing/cucumber.adoc‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,4 @@
33

44
TBD
55

6-
include::cucumber-introduction.adoc[leveloffset=+1]
7-
8-
include::cucumber-tutorial.adoc[leveloffset=+1]
9-
106
include::cucumber-cheatsheet.adoc[leveloffset=+1]

‎fineract-doc/src/docs/en/index.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,16 +39,16 @@ include::chapters/development/index.adoc[leveloffset=+1]
3939

4040
include::chapters/security/index.adoc[leveloffset=+1]
4141

42-
include::{rootdir}/fineract-client/build/generated/asciidoc/index.adoc[leveloffset=+1]
43-
44-
include::chapters/sdk/index.adoc[leveloffset=+1]
45-
4642
include::chapters/testing/index.adoc[leveloffset=+1]
4743

4844
include::chapters/documentation/index.adoc[leveloffset=+1]
4945

5046
include::chapters/release/index.adoc[leveloffset=+1]
5147

48+
include::chapters/sdk/index.adoc[leveloffset=+1]
49+
50+
include::{rootdir}/fineract-client/build/generated/asciidoc/index.adoc[leveloffset=+1]
51+
5252
include::faq.adoc[leveloffset=+1]
5353

5454
include::glossary.adoc[leveloffset=+1]

‎fineract-provider/build.gradle‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,11 @@ compileJava.doLast {
5151
import org.apache.tools.ant.filters.ReplaceTokens
5252

5353
task prepareInputYaml {
54-
outputs.file('config/swagger/fineract-input.yaml')
54+
outputs.file("${buildDir}/tmp/swagger/fineract-input.yaml")
5555

5656
doLast {
5757
copy {
58-
from file('config/swagger/fineract-input.yaml.template')
58+
from file("${projectDir}/config/swagger/fineract-input.yaml.template")
5959
into file("${buildDir}/tmp/swagger")
6060
rename { String filename -> return 'fineract-input.yaml' }
6161
filter(ReplaceTokens, tokens: [VERSION: "${project.version}".toString()])
@@ -323,6 +323,7 @@ jar.dependsOn resolve
323323
test.dependsOn resolve
324324
checkstyleMain.dependsOn resolve
325325
checkstyleTest.dependsOn resolve
326+
rat.dependsOn prepareInputYaml
326327
spotbugsTest.dependsOn resolve
327328
compileTestJava.dependsOn ':fineract-client:processResources'
328329
bootJarMainClassName.dependsOn resolve

‎fineract-provider/src/test/resources/features/accounting/accounting.common.feature‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1+
#
2+
# Licensed to the Apache Software Foundation (ASF) under one
3+
# or more contributor license agreements. See the NOTICE file
4+
# distributed with this work for additional information
5+
# regarding copyright ownership. The ASF licenses this file
6+
# to you under the Apache License, Version 2.0 (the
7+
# "License"); you may not use this file except in compliance
8+
# with the License. You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing,
13+
# software distributed under the License is distributed on an
14+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
# KIND, either express or implied. See the License for the
16+
# specific language governing permissions and limitations
17+
# under the License.
18+
#
19+
120
Feature: Accounting Service
221

322
@accounting

0 commit comments

Comments
 (0)