ConfNG Documentation

1. Welcome to ConfNG

ConfNG is a configuration management library designed specifically for Java applications with first-class TestNG integration. It provides a flexible, type-safe way to manage configuration across multiple sources with automatic precedence handling.

Key features include:

  • Zero-configuration TestNG integration - TestNG parameters automatically injected via service loader
  • Type-safe configuration - Enum-based keys with compile-time checking
  • Multiple configuration sources - Environment variables, system properties, files (Properties, JSON, YAML, TOML), secret managers, and custom sources
  • Smart precedence - Configurable source priority with sensible defaults
  • Extensible architecture - Easy to add custom configuration sources
  • Secret management - Built-in support for AWS, Azure, and HashiCorp Vault
  • Thread-safe - Safe for concurrent access
  • Lightweight - Minimal dependencies

Here is a very simple example:

package com.example;

import org.confng.ConfNG;
import org.confng.ConfNGKey;
import org.testng.annotations.*;

public enum AppConfig implements ConfNGKey {
    BASE_URL("base.url", "http://localhost:8080"),
    TIMEOUT("timeout", "30"),
    BROWSER("browser", "chrome");

    private final String key;
    private final String defaultValue;

    AppConfig(String key, String defaultValue) {
        this.key = key;
        this.defaultValue = defaultValue;
    }

    @Override
    public String getKey() { return key; }

    @Override
    public String getDefaultValue() { return defaultValue; }
}

public class SimpleTest {

    @BeforeClass
    public void setUp() {
        // TestNG parameters automatically available!
        // No configuration needed
    }

    @Test
    public void testApplication() {
        String url = ConfNG.get(AppConfig.BASE_URL);
        Integer timeout = ConfNG.getInt(AppConfig.TIMEOUT);
        String browser = ConfNG.get(AppConfig.BROWSER);

        System.out.println("Testing " + url + " with " + browser);
    }
}

The enum AppConfig defines your configuration keys with default values. TestNG parameters are automatically injected when tests run - no setup required!

1.1. Requirements

ConfNG requires Java 11 or higher.

1.2. Mailing-lists

For questions, support, or discussions, please contact us at team@confng.org.

1.3. Locations of the projects

1.4. Bug reports

Bug reports and feature requests can be submitted on the GitHub Issues page.

1.5. License

ConfNG is released under the Apache License 2.0.

2. Download

ConfNG is available through Maven Central. Add it to your project using Maven or Gradle:

2.1. Maven

<dependency>
    <groupId>org.confng</groupId>
    <artifactId>confng</artifactId>
    <version>1.0.2</version>
</dependency>

2.2. Gradle

dependencies {
    implementation 'org.confng:confng:1.0.2'
}

2.3. Build from source

To build ConfNG from source:

git clone https://github.com/confng/confng.git
cd confng
./gradlew build

3. ConfNG Documentation

3.1. Introduction

ConfNG simplifies configuration management in Java applications, especially for TestNG-based test automation. It eliminates boilerplate code and provides a unified API for accessing configuration from multiple sources.

3.2. Quick Start

Getting started with ConfNG is simple:

  1. Add the dependency to your project
  2. Create an enum implementing ConfNGKey
  3. Use ConfNG.get() to access configuration values
  4. Run your tests - TestNG parameters are automatically available!

3.3. Configuration Keys

Configuration keys in ConfNG are defined using enums that implement the ConfNGKey interface. This provides type-safety and compile-time checking.

public enum MyConfig implements ConfNGKey {
    API_URL("api.url", "https://api.example.com"),
    TIMEOUT("timeout", "30"),
    RETRY_COUNT("retry.count", "3");

    private final String key;
    private final String defaultValue;

    MyConfig(String key, String defaultValue) {
        this.key = key;
        this.defaultValue = defaultValue;
    }

    @Override
    public String getKey() { return key; }

    @Override
    public String getDefaultValue() { return defaultValue; }
}

Access configuration values using the ConfNG class:

// Get as String
String url = ConfNG.get(MyConfig.API_URL);

// Get as Integer
Integer timeout = ConfNG.getInt(MyConfig.TIMEOUT);

// Get as Boolean
Boolean enabled = ConfNG.getBoolean(MyConfig.FEATURE_ENABLED);

// Get as Long
Long count = ConfNG.getLong(MyConfig.MAX_RECORDS);

3.4. Configuration Sources

ConfNG supports multiple configuration sources with automatic precedence handling. Sources are checked in the following order (highest to lowest priority):

  1. Environment Variables - System environment variables
  2. System Properties - Java system properties (-D flags)
  3. TestNG Parameters - Parameters from TestNG XML (Method > Test > Suite levels)
  4. Properties Files - .properties files
  5. JSON Files - .json configuration files
  6. YAML Files - .yaml/.yml files (requires custom source)
  7. TOML Files - .toml files (requires custom source)
  8. Secret Managers - AWS Secrets Manager, Azure Key Vault, HashiCorp Vault
  9. Custom Sources - Implement your own configuration source
  10. Default Values - Values defined in the enum

Example of loading from a properties file:

# config.properties
api.url=https://production.example.com
timeout=60
retry.count=5

Example of loading from a JSON file:

{
  "api": {
    "url": "https://production.example.com",
    "timeout": 60
  },
  "retry": {
    "count": 5
  }
}

3.5. TestNG Integration

ConfNG provides zero-configuration TestNG integration through a service-loaded listener. TestNG parameters are automatically captured and made available through the ConfNG API.

Example TestNG XML:

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Test Suite" verbose="1">
    <parameter name="base.url" value="https://test.example.com"/>
    <parameter name="browser" value="firefox"/>

    <test name="Smoke Tests">
        <parameter name="timeout" value="45"/>
        <classes>
            <class name="com.example.SmokeTest"/>
        </classes>
    </test>
</suite>

Access these parameters in your test:

public class SmokeTest {

    @Test
    public void testApplication() {
        // No @Parameters annotation needed!
        String url = ConfNG.get(AppConfig.BASE_URL);
        String browser = ConfNG.get(AppConfig.BROWSER);
        Integer timeout = ConfNG.getInt(AppConfig.TIMEOUT);

        // Use the configuration...
    }
}

The TestNG listener is automatically registered via Java's ServiceLoader mechanism. No manual configuration is required!

4. Examples

The ConfNG Playground repository contains comprehensive examples demonstrating various features and use cases:

Basic Examples

Advanced Examples

TestNG Integration Examples

5. API Documentation

For detailed API documentation and additional resources:

6. GitHub Repository

ConfNG is open source and hosted on GitHub:

Contributions, bug reports, and feature requests are welcome!