larksuite__cli/tests/cli_e2e/docs/coverage.md

# Docs CLI E2E Coverage

## Metrics
- Denominator: 12 leaf commands
- Covered: 9
- Coverage: 75.0%

## Summary
- TestDocs_CreateAndFetchWorkflow: proves `docs +create` and `docs +fetch`; key `t.Run(...)` proof points are `create as bot` and `fetch as bot`.
- TestDocs_CreateAndFetchWorkflowAsUser: proves the same shortcut pair with UAT injection via `create as user` and `fetch as user`; creates its own Drive folder fixture first, then reads back the created doc by token.
- TestDocsFetchDryRunXMLIncludesCommentsForUserAndBot, TestDocsFetchDryRunMarkdownFormatsIncludeCommentSidecar, and TestDocsFetchCommentsWorkflowAsBot / AsUser prove XML, Markdown, and IM Markdown fetches default to comment v2 for identical UAT/TAT request bodies; XML carries local `comment-refs`, while Markdown keeps comments only in `reference_map.comments`. The live workflows cover full/partial filtering plus JSON/explicit-legacy-pretty output behavior.
- TestDocsCommandsHideFormatHelpButKeepCompatibility proves `docs +fetch`, `+create`, and `+update` no longer advertise the legacy output `--format` flag, while explicit callers remain parse-compatible and the default dry-run envelope remains JSON.
- TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
- TestDocs_BlockMutationRangeWorkflow: creates a bot-owned document with adjacent paragraph fixtures, discovers current block IDs through XML `with-ids`, replaces one inclusive range, deletes another inclusive range, polls fetch until both changes are visible, and cleans up the document and folder.
- TestDocs_LocalResourcesWorkflowAsBot / AsUser: prove the full local image + file lifecycle for `docs +create` and `docs +update --command append|block_insert_after|block_replace`: placeholder correlation, exact insertion after a block ID obtained from `docs +fetch --detail with-ids`, persisted block ordering, distinct media block IDs, local image intrinsic-dimension detection, model display-size conversion to persisted `scale`, invalid `width`/`height`/`size` normalization, media upload, token binding, response scrubbing, XML/Markdown fetch verification, exported-Markdown replay with image caption restoration, and cleanup.
- TestDocs_LocalResourcesDryRun: proves `docs +create` and `docs +update --command append|overwrite|block_replace` expose the complete no-network request plan for local images and files: placeholder content with intrinsic dimensions, media uploads, image binding with intrinsic `width`/`height` plus converted `scale`, file binding, conditional verification, and failure cleanup.
- TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance; its fetch case asserts fetch sends the default `extra_param`, and its update case asserts `--reference-map` is sent as request body `reference_map`.
- TestDocs_CreateTitleDryRunPrependsContent: proves `docs +create --title` dry-run prepends an escaped `<title>...</title>` tag to request body `content`.
- TestDocsScriptInitDraftCreatesUniqueWorkspacesWithoutXML, TestDocsScriptInitDraftDryRunDoesNotWrite, TestDocsScriptInitDraftAcceptsWindowsCommandShimQuotes, TestDocsScriptMangledPresentationDecisionSuggestsFileInput, TestDocsScriptFileNameFlagIsRemoved, TestDocsScriptParseXMLFromFile, TestDocsScriptLocalParseWithAuthenticatedBot, TestDocsScriptRemoteImagePreflightDryRunDeclaresNetwork, TestDocsScriptInitializedDraftAutomaticallyValidatesPresentationDecision, TestDocsScriptParseRepairsMalformedXMLForProfile, TestDocsScriptStrictFlagIsRemoved, TestDocsScriptMarkdownToXMLIsRemoved, TestDocsScriptCreateTempXMLIsRemoved, TestDocsScriptParseAcceptsLocalImagePath, TestDocsScriptParseDoesNotSupportLegacyQAImage, TestDocsScriptParseAcceptsServerSDKAttributeAmpersand, TestDocsScriptParseRejectsMarkdownFromFile, TestDocsScriptDryRunIsLocal, TestDocsScriptOnlineDryRunFetchesXML, and TestDocs_CreateAndFetchWorkflowAsBot/script parse by token prove `docs +script` initializes distinct `draft_<random>_folder/draft.xml` workspaces under concurrency, reserves the XML path without creating the file, accepts the decision through inline JSON and `@file`, tolerates one outer single-quote pair preserved by Windows command shims, gives file-input recovery guidance when a shell removes JSON quotes, returns `ok:true` and exit code 0 for completed checks while separating pass/fail through `data.assessment.status`, reports word-count, required-block, and resource failures as structured `data.diagnostics[]`, groups same-cause remote image failures into one diagnostic with `image_indices[]`, keeps dry-run side-effect free, rejects the removed `--file-name`, `create-temp-xml`, and `markdown-to-xml` surfaces, exposes only tolerant parsing without `--strict`, accepts the service SDK's bare-ampersand URL attribute form and local `<img path="@relative">` syntax, does not recognize legacy `qa_image`, counts known block tags without enforcing business schema, profiles malformed XML through deterministic recovery, parses local XML with authenticated bot configuration, rejects Markdown input, reports external remote-image preflight network use accurately, fetches online document URL/token input as XML, and returns word/character/block profiles.
- TestDocsScriptPresentationDecisionListCountsULAndOL proves the compatibility-only `list` requirement aggregates `<ul>` and `<ol>` block counts.
- TestDocs_DryRunDefaultsToV2OpenAPI also proves `docs +history-list`, `docs +history-revert`, and `docs +history-revert-status` dry-run endpoint and query/body shapes.
- TestDocs_HistoryWorkflow proves the guarded live history flow (`LARK_DOC_HISTORY_E2E=1`): create, update, list prior revisions, revert, poll status when needed, and fetch to verify reverted content.
- TestDocsMediaInsertDryRun_AppendsWithoutMCP proves `docs +media-insert` plans only the four append OpenAPI steps, uses `<children_len>`, and has no MCP locator; TestDocsMediaInsertRemovedLocationFlagsRejected pins removal of both legacy location flags. TestDocs_MediaDownloadWorkflow creates a temporary folder and document, writes a deterministic PNG fixture, inserts it, downloads it by the returned media token, verifies the saved bytes, and cleans up the document and folder.
- Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
- Blocked area: media preview still needs a stable live comment-image fixture; search and whiteboard update still need deterministic fixtures or DSL-specific orchestration. Local resource authoring through create/update is covered.

