picimako / citric

Citrus framework integration for the IntelliJ platform.

Welcome Dear Visitor!

I create plugins for JetBrains products based on the IntelliJ Platform. I have more than a decade experience in QA and test automation, so my main focus is on test automation related libraries.

Beside the current projects I maintain, I also offer IDE plugin development and consultation services. If you are interested, you can contact me via one of the ways below.

On JetBrains Marketplace:

• Test automation: WireMocha Paid Plugin / Citric Paid Plugin / Mockitools / Gherkin Overview / Terra Support / JBehave Support (I took over its maintenance)
• IDE plugin development: Just Kitting

On npm:

• Test automation: lasponya

Places you can find me at: Website / LinkedIn / Twitter / I(J)nspector blog / JetBrains Platform Slack / E-mail: pmplugindev at protonmail dot com

citric's Issues

Inspections for the @CitrusTestSource annotation

Summary

Certain issues could be detected by static analysing the configuration of @CitrusTestSource annotations.

Tasks

• Create an inspection that can detect the following:
  • invalid test type
  • if a value in name is the same as the test method's name, the value from name can be removed.
  • if packageName is the same as the package of the current test class, the packageName attribute can be removed.
  • the file extension associated with the test type must not be specified at the end of the values in name.
  • the file extensions in sources must match the file extension of the test type in type.
  • the same files in name and sources may be deduplicated.

Code completion of citrus: functions

Summary

Citrus provides dedicated, so-called functions for generating data at various locations. These are prefixed with citrus:. To simplify the discovery of these functions, code completion could be implemented.

Tasks

• Implement code completion to suggest the list of available Citrus functions.
• The completion would be invoked in string literals where the preceding text is citrus:, and ideally citrus:.* with arbitrary text after the prefix for which it is true that at least one of the functions start with that text.
• For now, it would work only in the Java DSL.
• For now, it would not support custom function prefixes.

Resources

• Citrus functions

JSON schema for YAML based Citrus test source files

Summary

Citrus provides various DSLs besides Java to write tests, and one among them is YAML files.

Tasks

• Implement a custom JSON schema provider for Citrus YAML test source files.
• Such YAML files have to be recognized. That will be done based on the values specified in the citrus.yaml.file.name.pattern property of the citrus-application.properties.
  • If #17 is completed beforehand, custom configuration files must also be taken into account.
  • If the citrus.yaml.file.name.pattern property is not specified or is blank, then it will fall back to the Citrus defaults.
  • The file name patterns must be cached/indexed, and updated when the Citrus configuration file changes.
  • File name patterns that would match files with not .yml or .yaml extension should be excluded.
  • Optionally, for cases when the file name patterns are specified externally via the corresponding system property or environment variable, an option on the plugin settings UI could be introduced, so that users could customize/extend the list of YAML files to be recognized.
• Schemas must be Citrus-version specific, so that the proper schemas could be provided for different Citrus versions.

Questions

• Is there JSON schemas in the Citrus codebase, or must one be created from scratch?

Resources

• CitrusSettings class
• Providing meta information (like schema file)

Line marker for class path resource references

Summary

There is Java methods that accept resource paths, including paths of classpath resources. To make the navigation to those resources quicker, line markers could be added.

Tasks

• Implement line markers for methods that accept classpath resource paths.
  • File resource paths are out of scope.
• The line marker would display the icon of the referenced resource file.
• The line marker with a single click would open the resource in the editor.
• Paths are treated as classpath resources when either they have no prefix, or the prefix is classpath:.
• Since classpath resources are absolute, the logic will be to locate the src/test/resources folder of the current Java file's module, and locate the resource relative to that.

TBD

• The exact methods and arguments to support this are to be collected.

Inspections for `@*EndpointConfig`, `@*ClientConfig` and `@*ServerConfig` annotations

Summary

There are a handful of @*EndpointConfig / @*ClientConfig / @*ServerConfig annotations whose parser classes throw exceptions if the annotation configuration is not valid. In order to signal those invalid configurations, an inspection could be useful.

Tasks

• Add one or more inspections for the validating the following annotations:
  • @JmsEndpointConfig
  • @JmsSyncEndpointConfig
  • @KafkaEndpointConfig
  • @HttpClientConfig
  • @HttpServerConfig
  • @WebServiceClientConfig

Citrus Quarkus support

Summary

Citrus v4 add Quarkus runtime support.

Tasks

