Add documentation on how to use IInstanceInfo

[krmahadevan]

The TestNG documentation should be enhanced to start capturing details on how to work with org.testng.IInstanceInfo

[krmahadevan]

I spent some time investigating about real-time use-cases that may require one to use this interface and I couldn't come up with any practical use case.
I couldn't find anything in the commit comments as well related to this.

Here's a sample from the unit test in the codebase.

public class FactoryWithInstanceInfoTest {

  @Parameters({"factory-param"})
  @Factory
  public IInstanceInfo[] createObjectsWithInstanceInfo(String param) {
    return new IInstanceInfo[] {
      new InstanceInfo<>(FactoryWithInstanceInfo2Sample.class, new FactoryWithInstanceInfo2Sample(42)),
      new InstanceInfo<>(FactoryWithInstanceInfo2Sample.class, new FactoryWithInstanceInfo2Sample(43)),
    };
  }
}

@cbeust - Can you please shed some light around possible use cases as to when this would be used? I want to include some context around when this would be useful in the real-world scenarios.

@juherr - Do you have any ideas on this interface?

[juherr]

I've just found it was released in 2.4
https://groups.google.com/g/testng-users/c/JBqUNukSyJk

[krmahadevan]

@juherr i was looking some example usecases wherein this can be used so that we can add that in the documentation.

[krmahadevan]

Found this thread https://groups.google.com/g/testng-users/c/X8G4kai8B9A/m/uSHNsRwEDUsJ that has a sample which looks like below

public class BeanRunnerFactory {
    @Factory
    public IInstanceInfo[] createObjectsWithInstanceInfo() {
        IInstanceInfo[] instances = null;
        try {
            Properties properties = new Properties();
            properties.put("java.naming.factory.initial", "org.jnp.interfaces.NamingContextFactory");
            properties.put("java.naming.factory.url.pkgs", "=org.jboss.naming:org.jnp.interfaces");
            properties.put("java.naming.provider.url", "localhost:1099");
            InitialContext ctx = new InitialContext(properties);
            // InitialContext ctx = new InitialContext();

            // List the test classes to be executed
            Class[] testClasses = new Class[] {
                ServiceProviderTestLocal.class,
                    StationTestLocal.class,
                    RouteTestLocal.class
            };

            int i = testClasses.length;
            instances = new IInstanceInfo[i];

            while (i-- != 0) {
                Class clazz = testClasses[i];
                String className = clazz.getName();
                className = className.substring(className.lastIndexOf('.') + 1)
                    .replaceAll("Local", "/local");
                Object test = ctx.lookup(className);
                instances[i] = new BeanInstanceInfo(test, clazz);
            }
        } catch (Exception e) {
            System.err.println("Error connecting to remote tests: " + e.getMessage());
        }
        return instances;
    }
}

Still not much context around where this will be used.

@juherr - Does this above sample give you any idea ?

[juherr]

As I understand it, IInstanceInfo is the typed way to write a factory method.

@Factory
public Object[] createObjectsWithInstanceInfo()

is just a syntactic sugar and it is translated into IInstanceInfo automatically by the engine.

Maybe to documentation, factory section, should be updated to that way.

[juherr]

Additional notes:
In the provided sample, the test class is defined locally but the instance is called by a RPC.
In that specific context, I suppose instance.getClass() won't provided the expected class with expected annotation because it involves java Proxy.