refactor: clarify documentation on incompatible document commits and enhance related tests

.claude/skills/write-insomnia-test/reference.md

@@ -1481,7 +1481,7 @@ cancelUnknownFieldsConfirmation(): Promise<void>
 confirmUnknownFieldsCommit(name: string): Promise<void>         // Continue; waits for `name`'s row to leave the modal
 ```
 
-The current build does **not** block committing an incompatible doc (INS-4014 open question) — `incompatible-remote-document.spec.ts` asserts only the icon tooltip and red banner. Real examples: `remote-document-with-unknown-fields.spec.ts` (icon, banner, highlight, cancel → still staged → confirm), `incompatible-remote-document.spec.ts`.
+Committing an incompatible doc is intentionally **not** blocked — `incompatible-remote-document.spec.ts` asserts the icon tooltip and red banner, then that committing still succeeds (the current behavior is the intended one). Real examples: `remote-document-with-unknown-fields.spec.ts` (icon, banner, highlight, cancel → still staged → confirm), `incompatible-remote-document.spec.ts`.
 
 ### Project dashboard — unsynced-file delete (INS-2026 fix, PR #10477)
 

packages/insomnia-test/tests/cloud-sync/unknown-fields/incompatible-remote-document.spec.ts

@@ -1,9 +1,9 @@
 import { faker } from '@faker-js/faker';
 
-import { expect, seedCloudSyncProject, test } from '../../../misc/fixtures';
+import { DEFAULT_TIMEOUT, expect, seedCloudSyncProject, test } from '../../../misc/fixtures';
 import { buildCloudSyncDocs } from './helpers';
 
-test('Verify a Cloud Sync document whose remote version is incompatible shows the error icon and banner', async ({ user }) => {
+test('Verify a Cloud Sync document whose remote version is incompatible shows the error icon and banner and can still be committed', async ({ user }) => {
   const { workspaceFlow, httpRequestFlow, cloudSyncFlow } = user.flowManager;
   const { cloudSyncPage } = user.pageManager;
 
@@ -22,9 +22,11 @@ test('Verify a Cloud Sync document whose remote version is incompatible shows th
   const iconTooltip = await cloudSyncPage.getUnsupportedItemIconTooltip(renamed);
   const bannerText = await cloudSyncPage.getUnsupportedDocDiffErrorText();
   const hasUnknownFieldsBanner = await cloudSyncPage.isUnknownFieldsDiffWarningVisible();
+  await cloudSyncPage.commit(renamed, faker.lorem.sentence());
 
   expect(iconTooltip).toContain('not supported by this version of Insomnia');
   expect(iconTooltip).toContain('converted to an older format');
   expect(bannerText).toContain('committing changes will break functionality for your collaborators');
   expect(hasUnknownFieldsBanner).toBe(false);
+  await expect.poll(() => cloudSyncPage.isCommitDisabled(), { timeout: DEFAULT_TIMEOUT }).toBe(true);
 });

packages/insomnia-test/tests/git-sync/undiscardable-change/non-insomnia-added-and-deleted-files-show-no-warning.spec.ts

@@ -10,7 +10,7 @@ import { DEFAULT_TIMEOUT, expect, GIT_CREDENTIAL, pushServerFile, test } from '.
 import { Collection } from '../../../models/collection';
 import { Project } from '../../../models/project';
 
-test('Verify a modified non-Insomnia file and an added or deleted file show no undiscardable warning', async ({
+test('Verify a modified non-Insomnia file and an added or deleted file show no undiscardable warning or unknown fields UI, and commit without confirmation', async ({
   user,
 }) => {
   const { gitSyncFlow, preferencesFlow, workspaceFlow } = user.flowManager;
@@ -20,7 +20,7 @@ test('Verify a modified non-Insomnia file and an added or deleted file show no u
   await pushServerFile({ path: otherFileName, content: `openapi: 3.0.0\ninfo:\n  title: ${faker.string.alpha(10)}\n` });
   await preferencesFlow.addGitCredential(GIT_CREDENTIAL);
   const cloneParentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'insomnia-undiscardable-'));
-  const project = await workspaceFlow.create(
+  const { project, unknownFieldFiles } = await workspaceFlow.cloneWithScanReport(
     new Project(faker.string.alphanumeric(10), ProjectType.Git),
     GIT_CREDENTIAL.name,
     { cloneParentDir },
@@ -44,13 +44,21 @@ test('Verify a modified non-Insomnia file and an added or deleted file show no u
     .toBeGreaterThanOrEqual(3);
   const unstaged = (await gitSyncFlow.getChanges()).unstaged;
   const warnings = [];
+  const unknownFieldsStates = [];
   for (const file of unstaged) {
     await gitSyncPage.openCommitDialog();
     await gitSyncPage.openChangeDiff(GitChangeList.Unstaged, file);
     warnings.push(await gitSyncPage.isUndiscardableWarningVisible());
+    unknownFieldsStates.push({
+      hasBanner: await gitSyncPage.isUnknownFieldsDiffWarningVisible(),
+      highlightCount: await gitSyncPage.getUnknownFieldHighlightCount(),
+    });
     await gitSyncPage.closeCommitDialog();
   }
+  const message = faker.string.alphanumeric(10);
+  const commit = await gitSyncFlow.commit(message);
 
+  expect(unknownFieldFiles).toEqual([]);
   expect(unstaged).toEqual(
     expect.arrayContaining([
       expect.stringContaining(otherFileName),
@@ -59,4 +67,6 @@ test('Verify a modified non-Insomnia file and an added or deleted file show no u
     ]),
   );
   expect(warnings).toEqual(unstaged.map(() => false));
+  expect(unknownFieldsStates).toEqual(unstaged.map(() => ({ hasBanner: false, highlightCount: 0 })));
+  expect(commit.message).toBe(message);
 });

packages/insomnia-test/tests/git-sync/unknown-fields/cloud-sync-and-git-sync-warnings-stay-independent.spec.ts

@@ -0,0 +1,65 @@
+import { faker } from '@faker-js/faker';
+
+import { GitChangeList } from '../../../enums/git-change-list';
+import { ProjectType } from '../../../enums/project-types';
+import { seedCloudSyncProject } from '../../../misc/fixtures';
+import { DEFAULT_TIMEOUT, expect, GIT_CREDENTIAL, pushServerFile, test } from '../../../misc/git-fixtures';
+import { Collection } from '../../../models/collection';
+import { Project } from '../../../models/project';
+import { buildCloudSyncDocs } from '../../cloud-sync/unknown-fields/helpers';
+import { buildCollectionFileWithUnknownField } from './helpers';
+
+test('Verify Cloud Sync and Git Sync unknown fields warnings stay independent in one session', async ({ user }) => {
+  const { gitSyncFlow, httpRequestFlow, preferencesFlow, workspaceFlow, cloudSyncFlow } = user.flowManager;
+  const { gitSyncPage, cloudSyncPage } = user.pageManager;
+
+  const fileName = `${faker.string.alpha(10).toLowerCase()}.yaml`;
+  const gitCollectionName = faker.string.alpha(10);
+  const { content, requestName: gitRequestName } = buildCollectionFileWithUnknownField(gitCollectionName);
+  await pushServerFile({ path: fileName, content });
+  await preferencesFlow.addGitCredential(GIT_CREDENTIAL);
+  await workspaceFlow.create(new Project(faker.string.alphanumeric(10), ProjectType.Git), GIT_CREDENTIAL.name);
+  await expect
+    .poll(async () => (await gitSyncFlow.getChanges()).unstaged, { timeout: DEFAULT_TIMEOUT })
+    .toContain(fileName);
+  await gitSyncPage.openCommitDialog();
+  await gitSyncPage.openChangeDiff(GitChangeList.Unstaged, fileName);
+  const gitBefore = {
+    hasBanner: await gitSyncPage.isUnknownFieldsDiffWarningVisible(),
+    highlighted: (await gitSyncPage.getUnknownFieldHighlightCount()) > 0,
+  };
+  await gitSyncPage.closeCommitDialog();
+
+  const cloudCollectionName = faker.string.alpha(10);
+  const { docs, requestName } = buildCloudSyncDocs(cloudCollectionName, { futureField: faker.string.alpha(10) });
+  await seedCloudSyncProject(cloudCollectionName, docs);
+  await user.page.reload();
+  await cloudSyncFlow.fetch(cloudCollectionName);
+  const cloudCollection = await workspaceFlow.getCollection({ name: cloudCollectionName });
+  const request = await httpRequestFlow.get(requestName, cloudCollection);
+  const renamed = faker.string.alphanumeric(10);
+  await workspaceFlow.rename(request!, renamed);
+  await cloudSyncPage.openCommitDialog();
+  await cloudSyncPage.openChangeDiff(renamed);
+  const cloudState = {
+    hasBanner: await cloudSyncPage.isUnknownFieldsDiffWarningVisible(),
+    highlighted: (await cloudSyncPage.getUnknownFieldHighlightCount()) > 0,
+  };
+  await cloudSyncPage.submitCommit(renamed, faker.lorem.sentence());
+  const cloudConfirmationText = await cloudSyncPage.getUnknownFieldsConfirmationText();
+  await cloudSyncPage.confirmUnknownFieldsCommit(renamed);
+
+  await httpRequestFlow.get(gitRequestName, new Collection(gitCollectionName));
+  await gitSyncPage.openCommitDialog();
+  await gitSyncPage.openChangeDiff(GitChangeList.Unstaged, fileName);
+  const gitAfter = {
+    hasBanner: await gitSyncPage.isUnknownFieldsDiffWarningVisible(),
+    highlighted: (await gitSyncPage.getUnknownFieldHighlightCount()) > 0,
+    hasUndiscardableWarning: await gitSyncPage.isUndiscardableWarningVisible(),
+  };
+
+  expect(gitBefore).toEqual({ hasBanner: true, highlighted: true });
+  expect(cloudState).toEqual({ hasBanner: true, highlighted: true });
+  expect(cloudConfirmationText).toContain('may break or remove functionality for your collaborators');
+  expect(gitAfter).toEqual({ hasBanner: true, highlighted: true, hasUndiscardableWarning: false });
+});