Self Test Doc

Create or update a NAS frontend self-test document in Lark for QA handoff. Use after a feature or large PR needs developer test evidence, parent/child Lark wiki placement, non-production browser verification, and screenshots or videos embedded inside the Self-Test Record table cells; browser evidence should use a 1440x900 viewport and compare against Figma when available.

Source: .agents/skills/self-test-doc/SKILL.md

Metadata

• name: self-test-doc
• version: 1.0.3
• bins: ["lark-cli"]

Content

Self Test Doc

Prerequisite: Read installed lark-shared, lark-doc, and lark-drive before creating docs or uploading visual evidence. Use lark-cli shortcuts before raw OpenAPI calls.

Create a developer self-test document for nas-fe and place it as a child page under the related tech design document.

Test URL Policy

Self-test URLs change per PR, preview, branch, or environment. Before browser verification or visual evidence capture:

• Ask the user for the exact URL they want tested if no test URL was provided in the current request.
• Do not guess or reuse an old preview URL from memory unless the user explicitly confirms it for this test pass.
• Do not test on production nas.com.
• Do not test on dev-nas.com.
• Prefer preview, branch, staging, localhost, or another user-confirmed non-production URL.
• If the user only provides nas.com or dev-nas.com, stop browser verification and ask for a safe preview/test URL instead. You may still draft the document and mark browser evidence as blocked by missing valid test URL.

Reference Format

Follow the house style of:

https://nasdaily.sg.larksuite.com/wiki/DJSfwQBLXiQtlnkU7OFlsxtfg3c?from=space_search

Use that document as a format reference. The observed structure is:

• Dev self Test for Web
• Task name/link
• Task type
• Developer
• Role: Web
• Date
• Change Overview and Impact
• Check Points table
• Self-Test Record table
• Known Issues and Limitations

Required Skills

Read installed upstream skills before writing:

• lark-shared
• lark-doc
• lark-drive when screenshots or videos need upload/linking before insertion
• lark-wiki for parent-child wiki placement, including blank parent fallback creation

Use docs +create --api-version v2 or docs +update --api-version v2 with XML content. For real parent-child pages in personal space or wiki, prefer wiki +node-create followed by docs +update --command overwrite over standalone doc creation.

Permissions

Operation	Required scope
Create Docx document	docx:document:create
Write Docx document content	docx:document:write_only
Read parent/template document	docs:document.content:read or docx:document:readonly
Upload screenshots or videos into docs	docs:document.media:upload or scope reported by lark-drive
Create/read wiki parent and child nodes	wiki:node:create, wiki:node:read, wiki:space:read
Resolve/list wiki spaces when needed	Scope reported by lark-wiki for the target parent, commonly wiki:space:retrieve

Preflight

Before creating the child self-test doc:

command -v lark-cli
lark-cli auth status

Handle results:

• If lark-cli is missing, do not create the doc. Return the XML draft or checklist and tell the user to install/configure Lark CLI.
• If user identity is unavailable, user-owned parent docs/wiki pages cannot be accessed. Start split auth through lark-shared for the minimum doc/wiki scope needed.
• If bot identity is unavailable, do not use bot-owned creation paths. Prefer --as user.
• If user identity needs refresh, continue with --as user; if refresh fails, follow lark-shared.
• If the parent tech design or personal-library fallback cannot be resolved because scopes are missing, start split auth through lark-shared for the minimum reported scope. Do not silently downgrade to a standalone doc when the user requested a child page.

Inputs

Required before creation:

• Parent tech design Lark URL or wiki token when the user has one. If the current request does not provide one, follow the Missing Parent Tech Design Fallback instead of stopping.
• Task or PR link.
• Developer name.
• PR URL.
• Preview/test environment URL to verify. This is required before browser checks or screenshots. Ask the user for it when missing. Reject nas.com and dev-nas.com as test targets.
• Summary of changed modules.
• Figma URL/node/spec, if available.
• Verification commands already run.
• Manual browser checks, screenshots, recordings, logs, or reasons they are unavailable.
• Screenshot or video evidence for each user-facing feature workflow or test case. If evidence has not been captured yet and the app can be run locally, capture it before writing the final doc.

