Skip to content

wttech/aem-stubs

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

WTT logo

GitHub tag (latest SemVer) GitHub All Releases Java CI with Gradle Apache License, Version 2.0, January 2004

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!

Screenshot

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

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:

Topic \ Framework WireMock Moco Comments
Installation All-in-one AEM package All-in-one AEM package Both distributions could be easily deployed via single package installation in CRX Package Manager.
HTTP server AEM built-in (Jetty) Separate running also on AEM at dedicated port (Netty) As of Moco is not using AEM HTTP Server but running its own (faster, asynchronous), it is required to ensure that port
used by Moco is free and not blocked by firewall on some deployment servers.
As of WireMock is running on same server as AEM, all mocked paths need to be prefixed (by default with stubs/).
When using Moco prefixes are not needed as of it is a dedicated HTTP server with mocks only.
Popularity Big - 3.9k stars on GitHub Big - 3.1k stars on GitHub WireMock is a little bit more popular and has probably better documentation and more materials available on the web.
API Rich, old-fashioned Rich, modern Moco API seems to be written with extendability in mind. Has many interfaces, builders etc available. WireMock API has less such extension points and generally does not look so elegant.

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

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:

  • all - both frameworks with Groovy OSGi bundle included,
  • app - both frameworks without Groovy OSGi bundle included.
  • 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

AEM Stubs AEM Java
1.0.0, 1.0.1 6.4, 6.5 8
>= 1.0.2 6.3, 6.4, 6.5 8
2.0.0 6.3, 6.4, 6.5 11
2.0.1 6.3, 6.4, 6.5 8, 11

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.

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:

Framework-specific stub script API

See also framework-specific stub script API:

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

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")