• Introduce JUnit5 specific Citrus Quarkus test framework.
• Inspection: If the test class is annotated with @org.citrusframework.quarkus.CitrusSupport but not with @QuarkusTest, then it is probably an issue to report.
• Inspection: A test class annotated with @QuarkusTest but not with @org.citrusframework.quarkus.CitrusSupport, and when the class has Citrus specific injected fields like @CitrusFramework, @BindToRegistry, etc. then the class must be reported to be annotated as @CitrusSupport too.
• Inspection: report @com.consol.citrus/org.citrusframework.junit.jupiter.CitrusSupport used on a @QuarkusTest annotated test class, instead of @org.citrusframework.quarkus.CitrusSupport.

Settings for `@CitrusTestSource` method generation

Summary

#2 introduced an action to generate @CitrusTestSource test method but its behaviour is not customizable at the moment.

Tasks

• Create plugin settings with the following options
  • Enable/disable the action, so that if a project doesn't use non-Java DSLs, then it doesn't appear for the users.
    • It would be enabled by default.
  • Make the the list of DSLs to be suggested customizable (to have enabled only those ones that are actually used in the project), so that when the action is invoked, unncessary items are not displayed.
    • At least one item must be enabled in the list.
    • If there is only one DSL enabled, there will be no code completion, and the template insertion won't stop at that template variable in order to speed up users' workflows.

Apache Camel support

Plugin settings to toggle Citrus functions and validation matchers annotators

Summary

Citrus functions and validation matchers are currently highlighted in Java String literal, but there is no option to disable them in case users want to disable them.

Tasks

• Add two options in the plugin settings:
  • one to enable/disable the annotator for Citrus functions
  • another one enable/disable the annotator for validation matchers
• The options would be enabled by default.
• Take into consideration the scalability of these options for when the annotators would be available in other file types in the future.

Custom citrus-application.properties files

Summary

Citrus supports defining custom locations for the citrus-application.properties file. Support for custom locations could be added, so that

• code completions,
• inspections,
• language injections,
• and custom project view icons

are available for them.

Tasks

• Add a textfield or table in the Citrus plugin settings UI to be able to add custom Citrus settings file locations.
• The location paths
  • when starting with / (forward slash), would be treated as paths relative to the project root. This would add IDE support for these specific files.
  • when not starting with /, would be treated as file names without their paths. This would add IDE support for all files having the configured names.
• citrus-application.properties would be supported regardless of the presence of any additional paths/file names in the plugin settings.

Resources

• Configuration property file
• CitrusSettings class

Extend function and validation matcher completion to other file types

Summary

Currently function and validation matcher code completion is available only in Java String literals. Since they can be used in many other places, extend the list of them.

This would enable the feature e.g. in separate request and response body files and YAKS feature files.

Tasks

• Create new completion contributors for the following file types and locations

File type	Location
XML	tag value, tag attribute value
JSON	property value, string literal
YAML	property value
Groovy	String literal
Gherkin	step value, data table cell, Examples table cell

Action to generate @CitrusTestSource test method

Generate @CitrusTestSource test method action in the Alt+Insert Generate menu.

Extend citrus-application.properties completion items descriptions

Summary

Citric provides code completion for Citrus properties in citrus-application.properties files, but description is not added for some of the properties when they are displayed as completion items.

Tasks

• Add descriptions for the properties where descrptions are missing.
• Include OSS attributions in the readme.

Resources

• https://citrusframework.org/citrus/reference/4.0.2/html/index.html#configuration

Create file type for .msgs message trace file

Summary

Citrus provides a feature to trace incoming and outgoing messages with its dedicated file extension .msgs.
To prepare for and to support advanced features like language injections, code folding of messages, and potential other stuff, create a dedicated file type for this file extension.

Tasks

• Create a new file type for .msgs files.

Feature ideas for .msgs files

• Code folding of message sections.
• Language injections for response bodies (if can be properly identified).
• Number of messages in a given .msgs file, and maybe other statistics as e.g. Project View node decoration.

Preliminary support for `@CitrusTestFactory` annotation

Tasks

• Add an action into the Alt+Insert Generate menu to be able to generate @CitrusTestFactory annotated Citrus JUnit5 test methods.
• Create inspections for the annotation, if any necessary.
  • Based on https://junit.org/junit5/docs/5.5.1/api/org/junit/jupiter/api/TestFactory.html
    • @CitrusTestFactory methods must not be private or static
    • @CitrusTestFactory methods must have the proper return types
  • @CitrusTestFactory annotated method doesn't need the JUnit @TestFactory annotation.
