@@ -137,10 +137,160 @@ describe("background preview lifecycle", () => {
137137 } ) ;
138138
139139 expect ( result ) . toMatchObject ( { type : "reused" , port : 41402 , pid : 4321 } ) ;
140- expect ( scan ) . toHaveBeenCalledWith ( 41402 ) ;
140+ expect ( scan ) . toHaveBeenCalledExactlyOnceWith ( 41402 ) ;
141141 expect ( spawn ) . not . toHaveBeenCalled ( ) ;
142142 } ) ;
143143
144+ it . each ( [ 3021 , 32521 , 32522 , 32620 , 32621 ] ) (
145+ "bounds the explicit-port scan when the saved port is %s" ,
146+ async ( savedPort ) => {
147+ const stateHome = tempDir ( "hf-preview-state-" ) ;
148+ const requestedPort = 32521 ;
149+ const owned = { ...server , port : savedPort } ;
150+ const requested = { ...server , port : requestedPort , pid : "5555" } ;
151+ const servers = savedPort === requestedPort ? [ requested ] : [ owned , requested ] ;
152+ writePreviewSession (
153+ { pid : 4321 , port : savedPort , projectDir, logPath : "/tmp/preview.log" } ,
154+ stateHome ,
155+ ) ;
156+ const scan = vi . fn ( async ( start = 3002 ) =>
157+ servers . filter ( ( candidate ) => candidate . port >= start && candidate . port < start + 100 ) ,
158+ ) ;
159+ const probe = vi . fn (
160+ async ( port : number ) => servers . find ( ( candidate ) => candidate . port === port ) ?? null ,
161+ ) ;
162+ const spawn = vi . fn ( ) ;
163+ const kill = vi . fn ( ) ;
164+
165+ const result = await startBackgroundPreview ( projectDir , requestedPort , {
166+ scan,
167+ probe,
168+ spawn,
169+ kill,
170+ stateHome,
171+ preferredPort : requestedPort ,
172+ } ) ;
173+
174+ expect ( result ) . toMatchObject ( { type : "reused" , port : requestedPort , pid : 5555 } ) ;
175+ expect ( scan ) . toHaveBeenCalledExactlyOnceWith ( requestedPort ) ;
176+ expect ( probe . mock . calls ) . toEqual (
177+ savedPort < requestedPort || savedPort > 32620 ? [ [ savedPort ] ] : [ ] ,
178+ ) ;
179+ expect ( spawn ) . not . toHaveBeenCalled ( ) ;
180+ expect ( kill ) . not . toHaveBeenCalled ( ) ;
181+ } ,
182+ ) ;
183+
184+ it . each ( [ true , false ] ) (
185+ "bounds the explicit-port replacement scan through shutdown (force-new: %s)" ,
186+ async ( forceNew ) => {
187+ const stateHome = tempDir ( "hf-preview-state-" ) ;
188+ const owned = { ...server , port : 3021 , browserGpuMode : "hardware" as const } ;
189+ const replacement = {
190+ ...server ,
191+ port : 32521 ,
192+ pid : "5432" ,
193+ browserGpuMode : "software" as const ,
194+ } ;
195+ const sibling = { ...replacement , port : 32522 , pid : "8765" } ;
196+ writePreviewSession (
197+ { pid : 4321 , port : owned . port , projectDir, logPath : "/tmp/preview.log" } ,
198+ stateHome ,
199+ ) ;
200+ let ownedRunning = true ;
201+ let replacementRunning = false ;
202+ let stopping = false ;
203+ const scan = vi . fn ( async ( start = 3002 ) =>
204+ [
205+ sibling ,
206+ ...( ownedRunning ? [ owned ] : [ ] ) ,
207+ ...( replacementRunning ? [ replacement ] : [ ] ) ,
208+ ] . filter ( ( candidate ) => candidate . port >= start && candidate . port < start + 100 ) ,
209+ ) ;
210+ const probe = vi . fn ( async ( port : number ) =>
211+ ownedRunning && port === owned . port ? owned : null ,
212+ ) ;
213+ const kill = vi . fn ( ( pid : number ) => {
214+ expect ( pid ) . toBe ( 4321 ) ;
215+ stopping = true ;
216+ } ) ;
217+ const sleep = vi . fn ( async ( ) => {
218+ if ( stopping ) ownedRunning = false ;
219+ } ) ;
220+ const spawn = vi . fn ( ( ) => {
221+ expect ( ownedRunning ) . toBe ( false ) ;
222+ replacementRunning = true ;
223+ return { pid : 5432 , unref : vi . fn ( ) } ;
224+ } ) ;
225+
226+ const result = await startBackgroundPreview ( projectDir , replacement . port , {
227+ browserGpuMode : "software" ,
228+ forceNew,
229+ preferredPort : replacement . port ,
230+ kill,
231+ probe,
232+ scan,
233+ sleep,
234+ spawn,
235+ stateHome,
236+ } ) ;
237+
238+ expect ( result ) . toMatchObject ( { type : "started" , port : replacement . port , pid : 5432 } ) ;
239+ expect ( scan . mock . calls . length ) . toBeGreaterThan ( 1 ) ;
240+ expect ( scan . mock . calls . every ( ( [ port ] ) => port === replacement . port ) ) . toBe ( true ) ;
241+ expect ( probe . mock . calls . length ) . toBeGreaterThanOrEqual ( 4 ) ;
242+ expect ( probe . mock . calls . every ( ( [ port ] ) => port === owned . port ) ) . toBe ( true ) ;
243+ expect ( kill ) . toHaveBeenCalledExactlyOnceWith ( 4321 ) ;
244+ expect ( sleep ) . toHaveBeenCalledOnce ( ) ;
245+ expect ( spawn ) . toHaveBeenCalledOnce ( ) ;
246+ expect (
247+ JSON . parse ( readFileSync ( previewSessionPath ( projectDir , stateHome ) , "utf8" ) ) ,
248+ ) . toMatchObject ( {
249+ port : replacement . port ,
250+ pid : 5432 ,
251+ } ) ;
252+ } ,
253+ ) ;
254+
255+ it ( "keeps explicit-port replacement blocked while the saved listener is still running" , async ( ) => {
256+ const stateHome = tempDir ( "hf-preview-state-" ) ;
257+ const owned = { ...server , port : 3021 } ;
258+ writePreviewSession (
259+ { pid : 4321 , port : owned . port , projectDir, logPath : "/tmp/preview.log" } ,
260+ stateHome ,
261+ ) ;
262+ const scan = vi . fn ( async ( start = 3002 ) =>
263+ owned . port >= start && owned . port < start + 100 ? [ owned ] : [ ] ,
264+ ) ;
265+ const probe = vi . fn ( async ( port : number ) => ( port === owned . port ? owned : null ) ) ;
266+ const spawn = vi . fn ( ) ;
267+ const kill = vi . fn ( ) ;
268+
269+ await expect (
270+ startBackgroundPreview ( projectDir , 32521 , {
271+ forceNew : true ,
272+ preferredPort : 32521 ,
273+ scan,
274+ probe,
275+ spawn,
276+ kill,
277+ sleep : async ( ) => { } ,
278+ stateHome,
279+ } ) ,
280+ ) . rejects . toThrow ( "background preview did not stop" ) ;
281+
282+ expect ( scan . mock . calls . every ( ( [ port ] ) => port === 32521 ) ) . toBe ( true ) ;
283+ expect ( probe . mock . calls . every ( ( [ port ] ) => port === owned . port ) ) . toBe ( true ) ;
284+ expect ( kill ) . toHaveBeenCalledExactlyOnceWith ( 4321 ) ;
285+ expect ( spawn ) . not . toHaveBeenCalled ( ) ;
286+ expect (
287+ JSON . parse ( readFileSync ( previewSessionPath ( projectDir , stateHome ) , "utf8" ) ) ,
288+ ) . toMatchObject ( {
289+ port : owned . port ,
290+ pid : 4321 ,
291+ } ) ;
292+ } ) ;
293+
144294 it ( "throws a port-mismatch error when the caller explicitly requests a port the reused server isn't on" , async ( ) => {
145295 const spawn = vi . fn ( ) ;
146296 const scan = vi . fn ( async ( ) => [ server ] ) ;
@@ -586,9 +736,10 @@ describe("background preview lifecycle", () => {
586736 const spawn = vi . fn ( ) ;
587737 const kill = vi . fn ( ) ;
588738
589- const result = await startBackgroundPreview ( projectDir , 3002 , {
739+ const result = await startBackgroundPreview ( projectDir , sibling . port , {
590740 kill,
591- scan : async ( ) => [ owned , sibling ] ,
741+ scan : async ( ) => [ sibling ] ,
742+ probe : async ( port ) => ( port === owned . port ? owned : null ) ,
592743 spawn,
593744 stateHome,
594745 preferredPort : sibling . port ,
@@ -602,10 +753,10 @@ describe("background preview lifecycle", () => {
602753 it ( "lists every same-project server in the port-mismatch error, not just the reuse candidate" , async ( ) => {
603754 const stateHome = mkdtempSync ( join ( tmpdir ( ) , "hf-preview-state-" ) ) ;
604755 const owned = { ...server , port : 3002 } ;
605- const sibling = { ...server , port : 3003 , pid : "5555" } ;
756+ const sibling = { ...server , port : 3004 , pid : "5555" } ;
606757 const foreign = {
607758 ...server ,
608- port : 3004 ,
759+ port : 3003 ,
609760 projectDir : resolve ( "/tmp/hyperframes-preview-lifecycle-other" ) ,
610761 pid : "7777" ,
611762 } ;
@@ -615,18 +766,19 @@ describe("background preview lifecycle", () => {
615766 ) ;
616767 const spawn = vi . fn ( ) ;
617768
618- const failure = await startBackgroundPreview ( projectDir , 3002 , {
619- scan : async ( ) => [ owned , sibling , foreign ] ,
769+ const failure = await startBackgroundPreview ( projectDir , foreign . port , {
770+ scan : async ( ) => [ sibling , foreign ] ,
771+ probe : async ( port ) => ( port === owned . port ? owned : null ) ,
620772 spawn,
621773 stateHome,
622- preferredPort : 3004 ,
774+ preferredPort : foreign . port ,
623775 } ) . then (
624776 ( ) => null ,
625777 ( error : unknown ) => error ,
626778 ) ;
627779
628780 expect ( failure ) . toBeInstanceOf ( PreviewServerPortMismatchError ) ;
629- expect ( failure ) . toMatchObject ( { requestedPort : 3004 , ports : [ 3002 , 3003 ] } ) ;
781+ expect ( failure ) . toMatchObject ( { requestedPort : 3003 , ports : [ 3002 , 3004 ] } ) ;
630782 expect ( ( failure as Error ) . message ) . toContain ( "add --force-new or run --stop first" ) ;
631783 expect ( spawn ) . not . toHaveBeenCalled ( ) ;
632784 } ) ;
@@ -640,18 +792,18 @@ describe("background preview lifecycle", () => {
640792 stateHome ,
641793 ) ;
642794 const spawn = vi . fn ( ) ;
643- const probe = vi . fn ( async ( port : number ) => ( port === farSibling . port ? farSibling : null ) ) ;
795+ const probe = vi . fn ( async ( port : number ) => ( port === owned . port ? owned : null ) ) ;
644796
645797 const result = await startBackgroundPreview ( projectDir , farSibling . port , {
646- scan : async ( ) => [ owned ] ,
798+ scan : async ( ) => [ farSibling ] ,
647799 probe,
648800 spawn,
649801 stateHome,
650802 preferredPort : farSibling . port ,
651803 } ) ;
652804
653805 expect ( result ) . toMatchObject ( { type : "reused" , port : farSibling . port , pid : 5555 } ) ;
654- expect ( probe ) . toHaveBeenCalledExactlyOnceWith ( farSibling . port ) ;
806+ expect ( probe ) . toHaveBeenCalledExactlyOnceWith ( owned . port ) ;
655807 expect ( spawn ) . not . toHaveBeenCalled ( ) ;
656808 } ) ;
657809
@@ -863,7 +1015,7 @@ describe("background preview lifecycle", () => {
8631015 } ) ;
8641016
8651017 expect ( status ?. port ) . toBe ( 3210 ) ;
866- expect ( scan ) . toHaveBeenCalledWith ( 3210 ) ;
1018+ expect ( scan ) . toHaveBeenCalledExactlyOnceWith ( 3210 ) ;
8671019 } ) ;
8681020
8691021 it ( "stops only the matching project server and waits until it is unreachable" , async ( ) => {
0 commit comments