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/06/08 07:51:54 UTC
[isis] 10/19: ISIS-2717: removes fixture's service docs,
as now part of refguide-index.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2717
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 1477dc3e8b758f470ba747a51af096f921b39d9e
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Jun 6 17:16:14 2021 +0100
ISIS-2717: removes fixture's service docs, as now part of refguide-index.
---
...ixtureScripts_020-configuration-properties.adoc | 9 +++
.../pages/fixture-scripts/api-and-usage.adoc | 35 ++++++-----
.../fixtures/pages/services/FixtureScripts.adoc | 59 ------------------
.../FixtureScriptsSpecificationProvider.adoc | 70 ----------------------
.../adoc/modules/fixtures/partials/module-nav.adoc | 4 --
5 files changed, 28 insertions(+), 149 deletions(-)
diff --git a/antora/components/refguide-index/modules/testing/pages/index/fixtures/applib/fixturescripts/hooks/FixtureScripts_020-configuration-properties.adoc b/antora/components/refguide-index/modules/testing/pages/index/fixtures/applib/fixturescripts/hooks/FixtureScripts_020-configuration-properties.adoc
new file mode 100644
index 0000000..e0909f1
--- /dev/null
+++ b/antora/components/refguide-index/modules/testing/pages/index/fixtures/applib/fixturescripts/hooks/FixtureScripts_020-configuration-properties.adoc
@@ -0,0 +1,9 @@
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
+:page-partial:
+
+
+== Configuration Properties
+
+The configuration properties used by this domain service can be found in the xref:refguide:config:sections/isis.testing.adoc[relevant section] of the config guide.
+
diff --git a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
index 0e849f6..6eb23ba 100644
--- a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
+++ b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
@@ -3,7 +3,7 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-There are two main parts to using fixture scripts: the `FixtureScripts` domain service class, and the `FixtureScript` view model class:
+There are two main parts to using fixture scripts: the xref:refguide:testing:index/fixtures/applib/fixturescripts/FixtureScripts.adoc[FixtureScripts] domain service class, and the xref:refguide:testing:index/fixtures/applib/fixturescripts/FixtureScript.adoc[FixtureScript] view model class:
* The role of the `FixtureScripts` domain service is to locate all fixture scripts from the classpath and to let them be invoked, either from an integration test/BDD spec or from the UI of your Isis app.
@@ -14,8 +14,8 @@ Let's look at `FixtureScripts` domain service in more detail first.
== `FixtureScripts`
-The framework provides a default implementation of `FixtureScripts` domain service, namely the xref:testing:fixtures:services/FixtureScripts.adoc[FixtureScriptsDefault] domain service.
-This is annotated to be rendered on the secondary "Prototyping" menu.
+The xref:refguide:testing:index/fixtures/applib/fixturescripts/FixtureScripts.adoc[FixtureScripts] domain service.
+This is annotated to be part of on the secondary "Prototyping" menu.
The behaviour of this domain menu service can be configured using the `isis.testing.fixtures.fixture-script-specification` configuration properties.
For example, here's the configuration used by the xref:docs:starters:simpleapp.adoc[SimpleApp] starter apps:
@@ -87,8 +87,9 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
[#fixturescript]
== `FixtureScript`
-A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.
-However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done.
+A xref:refguide:testing:index/fixtures/applib/fixturescripts/FixtureScript.adoc[FixtureScript] is responsible for setting up the system (or more likely, one small part of the overall system) into a known state, either for prototyping or for integration testing.
+
+The normal idiom is for the fixture script to invoke actions on business objects, in essence to replay what a real-life user would have done.
That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
For example, here's a fixture script called `RecreateSimpleObjects`.
@@ -101,37 +102,39 @@ import lombok.Getter;
import lombok.Setter;
@Accessors(chain = true)
-public class RecreateSimpleObjects extends FixtureScript { // <1>
+public class RecreateSimpleObjects extends FixtureScript { // <.>
- public final List<String> NAMES = Collections.unmodifiableList(Arrays.asList(
+ public final List<String> NAMES =
+ Collections.unmodifiableList(Arrays.asList(
"Foo", "Bar", "Baz", "Frodo", "Froyo",
- "Fizz", "Bip", "Bop", "Bang", "Boo")); // <2>
+ "Fizz", "Bip", "Bop", "Bang", "Boo")); // <.>
public RecreateSimpleObjects() {
- withDiscoverability(Discoverability.DISCOVERABLE); // <3>
+ withDiscoverability(Discoverability.DISCOVERABLE); // <.>
}
@Getter @Setter
- private Integer number; // <4>
+ private Integer number; // <.>
@Getter
- private final List<SimpleObject> simpleObjects = Lists.newArrayList(); // <5>
+ private final List<SimpleObject> simpleObjects =
+ Lists.newArrayList(); // <.>
@Override
- protected void execute(final ExecutionContext ec) { // <6>
+ protected void execute(final ExecutionContext ec) { // <.>
// defaults
- final int number = defaultParam("number", ec, 3); // <7>
+ final int number = defaultParam("number", ec, 3); // <.>
// validate
if(number < 0 || number > NAMES.size()) {
throw new IllegalArgumentException(
String.format("number must be in range [0,%d)", NAMES.size()));
}
// execute
- ec.executeChild(this, new SimpleObjectsTearDown()); // <8>
+ ec.executeChild(this, new SimpleObjectsTearDown()); // <.>
for (int i = 0; i < number; i++) {
final SimpleObjectCreate fs =
new SimpleObjectCreate().setName(NAMES.get(i));
- ec.executeChild(this, fs.getName(), fs); // <9>
- simpleObjects.add(fs.getSimpleObject()); // <10>
+ ec.executeChild(this, fs.getName(), fs); // <.>
+ simpleObjects.add(fs.getSimpleObject()); // <.>
}
}
}
diff --git a/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScripts.adoc b/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScripts.adoc
deleted file mode 100644
index c82ca75..0000000
--- a/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScripts.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[FixtureScripts]]
-= FixtureScripts
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-CAUTION: TODO: this needs to be converted into a hook for refguide-index
-
-The `FixtureScripts` service provides the ability to execute xref:fixtures:ROOT:about.adoc#api-and-usage[fixture scripts].
-
-The service is typically configured using the `isis.testing.fixtures.fixture-scripts-specification` configuration properties, for example telling it which package to search for xref:refguide:testing:index/ classes, how to execute those classes, and hints that influence the UI.
-
-
-
-== API
-
-The API for the service is:
-
-[source,java]
-----
-public abstract class FixtureScripts ... {
- @Programmatic
- public List<FixtureResult> runFixtureScript(
- FixtureScript fixtureScript,
- String parameters) { /* ... */ }
-}
-----
-
-
-== Implementation
-
-The default implementation is `o.a.i.applib.services.fixturespec.FixtureScriptsDefault`
-
-
-=== Configuration Properties
-
-The default implementation of this domain service supports the following configuration properties:
-
-.Core Configuration Properties for Fixture Events
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-
-|`isis.fixtures.fireEvents`
-|`true`,`false` +
-(`true`)
-|Whether fixture `FixturesInstallingEvent` and `FixturesInstalledEvent` events should be posted while the system is bootstrapping.
-
-Fixture events are fired to indicate the start and end of fixtures are being installed.
-This are listened to by the xref:refguide:applib:index/services/queryresultscache/QueryResultsCache.adoc[QueryResultsCache] to disable caching during this period.
-
-|===
-
-
diff --git a/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScriptsSpecificationProvider.adoc b/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScriptsSpecificationProvider.adoc
deleted file mode 100644
index 944257a..0000000
--- a/testing/fixtures/adoc/modules/fixtures/pages/services/FixtureScriptsSpecificationProvider.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-= `FixtureScriptsSpec'nProvider`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-CAUTION: TODO: this needs to be converted into a hook for refguide-index, and x-ref config properties as the preferred approach.
-
-
-The `FixtureScriptsSpecificationProvider` configures the xref:testing:fixtures:services/FixtureScripts.adoc[FixtureScripts] domain service, providing the location to search for fixture scripts and other settings.
-
-The service is used only by the default implementation of `FixtureScripts`, namely `FixtureScriptsDefault`.
-
-[TIP]
-====
-Of the two designs, we encourage you to implement this "provider" SPI rather than subclass `FixtureScripts`.
-The primary benefit (apart from decoupling responsibilities) is that it ensures that there is always an instance of `FixtureScripts` available for use.
-====
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface FixtureScriptsSpecificationProvider {
- @Programmatic
- FixtureScriptsSpecification getSpecification();
-}
-----
-
-where `FixtureScriptsSpecification` exposes these values:
-
-[source,java]
-----
-public class FixtureScriptsSpecification {
- public String getPackagePrefix() { /* ... */ }
- public FixtureScripts.NonPersistedObjectsStrategy getNonPersistedObjectsStrategy() { /* ... */ }
- public FixtureScripts.MultipleExecutionStrategy getMultipleExecutionStrategy() { /* ... */ }
- public Class<? extends FixtureScript> getRunScriptDefaultScriptClass() { /* ... */ }
- public DropDownPolicy getRunScriptDropDownPolicy() { /* ... */ }
- public Class<? extends FixtureScript> getRecreateScriptClass() { /* ... */ }
- ...
-}
-----
-
-The class is immutable but it has a builder (obtained using `FixturescriptsSpecification.builder(...)`) for a fluent API.
-
-== Implementation
-
-The xref:docs:starters:simpleapp.adoc[SimpleApp] starter app has a simple implementation of this service:
-
-[source,java]
-----
-import org.springframework.stereotype.Service;
-
-@Service
-public class DomainAppFixturesProvider implements FixtureScriptsSpecificationProvider {
- @Override
- public FixtureScriptsSpecification getSpecification() {
- return FixtureScriptsSpecification
- .builder(DomainAppFixturesProvider.class)
- .with(FixtureScripts.MultipleExecutionStrategy.EXECUTE)
- .withRunScriptDefault(RecreateSimpleObjects.class)
- .withRunScriptDropDown(FixtureScriptsSpecification.DropDownPolicy.CHOICES)
- .withRecreate(RecreateSimpleObjects.class)
- .build();
- }
-}
-----
diff --git a/testing/fixtures/adoc/modules/fixtures/partials/module-nav.adoc b/testing/fixtures/adoc/modules/fixtures/partials/module-nav.adoc
index 339bfa0..6401d07 100644
--- a/testing/fixtures/adoc/modules/fixtures/partials/module-nav.adoc
+++ b/testing/fixtures/adoc/modules/fixtures/partials/module-nav.adoc
@@ -3,9 +3,5 @@
* xref:testing:fixtures:about.adoc[Fixture Scripts]
-** Domain Services
-*** xref:testing:fixtures:services/ExecutionParametersService.adoc[ExecutionParametersService]
-*** xref:testing:fixtures:services/FixtureScripts.adoc[FixtureScripts]
-*** xref:testing:fixtures:services/FixtureScriptsSpecificationProvider.adoc[FixtureScriptsSpecificationProvider]