• Extend existing inspections to handle and take into account this annotation.

Resources

• https://junit.org/junit5/docs/current/user-guide/#writing-tests-dynamic-tests
• https://junit.org/junit5/docs/5.5.1/api/org/junit/jupiter/api/TestFactory.html
• https://www.baeldung.com/junit5-dynamic-tests

Extend the support for properties in `citrus-application.properties`

Summary

There is already some code completion support for citrus-application.properties, but that configuration file has more potential for integration with the IDE.

Tasks

• Code completion for boolean property values
• Implement regex language injection to pattern property values.

Improve Citrus functions and validation matchers annotators

Summary

Although Citric provides annotators to highlight Citrus function and validation matcher expressions, they don't work well for when they are nested in each other.

Tasks

• Investigate how the annotator could be improved for nested cases.
• See how Citrus resolves these expressions to get an idea for the annotators:
  • org.citrusframework.context.TestContext#replaceDynamicContentInString(java.lang.String, boolean)
  • org.citrusframework.variable.VariableUtils
  • org.citrusframework.functions.FunctionUtils
  • org.citrusframework.validation.matcher.ValidationMatcherUtils

SOAP Web services support - Java DSL

Inspections around injected Citrus resources

Summary

There are various types of resources that can be injected by Citrus, like Citrus, TestCaseRunner, endpoints, and others.

In order to identify usage issues earlier, one or more inspections could be useful.

Tasks

• Create one or more inspections with the following checks:
  • A field is annotated with @CitrusFramework but the field type is not Citrus.
    • This prevents injecting the Citrus object into the field.
  • A field is annotated with @CitrusEndpoint but the field type is not Endpoint or one of its inheritors.
    • This prevents injecting an Endpoint object into the field.
  • A field is annotated with one of the @*EndpointConfig annotations but it is not annotated with @CitrusEndpoint.
    • This prevents injecting an Endpoint object into the field, and then be able to override its properties.
  • A field has as type one of the inheritors of Endpoint but the @*EndpointConfig annotation on the field doesn't match the type.
    • E.g. DirectEndpoint field annotated with @CamelEndpointConfig.

Code completion for validation matchers

Summary

In a similar fashion to #14 , validation matchers could also be code completed.

Tasks

• Implement code completion to suggest the list of available Citrus validation matchers.
• The completion would be invoked in string literals where the caret is placed inside two @ symbols.
• For now, it would work only in the Java DSL.

Resources

• Validation matcher

Easy navigation from @CitrusTestSource method to test resource

Summary

@CitrusTestSource annotated methods reference test scripts and test descriptor files in other DSLs. To make the lookup and navigation to those files simpler and quicker, some kind of navigation option should be implemented.

Tasks

• The first option is a line marker, but considering that there can be multiple files and locations specified and in multiple ways, there may need to be a distinction, and separate options to navigate to them separately.
• The sources attribute will support only classpath resource paths, for now.

Combination of options

• File extensions
  • XML, SPRING: .xml
  • YAML: .yaml
  • GROOVY: .groovy

name	packageName	packageScan	sources	Executed
				Java test method name in package of the declaring class.
+				name attribute value + file extension of type in package of the declaring class.
	+			Java test method name in the packageName package.
		+		The Java test method name is ignored. Test names are the ones found in the packageScan package.
			+	The files specified in sources in the packages of files specified in sources
+	+			name attribute value + file extension of type in packageName package.
+		+		name attribute value + file extension of type from the current package, AND all tests in the packageScan package.
+			+	Only the files specified in sources, but a GroovyTestLoader is also created for name which is not executed.
	+	+		Only the files found in packageScan.
+	+	+		name attribute value + file extension of type from the packageName package, AND all tests in the packageScan package.
	+		+	Only the files specified in sources.
+	+		+	Only the files specified in sources, but a GroovyTestLoader is also created for name which is not executed.
		+	+	Files found in packageScan, AND in source.
+		+	+	Only the name attribute value + file extension of type from the current package but GroovyTestLoaders are also created for packageScan and sources that are not executed.
	+	+	+	Only the files specified in packageScan and sources.
+	+	+	+	name attribute value + file extension of type from the packageName package, AND sources, but GroovyTestLoaders are also created for packageScan which are not executed.