Add a FreePort extension

[krzyk]

This is quite similar to TempDirectory.

There are frequently tests that depend on network layer that need to use a port that is not already used by any other service (either to start a server on it, or to test a failure scenario where there is no service at given port).

Proposed usage:

@Test
@ExtendWith(FreePort.class)
void test(@FreePrt int port) {
    // do something with the `port`
}

[marcphilipp]

How do you guarantee the port stays free between the time you've checked it and the test actually using it? Usually you can pass 0 to servers to assign a randomly allocated port and then query the port that's been allocated after they're started. This approach doesn't have the race condition problem. Do you have use cases where this approach wouldn't work?

[krzyk]

Yes, race condition is problematic, but in some cases it can't be avoided, and the proposition is still better than hardcoding port number.

1. I have a test that needs to have nothing listening at the port (to test the application behavior for invalid host+port).
2. Some Java libraries allow passing a 0 as a port, but don't have a way to retrieve the assigned port back, so I need to pass a known free port there (yes, with possibility that it will be taken).

As for 2, I don't recall the names, because I had those problems some time ago, but as for 1, I needed to create such extension to be able to test failure conditions. So maybe someone else would find it useful also.

[sbrannen]

How do you guarantee the port stays free between the time you've checked it and the test actually using it?

You of course cannot guarantee that the port remains free, but there are use cases for it.

For example, Spring has SocketUtils exactly for such use cases.

[nipafx]

I think this is an interesting idea, but I don't have enough experience with testing port-reliant code to add anything to the discussion except a few (possibly naive) ideas. Here's one:

Would it make sense to design the extension so that the strategy to find a free port can be plugged in? That way, a Spring app (to use a random example) can use Spring's facilities to discover free ports and other apps use other mechanism. Or users could ask for random port scan or for a linear port scan in a certain range, ...

What do you think, @krzyk?

[Bukama]

I would guess that for such things testcontainers are the right thing to use as they handle the port things out of the box?

[krzyk]

@Bukama Running docker just for a single test (or even for the whole suit) is a overkill in majority of projects.

[nipafx]

I think this idea is sound enough to give it a go. One more idea, maybe don't pas the port as an int, but as an instance of a class (Free)Port. This removes the need for a @FreePort annotation on the argument and allows for a richer API if it's ever needed, e.g. checking whether a specific port is free at the moment.

[nipafx]

If anybody wants to work on this, let me know and I will mark it as in progress.

[nipafx]

As a first iteration, please pass an instance of the to-be-created class Port.

[Bukama]

PR opend by @p1729

[nipafx]

Blocked until #348/#491 is resolved as ports may turn out to be good resources.

[nipafx]

I'm gonna remove this from the the 2.0 milestone, so we can progress on that.