@wordpress/env 11.0.2-next.v.202602241322.0 → 11.1.0

package/lib/test/port-utils.js

@@ -0,0 +1,136 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const net = require( 'net' );
+
+/**
+ * Internal dependencies
+ */
+const {
+	isPortAvailable,
+	findAvailablePort,
+	DEFAULT_MIN_PORT,
+	DEFAULT_MAX_PORT,
+} = require( '../port-utils' );
+
+jest.mock( 'net' );
+
+describe( 'port-utils', () => {
+	afterEach( () => {
+		jest.restoreAllMocks();
+	} );
+
+	/**
+	 * Helper that configures net.createServer to return fresh mock servers.
+	 * Takes a function that receives the port and returns true if available.
+	 *
+	 * @param {Function} isAvailable A function (port) => boolean.
+	 */
+	function mockPortAvailability( isAvailable ) {
+		net.createServer.mockImplementation( () => {
+			let errorCb, listenCb;
+
+			const server = {
+				once: jest.fn( ( event, cb ) => {
+					if ( event === 'error' ) {
+						errorCb = cb;
+					}
+					if ( event === 'listening' ) {
+						listenCb = cb;
+					}
+				} ),
+				listen: jest.fn( ( port ) => {
+					if ( isAvailable( port ) ) {
+						server.close.mockImplementation( ( cb ) => cb() );
+						listenCb();
+					} else {
+						errorCb( { code: 'EADDRINUSE' } );
+					}
+				} ),
+				close: jest.fn(),
+			};
+
+			return server;
+		} );
+	}
+
+	describe( 'isPortAvailable', () => {
+		it( 'returns true for an available port', async () => {
+			mockPortAvailability( () => true );
+			const result = await isPortAvailable( 8888 );
+			expect( result ).toBe( true );
+		} );
+
+		it( 'returns false for a port in use', async () => {
+			mockPortAvailability( () => false );
+			const result = await isPortAvailable( 8888 );
+			expect( result ).toBe( false );
+		} );
+
+		it( 'returns false for EACCES error', async () => {
+			net.createServer.mockImplementation( () => {
+				let errorCb;
+				const server = {
+					once: jest.fn( ( event, cb ) => {
+						if ( event === 'error' ) {
+							errorCb = cb;
+						}
+					} ),
+					listen: jest.fn( () => {
+						errorCb( { code: 'EACCES' } );
+					} ),
+					close: jest.fn(),
+				};
+				return server;
+			} );
+			const result = await isPortAvailable( 80 );
+			expect( result ).toBe( false );
+		} );
+	} );
+
+	describe( 'findAvailablePort', () => {
+		it( 'returns the preferred port when available', async () => {
+			mockPortAvailability( () => true );
+			const result = await findAvailablePort( {
+				preferredPort: 8888,
+			} );
+			expect( result ).toBe( 8888 );
+		} );
+
+		it( 'finds an alternative when preferred port is busy', async () => {
+			mockPortAvailability( ( port ) => port !== 8888 );
+			const result = await findAvailablePort( {
+				preferredPort: 8888,
+			} );
+			expect( result ).toBe( 8889 );
+		} );
+
+		it( 'excludes specified ports', async () => {
+			mockPortAvailability( () => true );
+			const result = await findAvailablePort( {
+				preferredPort: 8888,
+				exclude: [ 8888 ],
+			} );
+			expect( result ).toBe( 8889 );
+		} );
+
+		it( 'returns a port higher than the preferred port when fallback is needed', async () => {
+			mockPortAvailability( ( port ) => port !== 8888 && port !== 8889 );
+			const result = await findAvailablePort( {
+				preferredPort: 8888,
+			} );
+			expect( result ).toBeGreaterThan( 8888 );
+			expect( result ).toBeLessThanOrEqual( DEFAULT_MAX_PORT );
+		} );
+
+		it( 'supports overriding fallback range', async () => {
+			mockPortAvailability( ( port ) => port === DEFAULT_MIN_PORT + 1 );
+			const result = await findAvailablePort( {
+				preferredPort: 8888,
+				minPort: DEFAULT_MIN_PORT,
+			} );
+			expect( result ).toBe( DEFAULT_MIN_PORT + 1 );
+		} );
+	} );
+} );

package/lib/test/resolve-available-ports.js

