wttech / aem-stubs

Tool for providing sample data for AEM applications in a simple and flexible way.

By providing JSON mapping file or implementing a Groovy script using WireMock or Moco framework be able to mock your 3rd party services within minutes without a need to set up separate mock servers (infrastructure).

Simply install ready-to-use CRX package on AEM instance and start stubbing!

AdaptTo 2020 Live Demo - https://adapt.to/2020/en/schedule/lightning-talks/aem-stubs.html

Main concepts of AEM Stubs tool are:

• Simplicity
  • Creating stubs should be as much simple as it is possible,
  • Reusing widely-known and battle-tested stubbing technology (avoiding reinventing a wheel),
• Reactivity
  • Trivial tool deployment - installable on AEM via all-in-one CRX package in the time when stubs are actually needed,
  • Trivial stubs deployment - reloading stubs tied to regular AEM application deployment.

Table of contents

• Frameworks
• Installation
  • Post installation steps
• Compatibility
• Documentation
  • Basics
  • OSGi configuration
  • Stub script API
    • Pre-defined variables
    • Framework-specific stub script API
• Other tools
• Contributing
• Building
• License

Frameworks

At first, it is needed to decide which stubbing framework is more preferred to use.

Both frameworks have their own pros and cons, see comparison:

After choosing stubbing framework, it is recommended to explore dedicated AEM Stubs framework related documentation:

• AEM Stubs - WireMock
• AEM Stubs - Moco

However, keep in mind using both frameworks on AEM is also supported. It may be useful when some features are missing in one framework, but they are available in another one.

Installation

Simply install ready to use AEM package downloaded from GitHub releases section.

Distribution types:

• wiremock-all - WireMock framework only with Groovy OSGi bundle included,
• wiremock-app - WireMock framework only without Groovy OSGi bundle included.
• moco-all - Moco framework only with Groovy OSGi bundle included,
• moco-app - Moco framework only without Groovy OSGi bundle included.

Post installation steps

Remember that using AEM Stubs on AEM Publish instances may require an additional configuration.

In case of WireMock, ensure that WireMock Servlet prefix /stubs is not filtered by AEM Dispatcher configuration. Alternatively, by creating OSGi configuration, update that path prefix to path which is already accessible.

When using Moco, ensure that Moco Stubs Server (running by default on port 5555) is not blocked by firewall. Alternatively, by creating OSGi configuration, update that port number to port which is already accessible.

Compatibility

Note that AEM Stubs is using Groovy scripts concept. However it is not using AEM Groovy Console. It is done intentionally, because Groovy Console has close dependencies to concrete AEM version. AEM Stubs tool is implemented in a AEM version agnostic way, to make it more universal and more fault-tolerant when AEM version is changing. It is compatible with AEM Groovy Console - simply install one of AEM Stubs distributions without Groovy console OSGi bundle included as it is usually provided by Groovy Console AEM package.

From AEM Stubs 3.x onwards, Groovy has been upgraded to version 4.x. Groovy has stopped providing a groovy-all 'uber' bundle. In this package, only the groovy 'core' bundle is included. It is possible to add extra Groovy modules in your own project. A list of groovy subprojects can be found here at the Groovy GitHub Project

Documentation

Basics

Stubs could be provided by:

• JSON mapping files (*.stub.json) so called stub mappings e.g file named my-feature.stub.json,
• Groovy Scripts (*.stub.groovy) so called stub scripts e.g file named my-feature.stub.groovy.

Format of contents of these files depends on chosen framework.

For example, when decided to choose WireMock framework, then these files should be put into AEM under path /conf/stubs/wiremock/* via CRX package with corresponding Vault workspace filter:

<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
    <filter root="/apps/example"/>
    <filter root="/conf/stubs/wiremock/example"/>
</workspaceFilter>

Stub mappings or scripts could be organized into folders tree. Any other assets used by scripts like images, extra JSON files could be also freely put close to stub scripts or mappings. Indeed, dedicated extensions *.stub.json and *.stub.groovy are introduced to distinguish these assets from automatically loaded scripts and mappings.

Note that mappings and scripts under path /conf/stubs/wiremock/samples will not be considered as of they are excluded by default configuration of Stub Manager OSGi service. Which means to use samples, it is needed to remove path exclusion, rename a folder or copy sample files to other folder.

OSGi configuration

There are framework specific OSGi configurations (WireMock, Moco) and common listed below:

Stub Manager

Stub script API

Pre-defined variables:

• stubs - use it to control actual Stubs server (WireMock or Moco),
• resourceResolver - for accessing AEM repository,
• repository - for easier using repository e.g reading file contents,
• logger - SLF4j logger connected to script being run.

Framework-specific stub script API

See also framework-specific stub script API:

• Wiremock
• Moco.

Other tools

There are no other dedicated tools for stubbing data available for AEM and it was main purpose to create AEM Stubs tool.

Authors

• Krystian Panek - Project Founder, Main Developer,
• Piotr Marcinkowski - Main Developer.

Contributing

Issues reported or pull requests created will be very appreciated.

1. Fork plugin source code using a dedicated GitHub button.
2. Do code changes on a feature branch created from develop branch.
3. Create a pull request with a base of develop branch.

Building

Project build is based on Gradle and using Gradle AEM Plugin.

To setup AEM instance, provide details required by running command:

sh gradlew props

Fill opened GUI dialog, then click execute button.

To build CRX package and deploy it on AEM instance, simply run command:

sh gradlew

That's it.

License

AEM Stubs is licensed under the Apache License, Version 2.0 (the "License")