Class TestContext

java.lang.Object
cloud.opencode.base.test.TestContext
public final class TestContext extends Object
Test Context - ScopedValue-based Test Execution Context 测试上下文 - 基于 ScopedValue 的测试执行上下文

Uses JDK 25 ScopedValue for efficient context propagation in test execution. Provides thread-safe variable storage, lifecycle hooks, and metadata management.

使用 JDK 25 ScopedValue 实现测试执行中高效的上下文传播。 提供线程安全的变量存储、生命周期钩子和元数据管理。

Features | 主要功能:

  • ScopedValue-based context propagation - 基于ScopedValue的上下文传播
  • Thread-safe variable and attribute storage - 线程安全的变量和属性存储
  • Lifecycle hooks (success/failure callbacks) - 生命周期钩子（成功/失败回调）
  • Test timing and status tracking - 测试计时和状态跟踪

Usage Example | 使用示例:

// Create new test context
TestContext context = TestContext.create("myTestName");

// Register callbacks
context.onSuccess(ctx -> System.out.println("Test passed!"));
context.onFailure((ctx, ex) -> System.out.println("Test failed: " + ex));

// Run test within context
TestContext.run(context, () -> {
    // Access current context
    TestContext current = TestContext.current().orElseThrow();
    current.setVariable("key", "value");
    current.setAttribute("component", "UserService");

    // Perform test assertions...
    return result;
});

Security | 安全性:

  • Thread-safe: Yes (ConcurrentHashMap for variables/attributes, synchronized callbacks) - 线程安全: 是（变量/属性使用ConcurrentHashMap，回调使用synchronized）
  • Null-safe: Yes (validates non-null inputs) - 空值安全: 是（验证非空输入）
