Understanding Concordion Architecture
Fixtures, Specifications, and Extensions
Each Concordion test ties a fixture (Java class) to an HTML specification file. Concordion scans annotated methods in the fixture and binds them to elements marked in the HTML using concordion:execute, concordion:assertEquals, etc. Extensions enhance behavior (e.g., logging, screenshots) via the Concordion extension API.
Test Execution Stack
Concordion tests run via JUnit or Maven Surefire Plugin. Tests can be executed in IDEs, via command-line builds, or CI/CD systems. Output is generated as a rendered HTML report with pass/fail markers and execution metadata.
Common Concordion Issues
1. HTML Specification Not Recognized
Occurs when the HTML file isn't named or located according to Concordion's conventions. Results in SpecificationNotFoundException or blank output pages.
2. Fixture and Specification Mismatch
When method names or argument signatures in the fixture don’t match the expressions used in the HTML, assertions silently fail or return null. This leads to undetected test errors.
3. IDE Integration Failures
Some IDEs fail to launch Concordion tests correctly if required annotations or dependencies are missing. In IntelliJ or Eclipse, JUnit runners may throw NoClassDefFoundError or Test class not found.
4. JUnit and Maven Build Failures
Common when Concordion is not correctly wired into the Maven build lifecycle. Errors include java.lang.NoSuchMethodError or test classes not being discovered during mvn test.
5. Assertion Failures Not Rendered
When rendered output doesn’t display failures correctly, it's often due to outdated HTML, incompatible themes, or missing Concordion stylesheet assets.
Diagnostics and Debugging Techniques
Validate HTML Specification Path
Ensure the HTML file is located in the same package structure as the fixture class and named ClassName.html. Paths must match Java classpaths exactly.
Enable Concordion Logging
Use a logging framework (e.g., Logback, SLF4J) and add log statements to the fixture. Also consider using the Concordion Logging Extension to trace bindings and assertions.
Run Tests in Verbose Mode
Pass -X to Maven for detailed stack traces. Use mvn -Dtest=FullyQualifiedTestClass test to isolate test cases.
Inspect Rendered Output
Open the generated HTML report and use browser dev tools to inspect failed assertion classes. Missing CSS or JavaScript can hinder correct rendering of result highlights.
Use the Concordion Extension Hooks
Register listeners (e.g., ConcordionExtension) to intercept before/after commands. Helps in debugging when tests silently skip or mis-execute commands.
Step-by-Step Resolution Guide
1. Fix Specification Recognition Errors
Confirm that MyFixture.java maps to MyFixture.html in the same package path. If using custom spec resolvers, ensure they're properly registered via ConcordionOptions.
2. Align Fixture Methods and HTML Directives
Ensure all concordion:execute and assertEquals directives match fixture method names exactly. Parameter counts and return types must align with the HTML usage.
3. Resolve IDE Test Execution Problems
Ensure that the Concordion JAR is in the classpath. Add JUnit 4 or 5 dependencies explicitly. Rebuild project indices and configure run configurations to use proper runners.
4. Correct Maven Build Integration
Add concordion as a dependency in the test scope. Verify that the Surefire plugin uses the correct JUnit version. Clean and rebuild with mvn clean test.
5. Restore Report Rendering
Ensure your report HTML has the correct concordion.css linked. If using custom templates, validate class attributes for assertion results. Revert to standard templates to isolate layout issues.
Best Practices for Concordion Stability
- Keep fixture logic minimal—offload complex behavior to helper classes.
- Use consistent naming conventions for fixtures and specifications.
- Pin Concordion and JUnit versions to avoid compatibility drift.
- Integrate Concordion reports into CI dashboards using HTML publishers.
- Leverage extensions like Screenshot or Logging for enhanced traceability.
Conclusion
Concordion enables living documentation and expressive test scenarios, but its declarative approach demands tight coordination between HTML specs, Java fixtures, and execution environments. With structured diagnostics—such as verifying paths, enabling logs, and isolating integration issues—teams can resolve test binding problems, rendering glitches, and CI inconsistencies. A disciplined testing strategy built on clear fixture-spec alignment ensures scalable use of Concordion in enterprise-grade software projects.
FAQs
1. Why does Concordion say my specification is missing?
The HTML file must reside in the same package path as the fixture class and follow the ClassName.html naming convention.
2. How do I debug assertion mismatches?
Enable detailed logging and inspect the rendered output. Ensure parameter names and fixture methods match the directives used in the HTML.
3. Why are my tests not discovered in Maven?
Ensure the fixture class has a public @Test method or uses a recognized JUnit runner. Verify that Concordion is in the test scope of the POM file.
4. Can I run Concordion tests with JUnit 5?
Yes, with the concordion-junit5 extension. Ensure JUnit 5 is configured correctly in your POM and test runner setup.
5. My HTML output isn’t showing failed tests—why?
Missing styles or corrupted templates can prevent proper rendering. Restore the default concordion.css or inspect using browser developer tools.