@@ -0,0 +1,155 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const {
+	createPortResolver,
+	resolveConfigPorts,
+} = require( '../resolve-available-ports' );
+const { findAvailablePort, isPortAvailable } = require( '../port-utils' );
+
+jest.mock( '../port-utils' );
+
+describe( 'resolve-available-ports', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	describe( 'createPortResolver', () => {
+		it( 'should resolve a port in non-strict mode', async () => {
+			findAvailablePort.mockResolvedValue( 8888 );
+
+			const resolver = createPortResolver();
+			const port = await resolver.resolve( 8888, 'env.development.port' );
+
+			expect( port ).toBe( 8888 );
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 8888 } )
+			);
+		} );
+
+		it( 'should fail in strict mode when port is busy', async () => {
+			isPortAvailable.mockResolvedValue( false );
+
+			const resolver = createPortResolver();
+
+			await expect(
+				resolver.resolve( 9000, 'env.development.port', true )
+			).rejects.toThrow( /Port 9000.*is busy/ );
+		} );
+
+		it( 'should succeed in strict mode when port is available', async () => {
+			isPortAvailable.mockResolvedValue( true );
+
+			const resolver = createPortResolver();
+			const port = await resolver.resolve(
+				9000,
+				'env.development.port',
+				true
+			);
+
+			expect( port ).toBe( 9000 );
+		} );
+
+		it( 'should fail in strict mode when port conflicts with another service', async () => {
+			isPortAvailable.mockResolvedValue( true );
+			findAvailablePort.mockResolvedValue( 8888 );
+
+			const resolver = createPortResolver();
+			// First call consumes port 8888.
+			await resolver.resolve( 8888, 'env.development.port' );
+
+			await expect(
+				resolver.resolve( 8888, 'env.tests.port', true )
+			).rejects.toThrow( /conflicts with another wp-env service/ );
+		} );
+	} );
+
+	describe( 'resolveConfigPorts', () => {
+		it( 'should resolve null ports using preferred defaults', async () => {
+			findAvailablePort.mockResolvedValue( 8888 );
+
+			const resolver = createPortResolver();
+			const config = {
+				env: {
+					development: { port: null },
+					tests: { port: null },
+				},
+			};
+
+			await resolveConfigPorts( config, resolver );
+
+			// Null ports should be resolved using preferred ports.
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 8888 } )
+			);
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 8889 } )
+			);
+		} );
+
+		it( 'should resolve explicit ports with auto-fallback', async () => {
+			findAvailablePort.mockImplementation( ( { preferredPort } ) =>
+				Promise.resolve( preferredPort )
+			);
+
+			const resolver = createPortResolver();
+			const config = {
+				env: {
+					development: { port: 9000 },
+					tests: { port: 9001 },
+				},
+			};
+
+			await resolveConfigPorts( config, resolver );
+
+			expect( config.env.development.port ).toBe( 9000 );
+			expect( config.env.tests.port ).toBe( 9001 );
+			// Auto-port always uses findAvailablePort (non-strict).
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 9000 } )
+			);
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 9001 } )
+			);
+		} );
+
+		it( 'should resolve explicit phpmyadminPort with auto-fallback', async () => {
+			findAvailablePort.mockResolvedValue( 49152 );
+
+			const resolver = createPortResolver();
+			const config = {
+				env: {
+					development: { port: null, phpmyadminPort: 9000 },
+					tests: { port: null },
+				},
+			};
+
+			await resolveConfigPorts( config, resolver );
+
+			// phpmyadminPort should use findAvailablePort (non-strict),
+			// not isPortAvailable (strict), even with an explicit value.
+			expect( findAvailablePort ).toHaveBeenCalledWith(
+				expect.objectContaining( { preferredPort: 9000 } )
+			);
+			expect( isPortAvailable ).not.toHaveBeenCalledWith( 9000 );
+		} );
+
+		it( 'should skip undefined ports', async () => {
+			const resolver = createPortResolver();
+			const config = {
+				env: {
+					development: { port: null },
+					tests: { port: null },
+				},
+			};
+
+			findAvailablePort.mockResolvedValue( 8888 );
+			await resolveConfigPorts( config, resolver );
+
+			// phpmyadminPort is undefined so should not trigger any resolution.
+			expect( config.env.development.phpmyadminPort ).toBeUndefined();
+			expect( config.env.tests.phpmyadminPort ).toBeUndefined();
+		} );
+	} );
+} );

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/env",
-	"version": "11.0.2-next.v.202602241322.0+bce7cff88",
+	"version": "11.1.0",
 	"description": "A zero-config, self contained local WordPress environment for development and testing.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -63,5 +63,5 @@
 	"scripts": {
 		"test": "echo \"Error: run tests from root\" && exit 1"
 	},
-	"gitHead": "943dde7f0b600ce238726c36284bc9f70ce0ffa4"
+	"gitHead": "8bfc179b9aed74c0a6dd6e8edf7a49e40e4f87cc"
 }