docs: add TESTING.md with testing conventions for contributors#3718
Open
sandikodev wants to merge 2 commits intoaws:mainfrom
Open
docs: add TESTING.md with testing conventions for contributors#3718sandikodev wants to merge 2 commits intoaws:mainfrom
sandikodev wants to merge 2 commits intoaws:mainfrom
Conversation
The codebase has insta as a workspace dependency but its usage is minimal and undocumented. Contributors currently have no guidance on: - when to use assert_eq!/assert! vs insta snapshot testing - how to run the cargo-insta review workflow - how to handle ANSI escape codes in terminal output tests Add TESTING.md at the repo root covering: - Quick reference table for choosing assertion style - Standard assertion examples - Full insta workflow (write -> run -> review -> accept) - ANSI escape code stripping pattern - Real example referencing the pattern used in PR aws#3717 Add a one-line pointer in CONTRIBUTING.md.
…nd real examples - Add Table of Contents - Add Core Principle section explaining the decision framework - Expand Quick Reference table with JSON and 'output may change' rows - Add explicit do/don't examples for standard assertions - Document all three insta modes (inline, auto-named, named) - Add note to install cargo-insta before writing snapshot tests - Add note that strip_ansi_escapes is already in the workspace - Add Case 2: sanitize_path_tool_arg as a second real example - Expand Anti-Patterns with context on why each is problematic
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
The codebase has
instaas a workspace dependency but its usage is minimal (3 occurrences across the entire codebase) and completely undocumented. There is currently no guidance for contributors on:assert_eq!/assert!vsinstasnapshot testingcargo instareview workflowprint_diff)This gap leads to either fragile hardcoded strings or missing tests for rendered output entirely.
Changes
TESTING.mdat the repo root with:cargo-instaworkflow: write → run → review → acceptCONTRIBUTING.md→TESTING.mdNotes
docs/was intentionally left unchanged — all existing files there are user-facing feature documentation, not contributor guidesTESTING.mdfollows the same root-level convention asCONTRIBUTING.md,SECURITY.md, andCODE_OF_CONDUCT.mdBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.