Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Standardize plugins configuration #3156

Merged
merged 1 commit into from
Sep 16, 2022
Merged

Standardize plugins configuration #3156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/modules/developer-guides/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
* xref:extension-points.adoc[Extension points]
** xref:extensions.adoc[Extensions]
** xref:plugins.adoc[Plugins]
** xref:custom-modules.adoc[Custom modules]
13 changes: 13 additions & 0 deletions docs/modules/developer-guides/pages/custom-modules.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
= Custom Modules

Custom modules are extensible and flexible mechanism for development and represent project-specific
logic (steps, transformers, expressions, etc.). The custom modules may depend on extensions and/or plugins,
may not have dependencies at all, also they may override default behaviour of plugins and extensions if needed,
but note that overriding of behaviour of other custom modules can yield undetermenistic behaviours.

:path: spring.xml
:key: custom module

include::partial$configuration.adoc[]

include::partial$features.adoc[]
19 changes: 3 additions & 16 deletions docs/modules/developer-guides/pages/extensions.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,7 @@
Extensions are basements for the plugins. An extension provides generic abstraction for common
functionality or wraps an external framework API.

The extension configuration should be placed at the `/src/main/resources/vividus-extension/spring.xml`
path relatively to the project root.
:path: vividus-extension/spring.xml
:key: extension

./src/main/resources/vividus-extension/spring.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd"
default-lazy-init="true">

<!-- extension bean definitions -->

</beans>
----
include::partial$configuration.adoc[]
238 changes: 7 additions & 231 deletions docs/modules/developer-guides/pages/plugins.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,236 +1,12 @@
= Plugins

Plugins are extensible and flexible mechanism for development. New plugin can be developed by
3rd party team and integrated.
Plugins are extensible and flexible mechanism for development and represent generic features that
can be used by multiple projects, it could be either VIVIDUS or external ones. The dependencies
between plugins are not recommended, all the generic logics should be moved to approppriate extensions.

The plugin configuration should be placed at the `/src/main/resources/spring.xml` path relatively
to the project root.
:path: vividus-plugin/spring.xml
:key: plugin

./src/main/resources/spring.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/util https://www.springframework.org/schema/util/spring-util.xsd"
default-lazy-init="true">
include::partial$configuration.adoc[]

<!-- plugin bean definitions -->

</beans>
----


== xref:ROOT:glossary.adoc#_table_transformer[Table Transformers]

In order to create and register own table transformer the following steps should
be done.

. Create a new class that implements
https://javadoc.io/doc/org.jbehave/jbehave-core/latest/org/jbehave/core/model/TableTransformers.TableTransformer.html[`org.jbehave.core.model.TableTransformers.TableTransformer`]:
+
./src/main/java/com/mycompany/transformer/MyTableTransformer.java
[source,java]
----
package com.mycompany.transformer;

import org.jbehave.core.model.TableTransformers.TableTransformer;

public class MyTableTransformer implements TableTransformer
{
@Override
public String transform(String tableAsString, TableParsers tableParsers, TableProperties properties)
{
String transformedTable = ...; // Table transformation logic
// ...
return transformedTable;
}
}
----

. Register Spring bean where `id` is the name of the transformer which will
be used to refer it in tests:
+
./src/main/resources/spring.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">

<bean id="MY_TRANSFORMER" class="com.mycompany.transformer.MyTableTransformer"/>

</beans>
----

. Use new transformer in tests:
+
./src/main/resources/story/MyStory.story
[source,gherkin]
----
Scenario: Use the custom tramsfomer to modify ExamplesTable
Given ...
When ...
Then ...
Examples:
{transformer=MY_TRANSFORMER}
|header |
|value 1|
|value 2|
----

[NOTE]
====
It's recommended to stick to the following naming conventions:

* `SCREAMING_SNAKE_CASE` for transfomer names:
+
[source,gherkin]
----
{transformer=MY_TRANSFORMER}
----
* `lowerCamelCase` for transformer parameters:
+
[source,gherkin]
----
{transformer=MY_TRANSFORMER, transformerParameter=value}
----
* `kebab-case` with dot `.` as a separator for transformer bean properties:
+
[source,properties]
----
transformer.my-transformer.my-property=value
----
+
Pay attention to the property format:
+
[source,properties]
----
transformer.<custom-transform-name>.<property-name>=<property-value>
----
====


== Dynamic variables

In order to create and register own dynamic variable the following steps should
be done.

. Create a new class that implements
https://github.com/vividus-framework/vividus/blob/master/vividus-engine/src/main/java/org/vividus/variable/DynamicVariable.java[`org.vividus.variable.DynamicVariable`]:
+
./src/main/java/com/mycompany/variable/MyDynamicVariable.java
[source,java]
----
package com.mycompany.variable;

import org.vividus.variable.DynamicVariable;
import org.vividus.variable.DynamicVariableCalculationResult;

public class MyDynamicVariable implements DynamicVariable
{
@Override
public DynamicVariableCalculationResult calculateValue()
{
try
{
String value = ...; // Variable value calcualtion
return DynamicVariableCalculationResult.withValue(value);
}
catch (MyException e)
{
return DynamicVariableCalculationResult.withError(e.getMessage());
}
}
}
----

. Register Spring bean where `id` is the name of the dynamic variable which will
be used to refer it in tests:
+
./src/main/resources/spring.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">

<bean id="my-dynamic-varibale" class="com.mycompany.variable.MyDynamicVariable"/>

</beans>
----

. Use new variable in tests:
+
./src/main/resources/story/MyStory.story
[source,gherkin]
----
Scenario: Validate with help of the custom dynamic variable
Then `${my-dynamic-varibale}` is equal to `my app specific value`
----
+
Keep in mind the alias for the dynamic variable with name in lower camel
case will be available out of the box:
+
./src/main/resources/story/MyStory.story
[source,gherkin]
----
Scenario: Validate with help of the custom dynamic variable
Then `${myDynamicVaribale}` is equal to `my app specific value`
----

== Baseline storages

Baseline storage is a source of the baseline images used to perform visual checks in xref:plugins:plugin-visual.adoc[visual testing plugin]

In order to create and register own baselines storages the following steps should be done

. Create a new class that implements
https://github.com/vividus-framework/vividus/blob/master/vividus-plugin-visual/src/main/java/org/vividus/visual/engine/BaselineStorage.java[`org.vividus.visual.engine.BaselineStorage`]:
+
./src/main/java/com/mycompany/visual/engine/AzureBaselineStorage.java
[source,java]
----
package com.mycompany.visual.engine;

import org.vividus.visual.engine.BaselineStorage;

public class AzureBaselineStorage implements BaselineStorage
{
@Override
public Optional<Screenshot> getBaseline(String baselineName) throws IOException
{
// gets the baseline screenshot
}

@Override
public void saveBaseline(Screenshot toSave, String baselineName) throws IOException
{
// saves the baseline screenshot
}

}
----

. Register Spring bean where `id` is the name of the baseline storage which will
be used in visual testing plugin:
+
./src/main/resources/spring.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">

<bean id="azure" class="com.mycompany.visual.engine.AzureBaselineStorage"/>

</beans>
----
include::partial$features.adoc[]
22 changes: 22 additions & 0 deletions docs/modules/developer-guides/partials/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
The {key} configuration should be placed at the following path relatively to the project root:

[source,xml,subs="attributes+"]
----
/src/main/resources/{path}
----

./src/main/resources/{path}
[source,xml,subs="attributes+"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/util https://www.springframework.org/schema/util/spring-util.xsd"
default-lazy-init="true">

<!-- {key} bean definitions -->

</beans>
----
Loading