If the parent tech design doc is missing, do not stop immediately. Ask the user one specific question:

Do you have a parent tech design Lark URL or wiki token for this self-test doc? If not, I will create a blank frontend tech design parent page and then create the self-test doc as its child.

If the user provides a parent URL/token, create the self-test doc under that parent. If the user says there is no parent doc, does not have one, or explicitly asks to proceed without one, create the blank parent tech design page first, then create the self-test doc inside it as a child page.

Missing Parent Tech Design Fallback

When the user has no parent tech design page:

1. Infer a concise parent title from the PR/task name, for example Frontend Tech Design - Short Feature Name.
2. Create the blank parent as a wiki node in the user's personal Lark library with lark-cli wiki +node-create --as user --space-id my_library --title "<parent title>" unless the user provides a specific wiki parent URL/token or another Lark location.
3. Use the returned parent obj_token to write the minimal parent content with docs +update --api-version v2 --command overwrite.
4. Create the self-test child with lark-cli wiki +node-create --as user --parent-node-token "<parent_node_token>" --title "<self-test title>".
5. Use the returned child obj_token to write the self-test content with docs +update --api-version v2 --command overwrite.
6. Create parent and child pages as user-owned content unless the user explicitly requests bot-owned creation and bot access is available.
7. Keep the blank parent intentionally small; it is only a stable parent for the self-test child until a full tech design is written.

Do not ask another location/title confirmation after the user says there is no parent doc unless the PR/task name is missing or ambiguous enough that a reasonable parent title cannot be inferred.

Minimal blank parent content:

<title>Frontend Tech Design - Short Feature Name</title>

<h1>Frontend Tech Design</h1>
<p><b>Feature / PR:</b> <a href="...">...</a></p>
<p><b>Status:</b> Placeholder parent created for self-test documentation.</p>
<p><b>Owner:</b> ...</p>
<p><b>Date:</b> YYYY.MM.DD</p>

Document Shape

Create a child page with this structure:

<title>Dev Self Test - Short Feature Name</title>

<h1>Dev self Test for Web</h1>
<p><b>Task Name / Link:</b> <a href="...">...</a></p>
<p><b>Task Type:</b> Product / Tech</p>
<p><b>Developer:</b> ...</p>
<p><b>Role:</b> Web</p>
<p><b>Date:</b> YYYY.MM.DD</p>

<h4>Change Overview &amp; Impact</h4>
<p><b>Risk Level:</b> Low / Medium / High</p>
<p><b>Summary of Changes / Affected Modules:</b> ...</p>
<p><b>PR link:</b> <a href="...">...</a></p>

<h4>Check Points</h4>
<table>...</table>

<h4>Self-Test Record</h4>
<table>...</table>

<h4>Known Issues &amp; Limitations</h4>
<ol>...</ol>

The checkpoints table must include Web rows for:

• Test Env Deployment
• Dev self Test and Smoke Test
• Event tracking Test
• Force upgrade
• User GreyScale and DownGrade Logic
• BE API / Old Data compatibility
• Release / Rollback Plan

Use checkbox cells for Yes, No, and No need. Fill the remark column with environment links, accounts, logs, PR links, or short notes.

The Self-Test Record table must include these columns:

• Workflow / Test Case
• Tested URL
• Account / Role / Viewport
• Expected Result
• Status
• Visual Evidence
• Figma / Design Gap
• Notes

Use color in pass/fail/status cells:

• Pass: green background or green status tag.
• Fail: red background or red status tag.
• Blocked: orange/yellow background or warning status tag.
• Needs manual evidence placement: orange/yellow background or warning status tag.
• No need: gray background or gray status tag.

