[RFC] Use markdown format for integration test snapshots

compiler/crates/fixture-tests/src/lib.rs

@@ -125,25 +125,61 @@ pub async fn test_fixture<T, U, V>(
         colored::control::unset_override();
     }
 
-    let actual = match &actual_result {
-        Ok(output) => format!(
-            "==================================== INPUT ====================================
+    // Check if we should use markdown format based on expected file extension
+    let use_markdown = expected_file_name.ends_with(".md");
+
+    let actual = if use_markdown {
+        match &actual_result {
+            Ok(output) => format!(
+                "## Input
+
+```
+{}
+```
+
+## Output
+
+{}
+",
+                &fixture.content.trim(),
+                output,
+            ),
+            Err(output) => format!(
+                "## Input
+
+```
+{}
+```
+
+## Error
+
+{}
+",
+                fixture.content.trim(),
+                output
+            ),
+        }
+    } else {
+        match &actual_result {
+            Ok(output) => format!(
+                "==================================== INPUT ====================================
 {}
 ==================================== OUTPUT ===================================
 {}
 ",
-            &fixture.content.trim(),
-            output,
-        ),
-        Err(output) => format!(
-            "==================================== INPUT ====================================
+                &fixture.content.trim(),
+                output,
+            ),
+            Err(output) => format!(
+                "==================================== INPUT ====================================
 {}
 ==================================== ERROR ====================================
 {}
 ",
-            fixture.content.trim(),
-            output
-        ),
+                fixture.content.trim(),
+                output
+            ),
+        }
     };
 
     match actual_result {

compiler/crates/fixture-tests/src/main.rs

@@ -32,6 +32,10 @@ struct Options {
 
     #[clap(long)]
     customized_snapshot_fixer: Option<String>,
+
+    /// Expected file extension (default: "expected")
+    #[clap(long, default_value = "expected")]
+    expected_extension: String,
 }
 #[derive(Debug)]
 struct TestCase {
@@ -40,8 +44,6 @@ struct TestCase {
     expected: Option<PathBuf>,
 }
 
-const EXPECTED_EXTENSION: &str = "expected";
-
 fn main() {
     let opt = Options::parse();
 
@@ -62,7 +64,7 @@ fn main() {
                 input: None,
                 expected: None,
             });
-            if path.extension().unwrap() == EXPECTED_EXTENSION {
+            if path.extension().unwrap() == opt.expected_extension.as_str() {
                 if let Some(ref previous) = test_case.expected {
                     panic!("Conflicting fixture name, {previous:?} and {path:?}");
                 }
@@ -79,7 +81,7 @@ fn main() {
                 && let Some(ref input) = test_case.input
             {
                 let mut expected = input.clone();
-                expected.set_extension(EXPECTED_EXTENSION);
+                expected.set_extension(&opt.expected_extension);
                 let fixer = match &opt.customized_snapshot_fixer {
                         Some(customized) => customized.as_str().as_bytes(),
                         None => {

compiler/crates/graphql-syntax/tests/visitor_test.rs

@@ -9,31 +9,55 @@
 
 mod visitor;
 
+use fixture_tests::test_fixture;
 use visitor::transform_fixture;
 use visitor::transform_schema_fixture;
-use fixture_tests::test_fixture;
 
 // Executable document tests
 
 #[tokio::test]
 async fn kitchen_sink() {
     let input = include_str!("visitor/fixtures/kitchen_sink.graphql");
     let expected = include_str!("visitor/fixtures/kitchen_sink.expected");
-    test_fixture(transform_fixture, file!(), "kitchen_sink.graphql", "visitor/fixtures/kitchen_sink.expected", input, expected).await;
+    test_fixture(
+        transform_fixture,
+        file!(),
+        "kitchen_sink.graphql",
+        "visitor/fixtures/kitchen_sink.expected",
+        input,
+        expected,
+    )
+    .await;
 }
 
 #[tokio::test]
 async fn nested_fragments() {
     let input = include_str!("visitor/fixtures/nested_fragments.graphql");
     let expected = include_str!("visitor/fixtures/nested_fragments.expected");
-    test_fixture(transform_fixture, file!(), "nested_fragments.graphql", "visitor/fixtures/nested_fragments.expected", input, expected).await;
+    test_fixture(
+        transform_fixture,
+        file!(),
+        "nested_fragments.graphql",
+        "visitor/fixtures/nested_fragments.expected",
+        input,
+        expected,
+    )
+    .await;
 }
 
 #[tokio::test]
 async fn variable_definitions() {
     let input = include_str!("visitor/fixtures/variable_definitions.graphql");
     let expected = include_str!("visitor/fixtures/variable_definitions.expected");
-    test_fixture(transform_fixture, file!(), "variable_definitions.graphql", "visitor/fixtures/variable_definitions.expected", input, expected).await;
+    test_fixture(
+        transform_fixture,
+        file!(),
+        "variable_definitions.graphql",
+        "visitor/fixtures/variable_definitions.expected",
+        input,
+        expected,
+    )
+    .await;
 }
 
 // Schema document tests
@@ -42,19 +66,43 @@ async fn variable_definitions() {
 async fn schema_kitchen_sink() {
     let input = include_str!("visitor/fixtures/schema_kitchen_sink.graphql");
     let expected = include_str!("visitor/fixtures/schema_kitchen_sink.expected");
-    test_fixture(transform_schema_fixture, file!(), "schema_kitchen_sink.graphql", "visitor/fixtures/schema_kitchen_sink.expected", input, expected).await;
+    test_fixture(
+        transform_schema_fixture,
+        file!(),
+        "schema_kitchen_sink.graphql",
+        "visitor/fixtures/schema_kitchen_sink.expected",
+        input,
+        expected,
+    )
+    .await;
 }
 
 #[tokio::test]
 async fn schema_with_directives() {
     let input = include_str!("visitor/fixtures/schema_with_directives.graphql");
     let expected = include_str!("visitor/fixtures/schema_with_directives.expected");
-    test_fixture(transform_schema_fixture, file!(), "schema_with_directives.graphql", "visitor/fixtures/schema_with_directives.expected", input, expected).await;
+    test_fixture(
+        transform_schema_fixture,
+        file!(),
+        "schema_with_directives.graphql",
+        "visitor/fixtures/schema_with_directives.expected",
+        input,
+        expected,
+    )
+    .await;
 }
 
 #[tokio::test]
 async fn schema_extensions() {
     let input = include_str!("visitor/fixtures/schema_extensions.graphql");
     let expected = include_str!("visitor/fixtures/schema_extensions.expected");
-    test_fixture(transform_schema_fixture, file!(), "schema_extensions.graphql", "visitor/fixtures/schema_extensions.expected", input, expected).await;
+    test_fixture(
+        transform_schema_fixture,
+        file!(),
+        "schema_extensions.graphql",
+        "visitor/fixtures/schema_extensions.expected",
+        input,
+        expected,
+    )
+    .await;
 }

compiler/crates/graphql-test-helpers/src/project_fixture.rs

@@ -48,7 +48,7 @@ impl ProjectFixture {
         Self { files }
     }
 
-    /// Serialize ProjectFixture as a fixture file string.
+    /// Serialize ProjectFixture as a fixture file string using the original format.
     /// Useful for encoding the results of a compiler integration test as
     /// a single output file.
     pub fn serialize(&self) -> String {
@@ -66,6 +66,30 @@ impl ProjectFixture {
         output
     }
 
+    /// Serialize ProjectFixture as markdown with fenced code blocks.
+    /// Each file is output as a separate code block with syntax highlighting
+    /// based on the file extension.
+    pub fn serialize_as_markdown(&self) -> String {
+        let mut sorted: Vec<_> = self.files.clone().into_iter().collect();
+        sorted.sort_by(|x, y| x.0.cmp(&y.0));
+
+        let mut output: String = Default::default();
+
+        for (file_name, content) in sorted {
+            let normalized_path = format_normalized_path(&file_name);
+            let language = infer_language(&file_name);
+            output.push_str(&format!("### `{}`\n\n", normalized_path));
+            output.push_str(&format!("```{}\n", language));
+            output.push_str(&content);
+            if !content.ends_with('\n') {
+                output.push('\n');
+            }
+            output.push_str("```\n\n");
+        }
+
+        output
+    }
+
     /// Write the files contained in this ProjectFixture to a directory.
     /// Useful for writing a fixture file to a temp directory before running an
     /// integration test.
@@ -120,3 +144,14 @@ fn format_normalized_path(path: &Path) -> String {
         .to_string()
         .replace(MAIN_SEPARATOR, "/")
 }
+
+// Infer the language identifier for markdown code fence from file extension
+fn infer_language(path: &Path) -> &'static str {
+    match path.extension().and_then(|ext| ext.to_str()) {
+        Some("js") => "js",
+        Some("ts") | Some("tsx") => "ts",
+        Some("graphql") | Some("gql") => "graphql",
+        Some("json") => "json",
+        _ => "",
+    }
+}

compiler/crates/relay-compiler/tests/relay_compiler_integration.rs

@@ -72,9 +72,9 @@ pub async fn transform_fixture(fixture: &Fixture<'_>) -> Result<String, String>
                 // Omit the input files from the output
                 output.remove_files(project_fixture);
                 let mut expected = output
-                    .serialize()
+                    .serialize_as_markdown()
                     // Jump through a few hoops to avoid having at-generated in either this
-                    // file or our generated `.expected` files, since that would confuse other
+                    // file or our generated `.md` files, since that would confuse other
                     // tools.
                     .replace(&format!("{}generated", '@'), "<auto-generated>");
 

compiler/crates/relay-compiler/tests/relay_compiler_integration/fixtures/client_extension_interface_backed_by_resolvers_in_throw_on_field_error.expected → compiler/crates/relay-compiler/tests/relay_compiler_integration/fixtures/client_extension_interface_backed_by_resolvers_in_throw_on_field_error.md

@@ -1,4 +1,6 @@
-==================================== INPUT ====================================
+## Input
+
+```
 //- foo.js
 graphql`fragment fooFragment on MyInterface @throwOnFieldError {
   id
@@ -36,8 +38,13 @@ interface MyInterface {
   id: ID!
   name: String
 }
-==================================== OUTPUT ===================================
-//- __generated__/ClientUser____relay_model_instance.graphql.js
+```
+
+## Output
+
+### `__generated__/ClientUser____relay_model_instance.graphql.js`
+
+```js
 /**
  * <auto-generated> SignedSource<<b7752710f2dec1efcfee6cfb9fc746cd>>
  * @flow
@@ -103,8 +110,11 @@ export default ((node/*: any*/)/*: Fragment<
   ClientUser____relay_model_instance$fragmentType,
   ClientUser____relay_model_instance$data,
 >*/);
+```
+
+### `__generated__/ClientUser__id.graphql.js`
 
-//- __generated__/ClientUser__id.graphql.js
+```js
 /**
  * <auto-generated> SignedSource<<002edcab96dd03234c41444688f0adcf>>
  * @flow
@@ -158,8 +168,11 @@ export default ((node/*: any*/)/*: Fragment<
   ClientUser__id$fragmentType,
   ClientUser__id$data,
 >*/);
+```
+
+### `__generated__/fooFragment.graphql.js`
 
-//- __generated__/fooFragment.graphql.js
+```js
 /**
  * <auto-generated> SignedSource<<e9be170a9a95b3b5bf9c03d572fde0ba>>
  * @flow
@@ -225,6 +238,7 @@ export default ((node/*: any*/)/*: Fragment<
   fooFragment$fragmentType,
   fooFragment$data,
 >*/);
+```
 
 
 

compiler/crates/relay-compiler/tests/relay_compiler_integration/fixtures/client_mutation_extension.expected → compiler/crates/relay-compiler/tests/relay_compiler_integration/fixtures/client_mutation_extension.md

@@ -1,4 +1,6 @@
-==================================== INPUT ====================================
+## Input
+
+```
 //- bar.js
 graphql`mutation barMutation {
    foo_mutation
@@ -28,8 +30,13 @@ type Query {
 extend type Mutation {
    foo_mutation: Boolean
 }
-==================================== OUTPUT ===================================
-//- __generated__/barMutation.graphql.js
+```
+
+## Output
+
+### `__generated__/barMutation.graphql.js`
+
+```js
 /**
  * <auto-generated> SignedSource<<8c2ec235b8b068c2c2fffbc3aae787b8>>
  * @flow
@@ -102,6 +109,7 @@ export default ((node/*: any*/)/*: Mutation<
   barMutation$variables,
   barMutation$data,
 >*/);
+```