@elisra-devops/docgen-data-provider 1.137.1 → 1.139.0

package/src/modules/TicketsDataProvider.ts

@@ -6,6 +6,8 @@ import { QueryType } from '../models/tfs-data';
 import { QueryAllTypes } from '../models/tfs-data';
 import { Column } from '../models/tfs-data';
 import { value } from '../models/tfs-data';
+import { TestSteps } from '../models/tfs-data';
+import TestStepParserHelper from '../utils/testStepParserHelper';
 
 import logger from '../utils/logger';
 const pLimit = require('p-limit');
@@ -61,7 +63,7 @@ type HistoricalSnapshotResult = {
 
 const HISTORICAL_WIT_API_VERSIONS: Array<string | null> = ['7.1', '5.1', null];
 const HISTORICAL_BATCH_MAX_IDS = 200;
-const HISTORICAL_WORK_ITEM_FIELDS = [
+const HISTORICAL_REQUIRED_WORK_ITEM_FIELDS = [
   'System.Id',
   'System.WorkItemType',
   'System.Title',
@@ -72,8 +74,19 @@ const HISTORICAL_WORK_ITEM_FIELDS = [
   'System.ChangedDate',
   'System.Description',
   'Microsoft.VSTS.TCM.Steps',
-  'Elisra.TestPhase',
-  'Custom.TestPhase',
+];
+// Process-template-specific: not every project defines either of these.
+// workitemsbatch's `fields` filter validates every requested reference name
+// against the project's schema and throws TF51535 ("Cannot find field ...")
+// if one is missing — unlike an unfiltered per-item GET, which just omits an
+// unknown field from the response. toHistoricalWorkItemSnapshot already
+// reads TestPhase via a 4-way fallback expecting it might be absent, so it's
+// safe to drop these on a TF51535 and retry without them (see
+// fetchHistoricalWorkItemsBatch).
+const HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS = ['Elisra.TestPhase', 'Custom.TestPhase'];
+const HISTORICAL_WORK_ITEM_FIELDS = [
+  ...HISTORICAL_REQUIRED_WORK_ITEM_FIELDS,
+  ...HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS,
 ];
 
 /** Default fields fetched per work item in tree/flat query parsing. */
@@ -85,6 +98,9 @@ export default class TicketsDataProvider {
   token: string = '';
   queriesList: Array<any> = new Array<any>();
   private limit = pLimit(10);
+  // Set once a workitemsbatch call reports one of HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS
+  // as unknown for this project, so only the first chunk pays the retry cost.
+  private historicalFieldsOverride: string[] | null = null;
 
   constructor(orgUrl: string, token: string) {
     this.orgUrl = orgUrl;
@@ -1772,6 +1788,58 @@ export default class TicketsDataProvider {
     return String(value).trim();
   }
 
+  /**
+   * Stores rich-text fields (Description, Steps) with only whitespace trimmed, preserving markup
+   * so the report renderer can clean/render it faithfully. Equality between two snapshots must go
+   * through canonicalizeHistoricalRichTextForCompare instead of comparing this value directly.
+   */
+  private rawHistoricalRichText(value: unknown): string {
+    if (value == null) {
+      return '';
+    }
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return this.normalizeHistoricalCompareValue(value);
+  }
+
+  /**
+   * Canonicalizes a rich-text field for equality comparison only. Intentionally identical to the
+   * whitespace collapse previously applied at storage time, so Changed/No-changes verdicts and
+   * summary counts are unaffected by storing the raw value for rendering.
+   */
+  private canonicalizeHistoricalRichTextForCompare(value: unknown): string {
+    return this.normalizeHistoricalCompareValue(value);
+  }
+
+  /**
+   * Parses baseline/compareTo Steps XML into per-step Action/Expected arrays for a changed test
+   * case, so the report can render readable steps instead of raw Steps XML. Best-effort: a parse
+   * failure (malformed XML, shared-step lookup error) must not fail the whole comparison, so it
+   * logs and falls back to leaving the caller with only the raw XML strings.
+   */
+  private async parseHistoricalStepsForDiff(
+    testStepParserHelper: TestStepParserHelper,
+    baselineStepsXml: string,
+    compareToStepsXml: string,
+  ): Promise<{ baselineSteps: TestSteps[]; compareToSteps: TestSteps[] } | null> {
+    try {
+      const emptyRevisionMap = new Map<number, number>();
+      const [baselineSteps, compareToSteps] = await Promise.all([
+        baselineStepsXml
+          ? testStepParserHelper.parseTestSteps(baselineStepsXml, emptyRevisionMap)
+          : Promise.resolve([]),
+        compareToStepsXml
+          ? testStepParserHelper.parseTestSteps(compareToStepsXml, emptyRevisionMap)
+          : Promise.resolve([]),
+      ]);
+      return { baselineSteps, compareToSteps };
+    } catch (err: any) {
+      logger.warn(`Failed to parse historical Steps XML for diff rendering: ${err?.message || err}`);
+      return null;
+    }
+  }
+
   private normalizeTestPhaseValue(value: unknown): string {
     const rendered = this.normalizeHistoricalCompareValue(value);
     if (!rendered) {
@@ -1969,6 +2037,90 @@ export default class TicketsDataProvider {
     return status === 404 || status === 410;
   }
 
+  private isHistoricalUnknownFieldError(error: any): boolean {
+    const message = this.historicalErrorMessage(error);
+    return /TF51535|Cannot find field/i.test(message);
+  }
+
+  // ADO's TF51535 names the specific field it couldn't find, e.g.
+  // "TF51535: Cannot find field 'Elisra.TestPhase'." — different networks
+  // define this optional field under different reference names (Elisra.* vs
+  // Custom.*), so drop only the one ADO actually rejected rather than every
+  // optional field, or a network that defines Custom.TestPhase but not
+  // Elisra.TestPhase would lose Test Phase comparison entirely for no reason.
+  private extractHistoricalUnknownFieldName(error: any): string | null {
+    const message = this.historicalErrorMessage(error);
+    const quoted = message.match(/Cannot find field\s*'([^']+)'/i);
+    if (quoted?.[1]) return quoted[1];
+    return HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.find((field) => message.includes(field)) || null;
+  }
+
+  private fetchHistoricalFieldsBatchAttempt(
+    workItemsBatchUrl: string,
+    idChunk: number[],
+    asOf: string,
+    fieldsForRequest: string[],
+    attemptsRemaining: number,
+  ): Promise<any> {
+    return this.limit(() =>
+      TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
+        ids: idChunk,
+        asOf,
+        fields: fieldsForRequest,
+        errorPolicy: 'Omit',
+      }),
+    ).catch((error: any) => {
+      if (attemptsRemaining <= 0 || !this.isHistoricalUnknownFieldError(error)) {
+        throw error;
+      }
+      const unknownField = this.extractHistoricalUnknownFieldName(error);
+      // Only strip fields this call actually recognizes as droppable
+      // (named explicitly, or one of the known optional fields as a
+      // last-resort fallback if the message doesn't parse) — never strip a
+      // required field, so an unrelated schema issue still surfaces as an
+      // error instead of silently losing data.
+      const reducedFields = unknownField
+        ? fieldsForRequest.filter((field) => field !== unknownField)
+        : fieldsForRequest.filter((field) => !HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.includes(field));
+      if (reducedFields.length === fieldsForRequest.length) {
+        throw error;
+      }
+      // Concurrent chunks can each discover a different bad field before any
+      // of them updates the shared override — intersect rather than
+      // overwrite, so one chunk's retry never re-requests a field another
+      // chunk already proved invalid for this project.
+      this.historicalFieldsOverride = this.historicalFieldsOverride
+        ? this.historicalFieldsOverride.filter((field) => reducedFields.includes(field))
+        : reducedFields;
+      logger.warn(
+        `[historical-workitems] field${unknownField ? ` '${unknownField}'` : '(s)'} not defined ` +
+          `for this project; retrying workitemsbatch without it: ${this.historicalErrorMessage(error)}`,
+      );
+      return this.fetchHistoricalFieldsBatchAttempt(
+        workItemsBatchUrl,
+        idChunk,
+        asOf,
+        reducedFields,
+        attemptsRemaining - 1,
+      );
+    });
+  }
+
+  private fetchHistoricalFieldsBatch(
+    workItemsBatchUrl: string,
+    idChunk: number[],
+    asOf: string,
+  ): Promise<any> {
+    const fieldsForRequest = this.historicalFieldsOverride || HISTORICAL_WORK_ITEM_FIELDS;
+    return this.fetchHistoricalFieldsBatchAttempt(
+      workItemsBatchUrl,
+      idChunk,
+      asOf,
+      fieldsForRequest,
+      HISTORICAL_OPTIONAL_WORK_ITEM_FIELDS.length,
+    );
+  }
+
   private async fetchHistoricalWorkItemsBatch(
     project: string,
     ids: number[],
@@ -1995,14 +2147,7 @@ export default class TicketsDataProvider {
           // two units against the shared concurrency cap, not one — otherwise
           // the real ceiling on simultaneous ADO calls would silently double.
           Promise.all([
-            this.limit(() =>
-              TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
-                ids: idChunk,
-                asOf,
-                fields: HISTORICAL_WORK_ITEM_FIELDS,
-                errorPolicy: 'Omit',
-              }),
-            ),
+            this.fetchHistoricalFieldsBatch(workItemsBatchUrl, idChunk, asOf),
             this.limit(() =>
               TFSServices.getItemContent(workItemsBatchUrl, this.token, 'post', {
                 ids: idChunk,
@@ -2175,8 +2320,8 @@ export default class TicketsDataProvider {
       iterationPath: this.normalizeHistoricalCompareValue(fields['System.IterationPath']),
       versionId: this.toHistoricalRevision(workItem?.rev ?? fields['System.Rev']),
       versionTimestamp: this.normalizeHistoricalCompareValue(fields['System.ChangedDate']),
-      description: this.normalizeHistoricalCompareValue(fields['System.Description']),
-      steps: this.normalizeHistoricalCompareValue(fields['Microsoft.VSTS.TCM.Steps']),
+      description: this.rawHistoricalRichText(fields['System.Description']),
+      steps: this.rawHistoricalRichText(fields['Microsoft.VSTS.TCM.Steps']),
       testPhase: this.normalizeTestPhaseValue(testPhaseRaw),
       relatedLinkCount,
       workItemUrl: `${this.orgUrl}${project}/_workitems/edit/${id}`,
@@ -2357,8 +2502,9 @@ export default class TicketsDataProvider {
       ...Array.from(compareTo.snapshotMap.keys()),
     ]);
     const sortedIds = Array.from(allIds.values()).sort((a, b) => a - b);
+    const testStepParserHelper = new TestStepParserHelper(this.orgUrl, this.token);
 
-    const rows = sortedIds.map((id) => {
+    const rows = await Promise.all(sortedIds.map(async (id) => {
       const baselineRow = baseline.snapshotMap.get(id) || null;
       const compareToRow = compareTo.snapshotMap.get(id) || null;
       const workItemType = compareToRow?.workItemType || baselineRow?.workItemType || '';
@@ -2396,7 +2542,15 @@ export default class TicketsDataProvider {
       const safeCompareTo = compareToRow as HistoricalWorkItemSnapshot;
       const changedFields: string[] = [];
 
-      if (safeBaseline.description !== safeCompareTo.description) {
+      const descriptionChanged =
+        this.canonicalizeHistoricalRichTextForCompare(safeBaseline.description) !==
+        this.canonicalizeHistoricalRichTextForCompare(safeCompareTo.description);
+      const stepsChanged =
+        isTestCase &&
+        this.canonicalizeHistoricalRichTextForCompare(safeBaseline.steps) !==
+          this.canonicalizeHistoricalRichTextForCompare(safeCompareTo.steps);
+
+      if (descriptionChanged) {
         changedFields.push('Description');
       }
       if (safeBaseline.title !== safeCompareTo.title) {
@@ -2405,7 +2559,7 @@ export default class TicketsDataProvider {
       if (safeBaseline.state !== safeCompareTo.state) {
         changedFields.push('State');
       }
-      if (isTestCase && safeBaseline.steps !== safeCompareTo.steps) {
+      if (stepsChanged) {
         changedFields.push('Steps');
       }
       if (safeBaseline.testPhase !== safeCompareTo.testPhase) {
@@ -2415,28 +2569,41 @@ export default class TicketsDataProvider {
         changedFields.push('Related Link Count');
       }
 
-      const differences = changedFields.map((field) => {
-        switch (field) {
-          case 'Description':
-            return { field, baseline: safeBaseline.description, compareTo: safeCompareTo.description };
-          case 'Title':
-            return { field, baseline: safeBaseline.title, compareTo: safeCompareTo.title };
-          case 'State':
-            return { field, baseline: safeBaseline.state, compareTo: safeCompareTo.state };
-          case 'Steps':
-            return { field, baseline: safeBaseline.steps, compareTo: safeCompareTo.steps };
-          case 'Test Phase':
-            return { field, baseline: safeBaseline.testPhase, compareTo: safeCompareTo.testPhase };
-          case 'Related Link Count':
-            return {
-              field,
-              baseline: String(safeBaseline.relatedLinkCount),
-              compareTo: String(safeCompareTo.relatedLinkCount),
-            };
-          default:
-            return { field, baseline: '', compareTo: '' };
-        }
-      });
+      const differences = await Promise.all(
+        changedFields.map(async (field) => {
+          switch (field) {
+            case 'Description':
+              return { field, baseline: safeBaseline.description, compareTo: safeCompareTo.description };
+            case 'Title':
+              return { field, baseline: safeBaseline.title, compareTo: safeCompareTo.title };
+            case 'State':
+              return { field, baseline: safeBaseline.state, compareTo: safeCompareTo.state };
+            case 'Steps': {
+              const parsed = await this.parseHistoricalStepsForDiff(
+                testStepParserHelper,
+                safeBaseline.steps,
+                safeCompareTo.steps,
+              );
+              return {
+                field,
+                baseline: safeBaseline.steps,
+                compareTo: safeCompareTo.steps,
+                ...(parsed || {}),
+              };
+            }
+            case 'Test Phase':
+              return { field, baseline: safeBaseline.testPhase, compareTo: safeCompareTo.testPhase };
+            case 'Related Link Count':
+              return {
+                field,
+                baseline: String(safeBaseline.relatedLinkCount),
+                compareTo: String(safeCompareTo.relatedLinkCount),
+              };
+            default:
+              return { field, baseline: '', compareTo: '' };
+          }
+        }),
+      );
 
       return {
         id,
@@ -2449,7 +2616,7 @@ export default class TicketsDataProvider {
         differences,
         workItemUrl: safeCompareTo.workItemUrl || safeBaseline.workItemUrl,
       };
-    });
+    }));
 
     const summary = rows.reduce(
       (acc, row) => {

package/src/tests/modules/ticketsDataProvider.historical.test.ts

@@ -946,6 +946,173 @@ describe('TicketsDataProvider historical queries', () => {
     expect(diff).toEqual({ field: 'Related Link Count', baseline: '1', compareTo: '2' });
   });
 
+  it('CompareHistoricalQueryResults preserves raw markup for rendering while comparing on canonicalized whitespace', async () => {
+    const baselineIso = '2026-02-01T00:00:00.000Z';
+    const compareIso = '2026-02-05T00:00:00.000Z';
+
+    (TFSServices.getItemContent as jest.Mock).mockImplementation(
+      async (url: string, _pat: string, method?: string, data?: any) => {
+        if (url.includes('/_apis/wit/queries/q-raw-html') && url.includes('api-version=7.1')) {
+          return { name: 'Raw Html Q', wiql: 'SELECT [System.Id] FROM WorkItems' };
+        }
+        if (url.includes('/_apis/wit/wiql?') && method === 'post') {
+          return { workItems: [{ id: 601 }, { id: 602 }] };
+        }
+        if (url.includes('/_apis/wit/workitemsbatch') && method === 'post') {
+          const isBaseline = data.asOf === baselineIso;
+          return {
+            value: [
+              {
+                id: 601,
+                rev: isBaseline ? 1 : 2,
+                fields: {
+                  'System.WorkItemType': 'Requirement',
+                  'System.Title': 'Whitespace-only edit',
+                  'System.State': 'Active',
+                  // Same content, differing only by internal whitespace: must compare as
+                  // unchanged (identical to the pre-existing collapse-then-compare behavior)
+                  // while the raw stored value keeps the original spacing for rendering.
+                  'System.Description': isBaseline
+                    ? '<p>Hello   world</p>'
+                    : '<p>Hello\nworld</p>',
+                  'System.ChangedDate': isBaseline ? baselineIso : compareIso,
+                },
+              },
+              {
+                id: 602,
+                rev: isBaseline ? 1 : 2,
+                fields: {
+                  'System.WorkItemType': 'Requirement',
+                  'System.Title': 'Real edit',
+                  'System.State': 'Active',
+                  'System.Description': isBaseline ? '<p>Hello world</p>' : '<p>Hello <b>world</b></p>',
+                  'System.ChangedDate': isBaseline ? baselineIso : compareIso,
+                },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected URL: ${url}`);
+      },
+    );
+
+    const result = await provider.CompareHistoricalQueryResults('q-raw-html', project, baselineIso, compareIso);
+    const byId = new Map<number, any>(result.rows.map((row: any) => [row.id, row]));
+
+    expect(byId.get(601)?.compareStatus).toBe('No changes');
+    expect(byId.get(602)?.compareStatus).toBe('Changed');
+    const diff = byId.get(602)?.differences.find((d: any) => d.field === 'Description');
+    // Raw markup is preserved on the difference payload, not collapsed to plain text.
+    expect(diff.baseline).toBe('<p>Hello world</p>');
+    expect(diff.compareTo).toBe('<p>Hello <b>world</b></p>');
+  });
+
+  it('CompareHistoricalQueryResults attaches parsed Action/Expected steps for a changed test case', async () => {
+    const baselineIso = '2026-02-10T00:00:00.000Z';
+    const compareIso = '2026-02-15T00:00:00.000Z';
+
+    const buildStepsXml = (expected: string) =>
+      `<steps id="0" last="1"><step id="1" type="ActionStep">` +
+      `<parameterizedString isformatted="true">Open the app</parameterizedString>` +
+      `<parameterizedString isformatted="true">${expected}</parameterizedString>` +
+      `</step></steps>`;
+
+    (TFSServices.getItemContent as jest.Mock).mockImplementation(
+      async (url: string, _pat: string, method?: string, data?: any) => {
+        if (url.includes('/_apis/wit/queries/q-parsed-steps') && url.includes('api-version=7.1')) {
+          return { name: 'Parsed Steps Q', wiql: 'SELECT [System.Id] FROM WorkItems' };
+        }
+        if (url.includes('/_apis/wit/wiql?') && method === 'post') {
+          return { workItems: [{ id: 701 }] };
+        }
+        if (url.includes('/_apis/wit/workitemsbatch') && method === 'post') {
+          const isBaseline = data.asOf === baselineIso;
+          return {
+            value: [
+              {
+                id: 701,
+                rev: isBaseline ? 1 : 2,
+                fields: {
+                  'System.WorkItemType': 'Test Case',
+                  'System.Title': 'Login test',
+                  'System.State': 'Active',
+                  'Microsoft.VSTS.TCM.Steps': buildStepsXml(isBaseline ? 'Login page shown' : 'Dashboard shown'),
+                  'System.ChangedDate': isBaseline ? baselineIso : compareIso,
+                },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected URL: ${url}`);
+      },
+    );
+
+    const result = await provider.CompareHistoricalQueryResults(
+      'q-parsed-steps',
+      project,
+      baselineIso,
+      compareIso,
+    );
+    const row = result.rows.find((r: any) => r.id === 701);
+    expect(row?.compareStatus).toBe('Changed');
+    expect(row?.changedFields).toContain('Steps');
+    const diff = row?.differences.find((d: any) => d.field === 'Steps');
+    expect(diff.baselineSteps).toEqual([
+      expect.objectContaining({ action: 'Open the app', expected: 'Login page shown' }),
+    ]);
+    expect(diff.compareToSteps).toEqual([
+      expect.objectContaining({ action: 'Open the app', expected: 'Dashboard shown' }),
+    ]);
+  });
+
+  it('CompareHistoricalQueryResults falls back gracefully when Steps XML cannot be parsed', async () => {
+    const baselineIso = '2026-02-20T00:00:00.000Z';
+    const compareIso = '2026-02-25T00:00:00.000Z';
+
+    (TFSServices.getItemContent as jest.Mock).mockImplementation(
+      async (url: string, _pat: string, method?: string, data?: any) => {
+        if (url.includes('/_apis/wit/queries/q-bad-steps') && url.includes('api-version=7.1')) {
+          return { name: 'Bad Steps Q', wiql: 'SELECT [System.Id] FROM WorkItems' };
+        }
+        if (url.includes('/_apis/wit/wiql?') && method === 'post') {
+          return { workItems: [{ id: 801 }] };
+        }
+        if (url.includes('/_apis/wit/workitemsbatch') && method === 'post') {
+          const isBaseline = data.asOf === baselineIso;
+          return {
+            value: [
+              {
+                id: 801,
+                rev: isBaseline ? 1 : 2,
+                fields: {
+                  'System.WorkItemType': 'Test Case',
+                  'System.Title': 'Malformed steps case',
+                  'System.State': 'Active',
+                  'Microsoft.VSTS.TCM.Steps': isBaseline ? '<steps><unclosed>' : '<steps><unclosed2>',
+                  'System.ChangedDate': isBaseline ? baselineIso : compareIso,
+                },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected URL: ${url}`);
+      },
+    );
+
+    const result = await provider.CompareHistoricalQueryResults('q-bad-steps', project, baselineIso, compareIso);
+    const row = result.rows.find((r: any) => r.id === 801);
+    expect(row?.compareStatus).toBe('Changed');
+    expect(row?.changedFields).toContain('Steps');
+    const diff = row?.differences.find((d: any) => d.field === 'Steps');
+    expect(diff.baseline).toBe('<steps><unclosed>');
+    expect(diff.compareTo).toBe('<steps><unclosed2>');
+    // TestStepParserHelper.parseTestSteps already swallows its own parse errors and resolves to
+    // an empty list, so the diff carries empty parsed-steps arrays rather than raw XML garbage;
+    // the content-control adapter treats an empty array the same as "no parsed steps".
+    expect(diff.baselineSteps).toEqual([]);
+    expect(diff.compareToSteps).toEqual([]);
+  });
+
   it('GetHistoricalQueryResults treats a workitemsbatch errorPolicy Omit as skipped without a per-item fallback', async () => {
     const asOfIso = '2026-01-15T00:00:00.000Z';
 
@@ -994,4 +1161,75 @@ describe('TicketsDataProvider historical queries', () => {
       (logger.warn as jest.Mock).mock.calls.some((call) => String(call[0]).includes('omitted 1')),
     ).toBe(true);
   });
+
+  it('GetHistoricalQueryResults drops only the specific field ADO names in TF51535, keeping Custom.TestPhase when only Elisra.TestPhase is undefined for this project', async () => {
+    const asOfIso = '2026-02-01T00:00:00.000Z';
+    // 205 ids -> 2 chunks (200 + 5), both dispatched with the full field list
+    // near-simultaneously — this proves the retry is decided per-call, not
+    // from the shared override flag, since both chunks fail before either
+    // one sets it.
+    const allIds = Array.from({ length: 205 }, (_, idx) => idx + 1);
+
+    (TFSServices.getItemContent as jest.Mock).mockImplementation(
+      async (url: string, _pat: string, method?: string, data?: any) => {
+        if (url.includes('/_apis/wit/queries/q-unknown-field') && url.includes('api-version=7.1')) {
+          return { name: 'Unknown Field Q', wiql: 'SELECT [System.Id] FROM WorkItems' };
+        }
+        if (url.includes('/_apis/wit/wiql?') && method === 'post') {
+          return { workItems: allIds.map((id) => ({ id })) };
+        }
+        if (url.includes('/_apis/wit/workitemsbatch') && method === 'post') {
+          if (data?.$expand === 'Relations') {
+            return {
+              value: (Array.isArray(data?.ids) ? data.ids : []).map((id: number) => ({ id, relations: [] })),
+            };
+          }
+          if (Array.isArray(data?.fields) && data.fields.includes('Elisra.TestPhase')) {
+            throw {
+              response: {
+                status: 400,
+                data: { message: "TF51535: Cannot find field 'Elisra.TestPhase'." },
+              },
+            };
+          }
+          // Custom.TestPhase is the real field on this project and must
+          // still be requested — only the unrecognized alias should be
+          // dropped, not every optional field.
+          expect(data.fields).toEqual(expect.arrayContaining(['Custom.TestPhase']));
+          expect(data.fields).not.toEqual(expect.arrayContaining(['Elisra.TestPhase']));
+          return {
+            value: (Array.isArray(data?.ids) ? data.ids : []).map((id: number) => ({
+              id,
+              rev: 1,
+              fields: {
+                'System.WorkItemType': 'Test Case',
+                'System.Title': `Test ${id}`,
+                'System.State': 'Active',
+                'System.ChangedDate': asOfIso,
+                'Custom.TestPhase': 'FAT',
+              },
+            })),
+          };
+        }
+        throw new Error(`unexpected URL: ${url}`);
+      },
+    );
+
+    const result = await provider.GetHistoricalQueryResults('q-unknown-field', project, asOfIso);
+
+    // Every id came back — nothing fell to the 2xN per-item fallback, which
+    // would have thrown on any call not covered by the handler above.
+    expect(result.total).toBe(205);
+    const fieldsCallsWithElisraAlias = (TFSServices.getItemContent as jest.Mock).mock.calls.filter(
+      (call) => Array.isArray(call[3]?.fields) && call[3].fields.includes('Elisra.TestPhase'),
+    );
+    // Both chunks start with the full field list before the override is set,
+    // so both legitimately fail once and both must retry — not just one.
+    expect(fieldsCallsWithElisraAlias).toHaveLength(2);
+    expect(
+      (logger.warn as jest.Mock).mock.calls.some((call) =>
+        String(call[0]).includes("field 'Elisra.TestPhase' not defined for this project"),
+      ),
+    ).toBe(true);
+  });
 });