Skip to content

[RFC] Use markdown format for integration test snapshots#5137

Open
captbaritone wants to merge 4 commits intomainfrom
markdown-snapshots
Open

[RFC] Use markdown format for integration test snapshots#5137
captbaritone wants to merge 4 commits intomainfrom
markdown-snapshots

Conversation

@captbaritone
Copy link
Contributor

@captbaritone captbaritone commented Jan 13, 2026

Summary

This RFC proposes migrating relay_compiler_integration test snapshots from .expected to .md files with syntax highlighting for improved readability in editors and GitHub.

Motivation: Markdown Snapshots - syntax highlighting makes snapshots easier to read and review.

Changes

  • Added serialize_as_markdown() to ProjectFixture with fenced code blocks
  • Made --expected-extension a CLI argument in fixture-tests
  • Renamed 70 integration test snapshots: .expected.md
  • Updated update-fixtures.sh to handle both formats

Example

Before:

==================================== INPUT ====================================
//- foo.js
graphql`fragment foo on User { name }`;
==================================== OUTPUT ===================================
//- __generated__/foo.graphql.ts
[TypeScript code without highlighting...]

After:

## Input

```js title="foo.js"
graphql\`fragment foo on User { name }\`;
```

## Output

```ts title="__generated__/foo.graphql.ts"
[TypeScript code with syntax highlighting...]
```

Compatibility

✅ Other fixture tests unaffected - only `relay_compiler_integration` uses markdown
✅ All 70 tests passing

Questions

  1. Migrate other test suites to markdown?
  2. Additional file extensions needed?

captbaritone and others added 3 commits January 12, 2026 20:08
This RFC proposes migrating the relay_compiler_integration test snapshots
from the legacy .expected format to markdown (.md) files with syntax
highlighting. This change improves snapshot readability and review
experience in editors and on GitHub.

- Added `serialize_as_markdown()` method to ProjectFixture that outputs
  fenced code blocks with `title="filename"` syntax
- Added language inference (js, ts, graphql, json) for syntax highlighting
- Updated fixture-tests to detect .md files and use markdown formatting
  (## Input, ## Output, ## Error headers)
- Made --expected-extension a CLI argument to support both formats

- Created fixture_dirs_md.txt for markdown fixture directories
- Updated fixture_dirs.txt to exclude relay_compiler_integration
- Updated update-fixtures.sh to call fixture generator twice:
  once for .expected files, once for .md files

- Renamed all 70 integration test snapshots from .expected to .md
- Regenerated snapshots with proper markdown formatting
- All 70 integration tests passing

- Syntax highlighting in GitHub/editors improves readability
- Easier to review snapshot changes in PRs
- Better diff visualization
- Preserves backward compatibility for other fixture tests

See: https://jordaneldredge.com/markdown-snapshots/

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Added file name as ### heading before each code block
- Removed title attribute from code fence (redundant with heading)
- Added blank line after each code block for better readability

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Changed ### __generated__/foo.ts to ### `__generated__/foo.ts`
for better markdown rendering.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@captbaritone
Copy link
Contributor Author

  • Example of output file in "preview" mode.
  • Example of output file in text mode with syntax highlighting.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants