You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/05/23 13:45:52 UTC
[isis] 01/02: ISIS-2687: updates docs for removal of BDD specs and
lockdown etc from simpleapp
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch 2.0.0-M5
in repository https://gitbox.apache.org/repos/asf/isis.git
commit d603ffc64f6b851744e18f44eea25b4e67adf497
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun May 23 14:07:05 2021 +0100
ISIS-2687: updates docs for removal of BDD specs and lockdown etc from simpleapp
---
starters/adoc/modules/parent-pom/pages/about.adoc | 23 +++++
starters/adoc/modules/starters/pages/about.adoc | 23 +++--
.../adoc/modules/starters/pages/simpleapp.adoc | 103 +++------------------
3 files changed, 50 insertions(+), 99 deletions(-)
diff --git a/starters/adoc/modules/parent-pom/pages/about.adoc b/starters/adoc/modules/parent-pom/pages/about.adoc
index bb27cbd8..b1f4bfa 100644
--- a/starters/adoc/modules/parent-pom/pages/about.adoc
+++ b/starters/adoc/modules/parent-pom/pages/about.adoc
@@ -58,3 +58,26 @@ For the `isis-testing-xxx` modules (fixture scripts, unit test support, integ te
* `o.a.i.legacy:isis-legacy`
These all set up `<dependencyManagement>/<dependencies>` entries for all of the modules, meaning that there's only one place to update the version to Apache Isis (the reference to the parent POM).
+
+
+== Surefire Configuration
+
+The parent pom configuresthe Maven surefire plugin to execute multiple times, based on test class suffix.
+The suffixes are:
+
+* `Test` (unit tests, if any)
++
+this will explicitly _exclude_ any integration tests, though, as defined by ...
+
+* `IntegTest` (integ tests, if any)
+
+// for 2.0.0-M6, add:
+//* `IntegBddSpecs` (BDD specs, if any)
+
+[NOTE]
+====
+in 2.0.0-M5 there is a bug in that the `default-test` (default) execution is also implicitly configured, meaning that unit tests and integ tests are executed twice, and BDD specs (if any)are executed once.
+
+This has been fixed for the next milestone, with a separate execution defined for BDD specs.
+====
+
diff --git a/starters/adoc/modules/starters/pages/about.adoc b/starters/adoc/modules/starters/pages/about.adoc
index a5296ac..2b1df0f 100644
--- a/starters/adoc/modules/starters/pages/about.adoc
+++ b/starters/adoc/modules/starters/pages/about.adoc
@@ -9,16 +9,16 @@ To get started with a new application, download one of the two starter apps.
The helloworld app is a very minimal app, intended just as a starting point to learn what the framework is all about.
-The source code is in this link:https://github.com/apache/isis-app-helloworld[git repo] which you can either fork, or just download as a zip, either:
+The source code is in this link:https://github.com/apache/isis-app-helloworld[git repo] which you can either fork, or just download as a zip:
+* use JDO as the ORM, use:
++
include::helloworld-script-jdo.adoc[]
-to use JDO for the ORM, or:
-
+* to use JPA as the ORM, use:
++
include::helloworld-script-jpa.adoc[]
-to use JPA as the ORM.
-
TIP: A much more complete explanation of the structure of the app (and how to use it) can be found *xref:docs:starters:helloworld.adoc[here]*.
@@ -28,18 +28,19 @@ TIP: A much more complete explanation of the structure of the app (and how to us
This app has the same functionality as _HelloWorld_, but is structured so it can be used as a starting point for developing your own applications.
It also includes some xref:testing:integtestsupport:about.adoc[integration tests], xref:testing:fixtures:about.adoc[fixtures], and xref:testing:specsupport:about.adoc[BDD (Cucumber)] specs.
-The source code can be found in this link:https://github.com/apache/isis-app-simpleapp[git repo] which you can either fork, or just download as a zip, either:
+The source code can be found in this link:https://github.com/apache/isis-app-simpleapp[git repo] which you can either fork, or just download as a zip:
+* to use JDO as the ORM, use:
++
include::simpleapp-script-jdo.adoc[]
-to use JDO for the ORM, or:
-
+* to use JPA for the ORM, use:
++
include::simpleapp-script-jpa.adoc[]
-to use JPA as the ORM.
-TIP: A much more complete explanation of the structure of the app (and how to use it) can be found *xref:docs:starters:helloworld.adoc[here]*.
+TIP: A much more complete explanation of the structure of the app (and how to use it) can be found *xref:docs:starters:simpleapp.adoc[here]*.
== Updating to Newer Versions
@@ -56,3 +57,5 @@ For both apps you can bump to newer versions of the framework just by updating t
</parent>
----
<1> update as required.
+
+Check the release notes/migration notes for details on new features and of any breaking changes.
diff --git a/starters/adoc/modules/starters/pages/simpleapp.adoc b/starters/adoc/modules/starters/pages/simpleapp.adoc
index 6f932aa..a0aae43 100644
--- a/starters/adoc/modules/starters/pages/simpleapp.adoc
+++ b/starters/adoc/modules/starters/pages/simpleapp.adoc
@@ -19,7 +19,7 @@ These modules can depend on each other, but Maven will to ensure that dependenci
In this way your application will be a "modular monolith"; said another way it will prevent your application from degenerating into a link:https://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
See also the discussion <<structure-of-the-app,below>>.
-The application also includes examples of unit tests, integration tests and BDD (cucumber) specs.
+The application also includes examples of unit tests and integration tests.
You'll find these in their own Maven modules (`simpleapp-...-module-simple-tests` and `simpleapp-...-webapp-tests`).
Normally we recommend that tests should be in the same Maven module as the code that they exercise.
The simpleapp doesn't do it this way just to give you the option to exclude them while initially prototyping/exploring a domain.
@@ -859,52 +859,12 @@ JQuery is available by default.
Note that there is no `src/main/webapp/` or `WEB-INF/web.xml` - the servlets and filters are configured by Apache Isis automatically.
+[#integration-tests]
=== webapp-test's src/test/java
-Under `src/test/java` we have different sets of tests.
-We'll inspect each in turn.
-
-IMPORTANT: the naming convention -- with `Test`, `IntegTest` and `IntegBddSpecs` suffixes -- is important, because the Maven surefire plugin is configured to run multiple times, one `<execution>` for each suffix.
-
-==== BDD Specs
-
-The simplapp starter app includes support for xref:testing:specsupport:about.adoc[BDD (Cucumber)] specifications.
-These reside under `domain.webapp.bdd`:
-
-[source]
-----
-src/test/java
- domainapp/
- webapp/
- bdd/
- glue/
- SimpleObjectsStepDef.java <.>
- specs/
- SimpleObjectSpec_listAllAndCreate.feature <.>
- RunIntegBddSpecs.java <.>
-----
-<.> defines the step definitions (or "glue") which describes how to interact with the application. +
-This class inherits from `WebAppIntegTestAbstract`, the base class for integration tests, described in the <<integration-tests,next section>>.
-<.> the feature file, discussed below.
-<.> boilerplate used to run the BDD Cucumber tests using JUni5 4.x.
-
-There is just one feature file: `SimpleObjectSpec_listAllAndCreate.feature`, which is pretty simple:
-
-[source,feature]
-----
-Feature: List and Create New Simple Objects
-
- Scenario: Existing simple objects can be listed and new ones created
- Given there are initially 3 simple objects
- When I create a new simple object
- Then there are 4 simple objects
-----
-
-The set up of the 3 initial objects is part of the step definitions.
+Under `src/test/java` we have a number of integration tests,
-[#integration-tests]
-==== Integration Tests
The integration tests are in `domainapp.application.integtests`:
@@ -917,21 +877,16 @@ src/
webapp/
integtests/
metamodel/
- lockdown/
- approved/
- ...
- current/
- ...
- LockDownMetaModel_IntegTest.java <.>
+ SwaggerExport_IntegTest.java <.>
ValidateDomainModel_IntegTest.java <.>
smoke/
Smoke_IntegTest.java <.>
ApplicationIntegTestAbstract.java <.>
----
-<.> Uses approval tests to verify that the metamodel is unchanged between releases of Apache Isis.
+<.> Exports the Swagger definition file.
+
-Discussed in more detail below.
+This could then be used to automate generation of client stubs in various languages.
<.> Bootstraps the app and runs the metamodel validators to check that there are not metamodel errors.
+
@@ -942,47 +897,17 @@ This can also be done simply when running the application, but performing the ch
<.> Base class used to bootstrap all integration tests for this module.
It is very similar to the base class used to bootstrap the integration tests for the simple module xref:simpleapp.adoc#simplemoduleintegtestabstract[], but referencing `ApplicationModule` rather than `SimpleModule`.
-The purpose of the metamodel lockdown tests is to capture regressions in Apache Isis itself whenever it is updated.
-
-Normally the metamodel of the application will evolve all of the time, so the metamodel lockdown tests are disabled by default and only enabled with `-Dmetamodel.lockdown`.
-If you want to capture the current metamodel, then enable and they will likely fail.
-The new export of the metamodel will be in `current` and can simply be approved (by copying over to the `approved` directory.
-
-However, if you are upgrading Apache Isis then you may want to check that the metamodel being built by the next version of Apache Isis is the same as previous.
-In this case, update Apache Isis (by updating the `<version> of the parent pom) and run the lockdown tests to check for differences.
-
-
-
-==== Unit Tests
-
-The integration tests are in `domainapp.application.unittests`:
-
-[source]
-----
-src/test/java
- domainapp/
- webapp/
- unittests/
- mavendeps/
- lockdown/
- approved/
- ...
- current/
- ...
- LockDownMavenDeps_Test.java <!--1-->
- util/
- CurrentVsApprovedApprovalTextWriter.java <!--2-->
-----
-<1> lock down test to check the transitive set of dependencies used by the application
-<2> utility class used by the lock down tests (unit tests and integ tests).
+[IMPORTANT]
+====
+The naming convention of tests classes is important, because the starter parent pom xref:parent-pom:about.adoc#surefire-configuration[configures the Maven surefire plugin] to execute multiple times, based on test class suffix.
-The maven dependency lock down tests are disabled by default, only enabled using `-Dmavendeps.lockdown`.
-The `pom.xml` is configured to run the Maven `dependency:tree` and `dependency:list` goals, capturing the current dependencies.
-These are compared to the approved versions.
+The suffixes are: `Test` (unit tests, if any) and `IntegTest` (integ tests, if any).
-Any time the Apache Isis version is updated, run these tests using `-Dmavendeps.lockdown` to capture and approve the new versions.
+// for 2.0.0-M6, change to:
+//
+// The suffixes are: `Test` (unit tests, if any), `IntegTest` (integ tests, if any) and `IntegBddSpecs` (BDD cucumber specs, if any) respectively.
+====
-TIP: The Maven dependency lock down tests are useful to capture any accidental changes to the dependency tree, so consider enabling them all of the time.
=== Root module's pom.xml