## Command Table

| Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
| --- | --- | --- | --- | --- | --- |
| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_local_resources_workflow_test.go::TestDocs_LocalResourcesWorkflowAsBot/create image and source; docs_local_resources_workflow_test.go::TestDocs_LocalResourcesWorkflowAsUser/create image and source; docs_local_resources_dryrun_test.go::TestDocs_LocalResourcesDryRun/create; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent; docs_update_dryrun_test.go::TestDocs_CreateEmptyContentFileReportsActionableError | `--parent-token`; `--doc-format markdown`; `--content`; `--title`; XML `<img path="@relative" width="display-px">` + `<source path="@relative">` | local-resource workflows assert returned image/file block IDs and bound tokens; image binding preserves intrinsic dimensions and converts display size to `scale`; empty `@file` content reports the file path and `init-draft` recovery action |
| ✓ | docs +fetch | shortcut | docs_fetch_dryrun_test.go::TestDocsFetchDryRunXMLIncludesCommentsForUserAndBot; docs_fetch_dryrun_test.go::TestDocsFetchDryRunMarkdownFormatsIncludeCommentSidecar; docs_fetch_dryrun_test.go::TestDocsFetchCommentsFlagIsRemovedFromHelpAndRejected; docs_fetch_dryrun_test.go::TestDocsCommandsHideFormatHelpButKeepCompatibility; docs_fetch_comments_workflow_test.go::TestDocsFetchCommentsWorkflowAsBot; docs_fetch_comments_workflow_test.go::TestDocsFetchCommentsWorkflowAsUser; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsBot/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_local_resources_workflow_test.go::testDocsLocalResourcesWorkflow/fetch verifies persisted resources | `--doc <docToken>`; all `--doc-format` values default `extra_param.include_comments=true`; XML carries local `comment-refs`, Markdown/IM Markdown return only the sidecar; `--detail full`; hidden legacy `--format`; `--api-version v1` compatibility flag still dry-runs the v2 fetch endpoint | user/bot request bodies match; comment v2 full/partial refs are closed; default JSON preserves the sidecar; explicit legacy pretty stays body-only; removed `--comments` is absent from help and rejected |
| ✓ | docs +history-list | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history list; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--page-size`; `--page-token` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
| ✓ | docs +history-revert | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--history-version-id`; `--wait-timeout-ms` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
| ✓ | docs +history-revert-status | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert status; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--task-id` | live workflow polls only when revert returns `running` |
| ✓ | docs +script | shortcut | docs_script_test.go::TestDocsScriptPresentationDecisionListCountsULAndOL; docs_script_test.go::TestDocsScriptInitDraftCreatesUniqueWorkspacesWithoutXML; docs_script_test.go::TestDocsScriptInitDraftDryRunDoesNotWrite; docs_script_test.go::TestDocsScriptInitDraftAcceptsWindowsCommandShimQuotes; docs_script_test.go::TestDocsScriptMangledPresentationDecisionSuggestsFileInput; docs_script_test.go::TestDocsScriptFileNameFlagIsRemoved; docs_script_test.go::TestDocsScriptInitializedDraftAutomaticallyValidatesPresentationDecision; docs_script_test.go::TestDocsScriptInitializedDraftPreflightsBlockedRemoteImage; docs_script_test.go::TestDocsScriptParseRepairsMalformedXMLForProfile; docs_script_test.go::TestDocsScriptStrictFlagIsRemoved; docs_script_test.go::TestDocsScriptMarkdownToXMLIsRemoved; docs_script_test.go::TestDocsScriptCreateTempXMLIsRemoved; docs_script_test.go::TestDocsScriptParseRejectsMarkdownFromFile; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsBot/script parse by token | `--command init-draft` with `--presentation-decision <JSON>`, one command-shim-preserved outer single-quote pair, `@file`, or `-`; `--command parse --content @file`; `--doc <URL/token>`; local/online dry-run | initializes `draft_<random>_folder/draft.xml` and reserves the uncreated XML path; validates word-count and planned block minimums; treats compatibility type `list` as the combined `<ul>` and `<ol>` count; preflights local/remote resources; returns `ok:true` with `assessment.status:failed` and structured diagnostics when checks do not pass; deduplicates same-cause image failures into `image_indices[]`; requires normal authentication for local parse, rejects Markdown input, and fetches online input as XML |
| ✓ | docs +media-download | shortcut | docs_media_download_dryrun_test.go::TestDocsMediaDownloadDryRun_PlansExportAuthBeforeMediaDownload; docs_media_download_dryrun_test.go::TestDocsMediaDownloadDryRun_WhiteboardSkipsExportAuth; docs_media_download_workflow_test.go::TestDocs_MediaDownloadWorkflow | `--token`; `--output`; `--type whiteboard` dry-run | dry-run pins permission-check ordering and whiteboard bypass; live workflow creates a media fixture and verifies downloaded bytes |
| ✓ | docs +media-insert | shortcut | docs_media_insert_dryrun_test.go::TestDocsMediaInsertDryRun_AppendsWithoutMCP; docs_media_insert_dryrun_test.go::TestDocsMediaInsertRemovedLocationFlagsRejected; docs_media_download_workflow_test.go::TestDocs_MediaDownloadWorkflow | `--doc`; `--file`; `--type image`; append-only `<children_len>` plan without MCP; removed `--selection-with-ellipsis` / `--before` rejected | dry-run pins the append-only request chain and removed flags; live workflow asserts the returned media token and uses it to retrieve the inserted image |
| ✕ | docs +media-preview | shortcut |  | none | requires a deterministic comment-image fixture to verify whether `<img src="TOKEN"/>` works with the source preview endpoint |
| ✕ | docs +search | shortcut |  | none | search results are ambient and not yet stabilized for E2E |
| ✓ | docs +update | shortcut | docs_update_test.go::TestDocs_UpdateWorkflow/update-title-and-content as bot; docs_update_test.go::TestDocs_BlockMutationRangeWorkflow; docs_local_resources_workflow_test.go::testDocsLocalResourcesWorkflow/append, block_insert_after, block_replace, and overwrite image/source; docs_local_resources_dryrun_test.go::TestDocs_LocalResourcesDryRun/update append, overwrite, and block_replace; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/update | `--doc`; `--command overwrite`, `append`, `block_insert_after`, `block_replace`, or `block_delete`; `--block-id` or inclusive `--start-block-id` + `--end-block-id`; `--doc-format markdown` or `--doc-format xml`; `--content`; local `<img path>` / `<source path>`; optional `--reference-map` -> body `reference_map` | local resources are covered under both bot and user identities; exact-position image insertion is verified from fetched block ID through persisted order; range replace/delete are covered with a bot-owned live document |
| ✕ | docs +whiteboard-update | shortcut |  | none | requires whiteboard fixture and DSL-specific assertions |