DOCSEARCHbyAlgolia
Submit Docs

stubby4j Documentation

repository·master·Indexed 18 days ago

https://github.com/azagniotov/stubby4j

A flexible stub server for HTTP/1.1, HTTP/2, and WebSockets used for contract testing in microservices and SOA architectures. It supports fault injection, request proxying, record/replay, and advanced regex matching for URIs, headers, and payloads. stubby4j can be deployed as a standalone JAR or via Docker and Docker Compose, with support for multiple JRE versions (8, 11, 16, 17, 21) and architectures including amd64 and arm64.

Tokens
5.8K
Snippets
10
Records
19
Agent score
62%

What's inside stubby4j

  1. Overview of stubby4j

    master

    stubby4j is a highly flexible and configurable stub server designed for testing interactions in service-oriented (SoA) or micro-services architectures. It allows developers and QA engineers to stub out external web services for contract testing in both Dockerized and non-containerized environments.

    Supported Protocols:

    • HTTP/1.1
    • HTTP/2 (supports both h2c over TCP and h2 over TLS using ALPN)
    • WebSockets (over HTTP/1.1, with or without TLS)

    Key Capabilities:

    • Protocol Support: TLS versions 1.0, 1.1, 1.2, and 1.3.
    • Advanced Matching: Regex support for URIs, query parameters, headers, and POST payloads; dynamic token replacement using regex capturing groups.
    • Flow Control: Fault injection (e.g., returning a bad response after X successful ones), dynamic flows (multiple responses for the same URI), and delayed responses for performance testing.
    • Proxying & Recording: Request proxying to other services and Record & Replay functionality.
    • Content Handling: Serving binary files (images, PDFs, etc.) and verifying HTTP 30x redirects and various Authorization types (Basic, Bearer Token, etc.).

  2. Manage stubs via the Admin REST API

    master
    Once the stubby4j container is running, an Admin portal is accessible at localhost:<ADMIN_PORT> (or the address/port configured via environment variables). The Admin portal exposes a set of REST APIs that allow you to manage the in-memory stubs that were loaded from the YAML configuration during startup.

  3. Setup stubby4j

    master

    stubby4j can be deployed in several ways depending on your environment:

    1. Standalone JAR: Run stubby4j as a standard Java application.
    2. Docker Container: Use pre-built Docker images (including ARM64 support) to run stubby4j in containerized micro-service architectures.
    3. Docker Compose: Orchestrate stubby4j alongside other services using Docker Compose.

    For specific system requirements and detailed installation steps for each method, refer to the official documentation at https://stubby4j.com.

  4. Run stubby4j using Docker Compose

    master

    You can integrate stubby4j into your service stack using a Docker Compose file. You must map a host directory containing your YAML configuration file to the container volume /home/stubby4j/data.

    Available image tags include latest-jre8, latest-jre11, and latest-jre15.

    version: '3.8'