When Lark XML supports styled spans or table-cell background color, apply the color directly in the Status cell. If the available CLI path cannot style table cells reliably, use colored status tags/spans inside the cell and mention the styling limitation in the final output.

Visual Evidence In Self-Test Record

The self-test doc should not be only written words. For each user-facing feature workflow or self-test case:

• Capture browser evidence at 1440x900 unless the user explicitly asks for another viewport. Put 1440x900 in the Account / Role / Viewport cell.
• Capture a screenshot for stable UI states.
• Capture a short video or GIF for multi-step flows, animations, checkout/payment/auth transitions, modal flows, redirects, or state changes that a static screenshot cannot prove.
• Put the actual screenshot, video, GIF, or linked media block inside the Visual Evidence column cell of the matching Self-Test Record row.
• Do not create a separate Visual Evidence section as the primary evidence location.
• Do not create a Self-Test Record Evidence Attachments section below the table.
• Do not append screenshots or videos below the table as the final evidence placement.
• Include the tested URL, account/role, viewport/device, and short expected result in the same Self-Test Record row.
• To embed local screenshots or videos in table cells, use this workflow:
  1. Upload the media into the target document to obtain a media token. docs +media-insert --file <path> can be used as an upload helper, but it may append a temporary media block at the end of the document.
  2. Record the returned file_token and temporary block_id. If the command reports an internal/empty-response error after upload, inspect the command output for the uploaded file token and continue only if the token is present.
  3. Fetch the self-test document with docs +fetch --api-version v2 --detail with-ids and locate the block inside the intended Visual Evidence table cell.
  4. Use docs +update --api-version v2 --command block_replace --block-id "<cell_content_block_id>" --content '<img src="<file_token>" width="320" height="..." caption="..." name="..."/>' to put the image in that table cell.
  5. Delete any temporary media block appended outside the table with docs +update --command block_delete --block-id "<temporary_block_id>".
  6. Fetch the document again and verify the matching Visual Evidence table cell contains an <img> or media block.
• If in-cell media placement fails after the upload-token + block-replace workflow, do not use a below-table attachment workaround. Mark the row Blocked or Needs manual evidence placement, write the exact CLI/API limitation in that row's Notes, and report the missing in-row evidence in the final output.
• When using docs +media-insert, remember that appended media at the document end is never acceptable as final placement by itself. It is only acceptable as a temporary upload step if the media token is then inserted into the intended Visual Evidence table cell and the temporary block is deleted.
• For non-visual cases such as API compatibility, analytics, or release checks, attach the most relevant proof: logs, request/response screenshot, dashboard screenshot, command output summary, or mark No visual evidence needed with a reason.
• If evidence cannot be captured because env access, data, credentials, feature flags, or Lark upload permissions are missing, state the exact blocker in that row. Do not replace missing evidence with a vague written pass.

Prefer browser screenshots/video from the actual tested route over copied Figma or PR screenshots. Do not attach sensitive customer data, secrets, tokens, raw env values, or private payment/auth details.

Figma Comparison

When a Figma URL, node, screenshot, or design spec is available:

1. Load the relevant Figma context using the installed Figma skills/tools before finalizing the self-test doc.
2. Compare the actual tested 1440x900 browser screenshot or video frame against the Figma design.
3. Name every meaningful gap in the matching Self-Test Record row under Figma / Design Gap.
4. For each gap, state the expected design and the observed implementation, for example Button spacing: expected 16px below title, observed 8px.
5. Mark the row Fail for user-visible design mismatches that should block handoff, or Pass with noted minor gaps only when the gap is explicitly acceptable or non-blocking.
6. If Figma is unavailable, inaccessible, or not relevant for the workflow, write No Figma reference provided or Not design-driven in the Figma / Design Gap cell.

Do not invent Figma expectations from memory. If the design is ambiguous, record the ambiguity as a design-gap note or open question rather than claiming a pass.

Known Issues Boundaries