Since:
JDK 25, opencode-base-test V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • CURRENT

      public static final ScopedValue<TestContext> CURRENT
      Current test context (ScopedValue) 当前测试上下文 (ScopedValue)

  • Method Details

    • create

      public static TestContext create(String testName)
      Creates a new test context with test name 使用测试名称创建新的测试上下文
      Parameters:
      testName - the test name | 测试名称
      Returns:
      new test context | 新的测试上下文

    • create

      public static TestContext create()
      Creates a new test context with default name 使用默认名称创建新的测试上下文
      Returns:
      new test context | 新的测试上下文

    • run

      public static <T, X extends Throwable> T run(TestContext context, ScopedValue.CallableOp<T,X> task) throws X
      Runs a callable within this context 在此上下文中运行可调用对象
      Type Parameters:
      T - return type | 返回类型
      X - exception type | 异常类型
      Parameters:
      context - the test context | 测试上下文
      task - the task to run | 要运行的任务
      Returns:
      task result | 任务结果
      Throws:
      X - if task throws | 如果任务抛出异常

    • run

      public static void run(TestContext context, Runnable task)
      Runs a runnable within this context 在此上下文中运行可运行对象
      Parameters:
      context - the test context | 测试上下文
      task - the task to run | 要运行的任务

    • current

      public static Optional<TestContext> current()
      Gets the current test context 获取当前测试上下文
      Returns:
      current context or empty | 当前上下文或空

    • currentOrCreate

      public static TestContext currentOrCreate()
      Gets the current context or creates a new one 获取当前上下文或创建新的
      Returns:
      current or new context | 当前或新的上下文

    • currentOrCreate

      public static TestContext currentOrCreate(String testName)
      Gets the current context or creates one with specified name 获取当前上下文或使用指定名称创建新的
      Parameters:
      testName - the test name for new context | 新上下文的测试名称
      Returns:
      current or new context | 当前或新的上下文

    • setVariable

      public TestContext setVariable(String key, Object value)
      Sets a variable in the context 在上下文中设置变量
      Parameters:
      key - the variable key | 变量键
      value - the variable value | 变量值
      Returns:
      this context for chaining | 此上下文用于链式调用

    • getVariable

      public <T> Optional<T> getVariable(String key)
      Gets a variable from the context 从上下文中获取变量
      Type Parameters:
      T - the expected type | 预期类型
      Parameters:
      key - the variable key | 变量键
      Returns:
      the variable value or empty | 变量值或空

    • getVariable

      public <T> T getVariable(String key, T defaultValue)
      Gets a variable with default value 获取变量，带默认值
      Type Parameters:
      T - the expected type | 预期类型
      Parameters:
      key - the variable key | 变量键
      defaultValue - the default value | 默认值
      Returns:
      the variable value or default | 变量值或默认值

    • hasVariable

      public boolean hasVariable(String key)
      Checks if a variable exists 检查变量是否存在
      Parameters:
      key - the variable key | 变量键
      Returns:
      true if variable exists | 如果变量存在返回 true

    • removeVariable

      public TestContext removeVariable(String key)
      Removes a variable from the context 从上下文中移除变量
      Parameters:
      key - the variable key | 变量键
      Returns:
      this context for chaining | 此上下文用于链式调用

    • variables

      public Map<String,Object> variables()
      Gets all variables as unmodifiable map 获取所有变量（不可修改的映射）
      Returns:
      all variables | 所有变量

    • setAttribute

      public TestContext setAttribute(String key, Object value)
      Sets an attribute (metadata) in the context 在上下文中设置属性（元数据）
      Parameters:
      key - the attribute key | 属性键
      value - the attribute value | 属性值
      Returns:
      this context for chaining | 此上下文用于链式调用

    • getAttribute

      public <T> Optional<T> getAttribute(String key)
      Gets an attribute from the context 从上下文中获取属性
      Type Parameters:
      T - the expected type | 预期类型
      Parameters:
      key - the attribute key | 属性键
      Returns:
      the attribute value or empty | 属性值或空

    • getAttribute

      public <T> T getAttribute(String key, T defaultValue)
      Gets an attribute with default value 获取属性，带默认值
      Type Parameters:
      T - the expected type | 预期类型
      Parameters:
      key - the attribute key | 属性键
      defaultValue - the default value | 默认值
      Returns:
      the attribute value or default | 属性值或默认值

    • hasAttribute

      public boolean hasAttribute(String key)
      Checks if an attribute exists 检查属性是否存在
      Parameters:
      key - the attribute key | 属性键
      Returns:
      true if attribute exists | 如果属性存在返回 true

    • attributes

      public Map<String,Object> attributes()
      Gets all attributes as unmodifiable map 获取所有属性（不可修改的映射）
      Returns:
      all attributes | 所有属性

    • onSuccess

      public TestContext onSuccess(Consumer<TestContext> callback)
      Registers a success callback 注册成功回调
      Parameters:
      callback - the callback to invoke on success | 成功时调用的回调
      Returns:
      this context for chaining | 此上下文用于链式调用

    • onFailure

      public TestContext onFailure(TestContext.FailureCallback callback)
      Registers a failure callback 注册失败回调
      Parameters:
      callback - the callback to invoke on failure | 失败时调用的回调
      Returns:
      this context for chaining | 此上下文用于链式调用

    • testName

      public String testName()
      Gets the test name 获取测试名称
      Returns:
      test name | 测试名称

    • startTime

      public Instant startTime()
      Gets the start time 获取开始时间
      Returns:
      start time | 开始时间

    • endTime

      public Optional<Instant> endTime()
      Gets the end time if test has completed 获取结束时间（如果测试已完成）
      Returns:
      end time or empty | 结束时间或空

    • duration

      public Duration duration()
      Gets the test duration 获取测试持续时间
      Returns:
      duration from start to now or end time | 从开始到现在或结束时间的持续时间

    • status

      public String status()
      Gets the test status 获取测试状态
      Returns:
      test status (pending, running, success, failure) | 测试状态

    • isPassed

      public boolean isPassed()
      Checks if test passed 检查测试是否通过
      Returns:
      true if test succeeded | 如果测试成功返回 true

    • isFailed

      public boolean isFailed()
      Checks if test failed 检查测试是否失败
      Returns:
      true if test failed | 如果测试失败返回 true

    • exception

      public Optional<Throwable> exception()
      Gets the failure exception if test failed 获取失败异常（如果测试失败）
      Returns:
      the exception or empty | 异常或空

    • toString

      public String toString()
      Overrides:
      toString in class Object