services:
  stubby4j:
    image: azagniotov/stubby4j:latest-jre8
    volumes:
      - "<HOST_MACHINE_DIR_WITH_YAML_CONFIG_TO_MAP_VOLUME_TO>:/home/stubby4j/data"
    container_name: stubby4j
    ports:
      - 8882:8882
      - 8889:8889
      - 7443:7443
    environment:
      YAML_CONFIG: main.yaml
      STUBS_PORT: 8882
      ADMIN_PORT: 8889
      STUBS_TLS_PORT: 7443
      WITH_ARGS: "--enable_tls_with_alpn_and_http_2 --debug --watch"

  5. Start a basic stubby4j Docker instance

    master

    To start a basic stubby4j instance, run the Docker container with a volume mapping for your YAML configuration. You must map your host directory containing the config to /home/stubby4j/data inside the container.

    By default, the container runs as UID/GID 1001 (user stubby4j) for security.

    This command:

    1. Sets YAML_CONFIG to stubs.yaml.
    2. Maps the host directory to /home/stubby4j/data.
    3. Exposes ports 8882 (stubs), 8889 (admin), and 7443 (stubs SSL) to the host.
    $ docker run --rm \
    --env YAML_CONFIG=stubs.yaml \
    --volume <HOST_MACHINE_DIR_WITH_YAML_CONFIG_TO_MAP_VOLUME_TO>:/home/stubby4j/data \
    -p 8882:8882 -p 8889:8889 -p 7443:7443 \
    azagniotov/stubby4j:<TAG>

  6. How Stubby4j matches incoming requests to stubs

    master

    Stubby4j uses a multi-stage matching process to determine if an incoming HTTP request satisfies a configured stub. A request matches a stub only if all of the following criteria are met:

    1. URL/URI Match: The request URI must match the stubbed URI. This supports exact string matching or regular expressions.
    2. HTTP Method Match: If the stub specifies HTTP methods (e.g., GET, POST), the incoming request's method must intersect with the stubbed list.
    3. Headers Match: All headers defined in the stub must be present in the incoming request with matching values. Note: Authorization headers are handled separately by the StubRepository and are excluded from this specific matching phase.
    4. Query Parameters Match: All query parameters defined in the stub must be present in the incoming request's query string.
    5. Request Body Match: If the stub specifies a request body (for POST, PUT, or PATCH requests), the bodies must match. The matching logic depends on the Content-Type header:
      • JSON: Uses JSONCompare in NON_EXTENSIBLE mode. If structural comparison fails, it falls back to regex/string matching.
      • XML: Uses XMLUnit for structural comparison, supporting whitespace normalization, comment ignoring, and custom regex placeholders (e.g., ${xmlunit.matchesRegex(...)}).
      • Plain Text/Other: Falls back to regex or exact string matching.

    If any stage fails, Stubby4j logs an error indicating which field caused the mismatch (e.g., [URL] Failed to match on stubbed...).

  7. Understand the Stubby4j Web UI behavior

    master

    The Stubby4j web interface uses AJAX to provide interactive views of server statistics and resources without full page reloads.

    Key interactive behaviors include:

    • Statistics Visualization: Clicking on .ajax-stats links fetches CSV data and renders an interactive bar chart using D3.js. This chart can be sorted by hits or resource ID.
    • Resource Inspection: Clicking on .ajax-resource links fetches resource details and displays them in a popup window, with code highlighting applied via hljs.
    • Dynamic UI Updates: The UI periodically checks /ajax/stats/check to detect if requests have been made, automatically enabling 'view' links when data becomes available.
    • Interactive Popups: Popups are draggable (via #popup-drag-handle or #popup-title) and resizable (via #popup-resize-handle). They can be closed using the 'X' button, the 'Close' button, clicking the overlay, or pressing the ESC key.

  8. Regex stubbing for XML content

    master

    When stubbing XML requests, Stubby4j supports advanced matching using XMLUnit combined with regex placeholders. This allows you to perform structural XML comparisons while using regular expressions for specific elements or attributes that might contain dynamic data.

    For more details on the syntax of these placeholders, refer to the project documentation on regex stubbing for XML content.

  9. Run stubby4j via CLI

    master

    Stubby4j can be executed as a standalone application using its command-line interface. The application parses arguments to configure the server, load YAML stub definitions, and manage logging/console output.

    Key behaviors:

    • Configuration: You must provide a YAML configuration file using the --config option (referenced by CommandLineInterpreter.OPTION_CONFIG).
    • Default Behavior: If no YAML file is provided via the command line, stubby4j will attempt to create a temporary empty.yaml file using a default internal configuration (/yaml/empty-stub.yaml).
    • Help and Version: Use the standard help and version flags to display information about available options or the current version.
    • Termination: The server can be stopped using ctrl-c.
    # Example conceptual usage (actual flags depend on CommandLineInterpreter implementation)
java -jar stubby4j.jar --config my-stubs.yaml

  10. View resource statistics and charts in the UI

    master

    The Stubby4j UI provides a visual way to monitor request hits per resource. When you click a statistics link (elements with the .ajax-stats class), the following happens:

    1. A loading indicator is shown in the table cell.
    2. Data is fetched from the server via an AJAX GET request.
    3. A D3.js bar chart is rendered in a popup window.
    4. The chart displays hits on the Y-axis and resourceId on the X-axis.
    5. You can sort the chart by clicking the #sort-values-box checkbox, which toggles between sorting by hits (descending) and resource ID (ascending).

  11. Inspect specific resources via AJAX

    master

    To view the details of a specific stubbed resource, click the link associated with the .ajax-resource class.

    This triggers an AJAX request to the resource's URL. Upon success, the content is displayed in a popup window, and any code blocks within the response (specifically code#ajax-response) are automatically highlighted using hljs (Highlight.js).

  12. Start a full stubby4j Docker instance with custom arguments

    master

    For advanced configurations, use the WITH_ARGS environment variable to pass command-line switches. Note that the WITH_ARGS value must be enclosed in quotes.

    Commonly used flags via WITH_ARGS:

    • --enable_tls_with_alpn_and_http_2: Enables HTTP/2 over TCP (h2c) and HTTP/2 over TLS (h2) on TLS v1.2 or newer using ALPN extension.
    • --disable_stub_caching: Disables in-memory caching of matched stubs.
    • --debug: Dumps raw incoming HTTP requests to the console.
    • --watch: Periodically scans for changes in YAML configs and referenced files (every 100ms) and reloads them if changed.
    docker run --rm \
    --env YAML_CONFIG=stubs.yaml \
    --env STUBS_PORT=9991 \
    --env ADMIN_PORT=8889 \
    --env STUBS_TLS_PORT=8443 \
    --env WITH_ARGS="--enable_tls_with_alpn_and_http_2 --disable_stub_caching --debug --watch" \
    --volume /Users/zaggy/docker-playground/yaml:/home/stubby4j/data \
    -p 9991:9991 -p 8889:8889 -p 8443:8443 \
    azagniotov/stubby4j:7.5.2-jre8