Known Issues & Limitations is product-facing. Include only product, feature, UX, compatibility, data, rollout, or user-impacting limitations discovered during testing.

Do not put Lark CLI issues, missing scopes, upload quirks, evidence-placement mechanics, local file paths, test setup details, or documentation workflow limitations in Known Issues & Limitations. Put those in the relevant Self-Test Record Notes cell and in the final agent output under missing evidence/tooling limitations.

Browser Verification Flow

Before testing:

1. Confirm the requested test URL is present and is not nas.com or dev-nas.com.
2. Set the browser viewport to 1440x900 before capturing standard desktop evidence.
3. Open the user-confirmed URL only.
4. Capture evidence per workflow/test case.
5. Compare against Figma when Figma is available and record named gaps in the matching row.
6. Store each evidence item against the matching Self-Test Record row.

If the URL is missing or unsafe:

• Ask the user for the exact preview/test URL.
• Do not navigate to nas.com or dev-nas.com.
• Mark affected rows as Blocked with the reason Missing valid non-production test URL if creating a draft before verification.

Commands

If the user has no parent tech design doc, create a blank parent wiki node in the personal library, then write its content:

lark-cli wiki +node-create --as user --space-id my_library --title "<parent title>"
lark-cli docs +update --api-version v2 --as user --doc "<parent_obj_token>" --command overwrite --doc-format xml --content @.git/self-test-parent-tech-design.xml

Create the self-test child under the parent wiki node, then write the self-test content:

lark-cli wiki +node-create --as user --parent-node-token "<parent_node_token>" --title "<self-test title>"
lark-cli docs +update --api-version v2 --as user --doc "<child_obj_token>" --command overwrite --doc-format xml --content @.git/self-test-doc.xml

If an existing parent URL is provided, resolve it with lark-wiki when needed. Prefer creating the child with wiki +node-create --parent-node-token so the Lark page hierarchy is real.

Upload and place screenshot evidence in the intended table cell:

lark-cli docs +media-insert --doc "<child_obj_token>" --file ./evidence.png --width 320 --caption "..."
lark-cli docs +fetch --api-version v2 --doc "<child_obj_token>" --detail with-ids --scope keyword --keyword "Visual Evidence"
lark-cli docs +update --api-version v2 --doc "<child_obj_token>" --command block_replace --block-id "<visual_evidence_cell_block_id>" --doc-format xml --content '<img src="<file_token>" width="320" height="180" caption="..." name="evidence.png"/>'
lark-cli docs +update --api-version v2 --doc "<child_obj_token>" --command block_delete --block-id "<temporary_appended_media_block_id>"

Output

Return:

• self-test Lark URL/token
• parent tech design URL/token
• PR URL
• risk level
• checkpoint rows marked Yes, No, or No need
• visual evidence coverage by workflow/test case
• viewport used for browser evidence, expected to be 1440x900 unless explicitly overridden
• Figma comparison coverage and named design gaps, or why Figma comparison was unavailable
• tested URL used for browser verification, or the exact blocker if no valid test URL was provided
• missing screenshots, recordings, accounts, environment links, or upload permissions
• tooling or Lark CLI limitations separately from product Known Issues & Limitations

Safety

• Do not fabricate test evidence.
• Do not test production nas.com.
• Do not test dev-nas.com.
• Do not guess the test URL. Ask the user when the URL is missing or ambiguous.
• Do not include passwords, auth tokens, private customer data, or raw env values.
• Do not mark a checkpoint Yes unless evidence exists in commands, screenshots, recordings, logs, or user-provided confirmation.
• Do not mark a user-facing workflow as fully self-tested unless it has screenshot/video evidence or a specific, defensible reason why visual evidence is unavailable.
• Do not mark a Figma-backed workflow as fully passed unless the actual 1440x900 browser evidence was compared with the design or a specific blocker is recorded.
• Do not put tooling, Lark CLI, permission, upload, or documentation workflow issues in the product-facing Known Issues & Limitations section.