Integrations

Integrating Concordion with other tools

This page shows the integrations for Java. Click the toggle buttons above to choose other options.

IDEs

IntelliJ IDEA

The excellent Concordion support plugin for IDEA provides support such as autocompletion, 2-way navigation between specifications and fixtures, run test from specification, surround with Concordion command, go to declaration and renaming. See the home page for documentation of the features and keyboard shortcuts.

This plugin supports both HTML and Markdown format specifications.

For Markdown format specifications, a Markdown plugin is also required. The official IntelliJ IDEA Markdown Support plugin is recommended. The Markdown Navigator plugin is also supported.

Star

Eclipse

The concordion-eclipse plugin provides content assist and validation for Concordion specifications, integrated into Eclipse’s HTML and Web Page (Source) editors.

This plugin currently supports HTML format specifications (not Markdown). It has not been updated with the Concordion 2.0 commands yet, so will show these as errors, but still works well.


Build tools

Gradle

Concordion tests can be run using the standard test task. A typical build script is:

apply plugin: 'java'

repositories {
  mavenCentral()
}

dependencies {
  testImplementation "org.concordion:concordion:x.y.z"
  testRuntimeOnly('org.junit.vintage:junit-vintage-engine')  // <-- Only needed if using concordion:run with a JUnit 4 fixture
}

test {
  testLogging.showStandardStreams = true   // display test output on console
  systemProperties['concordion.output.dir'] = "$reporting.baseDir/spec"  // write output to build/reports/spec
  outputs.upToDateWhen { false }   // force tests to run even if code hasn't changed
}

where x.y.z is replaced by the Concordion version, for example 2.0.0.

Note: Prior to Gradle 3.4, use testCompile rather than testImplementation.

If you have created a suite of specifications using the run command, you may want to run only your main fixture class by adding this line inside the test block:

  include '**/MainFixture.*' 

where MainFixture.java is the fixture class corresponding to the main index page.

(This is not strictly necessary since Concordion will cache test results so that tests are not run multiple times within a single test run. The number of tests reported will be less if you only run the main fixture class.)

Gradle Bug

The gradle command line option “–tests” does not currently work correctly with Concordion and will:

  • prevent @AfterSuite annotated methods from running
  • construct all test classes (but not run them)

Until this is corrected either use the older command line option “-DtaskName.single = testNamePattern” or use includes as shown above.

Maven

Concordion tests can be run using the surefire plugin. For example:

<build>
  <plugins>
    ......
    <plugin>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>2.19.1</version>
      <configuration>
        <systemPropertyVariables>
          <concordion.output.dir>target/concordion</concordion.output.dir>
        </systemPropertyVariables>
      </configuration>
    </plugin>
    ......
  </plugins>
</build>

Note that the Surefire plugin, by default, only includes test classes with filenames that start or end with Test or end with TestCase. If your Concordion fixture class names don’t end with Test or you want to limit the fixture classes that are run, you will need to specify the fixtures you want to include. For example:

  <includes>
    <include>**/MainFixture.java</include>
  </includes>

If using the concordion:run command with a JUnit 4 fixture, you will also need to add:

    <dependency>
        <groupId>org.junit.vintage</groupId>
        <artifactId>junit-vintage-engine</artifactId>
        <version>5.9.3</version>
        <scope>test</scope>
    </dependency>

There is also a maven-concordion-reporting-plugin which allows you to incorporate Concordion reports into a Maven site report in the project reports section.

Command Line

Should you wish to run your tests from the command line, you will need to:

  1. Download and unzip the full distribution.
  2. From the unzipped folder, copy the lib folder to be located alongside your source code, and copy concordion-<x.y.z>.jar files to this lib folder (where <x.y.z> is the version number of Concordion).
  3. Compile your Java source code (adding the lib folder to your classpath)
  4. Run Concordion as a JUnit test, for example:

    java -cp lib/*:bin org.junit.runner.JUnitCore path/to/my/fixture.class


Build servers

Jenkins

The HTML Publisher plugin can publish the Concordion results, maintain a per-build history, and let you download the output as a zip file.

Note: as of Jenkins 1.641 / 1.625.3, Jenkins enforces a Content Security Policy which results in Concordion reports no longer being fully functional in Jenkins by default. The policy defaults to sandbox; default-src 'none'; img-src 'self'; style-src 'self'; which forbids inline CSS and does not allow JavaScript. Concordion reports use inline CSS and Javascript.

We are looking to resolve this with issue 151. In the meantime, the only workaround is to restore the security vulnerability. Before doing so, check the considerations for relaxing the rules. If safe to do so in your context, relax the policy to allow script-src 'unsafe-inline' and style-src 'unsafe-inline' by appending

-Dhudson.model.DirectoryBrowserSupport.CSP=\"default-src 'none'; img-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'unsafe-inline';\"

to the value of the JAVA_ARGS variable in the Jenkins startup script (/etc/default/jenkins on Linux) and restarting Jenkins.

NOTE: Jul 2017, removed sandbox; from the start of the CSP setting since it was causing issues with displaying screenshots, similar to Jenkins issue 33653.


Frameworks

Spring

The chiiknrice/concordion-spring-runner provides integration between Concordion and Spring Framework.