format

Author: ananas-block

INTEGRATION_TESTING.md

@@ -62,6 +62,9 @@ All integration tests in this repository must follow these mandatory requirement
 • **Functional test for every usage flow** - Each user workflow must have a corresponding test
 • **Failing test for every error condition** - Every error case must have a test that verifies the expected failure
 • **Complete output verification** - Assert the entire output struct in a single `assert_eq!` against the expected struct
+• **Before + Changes = After pattern** - Test exact state transitions, not arbitrary end states
+• **Complete struct assertions** - Single comprehensive `assert_eq!` on complete structs, not individual fields
+• **Proper test documentation** - Numbered SUCCESS/FAIL test case lists for each test function
 
 ## Assertion Utilities
 
@@ -121,22 +124,170 @@ async fn test_invalid_authority_fails() {
 ### Complete Output Verification
 **Assert complete output structures in single `assert_eq!` against expected structs**
 
+## **CRITICAL: Ideal Assertion Pattern**
+
+**❌ WRONG: Creating arbitrary expected end states**
 ```rust
-#[tokio::test]
-async fn test_operation_output() {
-    let result = perform_operation(&mut rpc, test_params).await.unwrap();
+// Anti-pattern: Creating expected state from scratch
+let expected_end_state = create_expected_state(field1, field2, field3);
+assert_eq!(actual_state, expected_end_state);
+```
+
+**✅ CORRECT: Before State + Expected Changes = After State**
+```rust
+// IDEAL: Parse actual before state, apply expected changes, compare to after state
+{
+    // Parse complete state before operation
+    let mut expected_after_state = parse_state_before(&state_data_before);
 
-    let expected = ExpectedOperationResult {
-        transaction_signature: result.signature,
-        modified_accounts: expected_account_changes,
-        emitted_events: expected_events,
-        // ... all expected outputs
-    };
+    // Apply the expected changes to the before state
+    expected_after_state.field1 = new_value;  // Only change what should change
+    expected_after_state.amount -= transfer_amount;
 
-    assert_eq!(result, expected);
+    // Parse actual state after operation
+    let actual_after_state = parse_state_after(&state_data_after);
+    
+    // Single comprehensive assertion: after = before + changes
+    assert_eq!(actual_after_state, expected_after_state);
+}
+```
+
+## **Real Example from Codebase**
+From `/program-tests/utils/src/assert_decompressed_token_transfer.rs`:
+
+```rust
+{
+    // Parse as SPL token accounts first
+    let mut sender_token_before =
+        spl_token_2022::state::Account::unpack(&sender_data_before[..165]).unwrap();
+    sender_token_before.amount -= transfer_amount;
+    let mut recipient_token_before =
+        spl_token_2022::state::Account::unpack(&recipient_data_before[..165]).unwrap();
+    recipient_token_before.amount += transfer_amount;
+
+    // Parse as SPL token accounts first  
+    let sender_account_after =
+        spl_token_2022::state::Account::unpack(&sender_account_data.data[..165]).unwrap();
+    let recipient_account_after =
+        spl_token_2022::state::Account::unpack(&recipient_account_data.data[..165]).unwrap();
+    assert_eq!(sender_account_after, sender_token_before);
+    assert_eq!(recipient_account_after, recipient_token_before);
+}
+```
+
+This pattern ensures you're testing **exact state transitions** rather than arbitrary end states.
+
+## **Common Pitfalls and Solutions**
+
+### **❌ Assertion Anti-Patterns to Avoid**
+
+```rust
+// ❌ WRONG: Individual field assertions
+assert_eq!(actual.field1, expected_field1);
+assert_eq!(actual.field2, expected_field2);
+assert_eq!(actual.field3, expected_field3);
+
+// ❌ WRONG: Creating expected end states from scratch
+let expected = ExpectedState {
+    field1: "hardcoded_value",
+    field2: 42,
+    field3: vec![1, 2, 3],
+};
+
+// ❌ WRONG: Not capturing actual before state
+let expected_before = create_expected_state(/* guess what before state was */);
+```
+
+### **✅ Correct Patterns**
+
+```rust
+// ✅ CORRECT: Parse actual before state, apply changes, assert after
+let actual_before = parse_complete_state(&account_data_before);
+let mut expected_after = actual_before.clone();
+expected_after.field1 = new_value; // Apply only the expected change
+let actual_after = parse_complete_state(&account_data_after);
+assert_eq!(actual_after, expected_after);
+```
+
+### **Test Documentation Requirements**
+
+**❌ WRONG: Vague test descriptions**
+```rust
+/// Test metadata operations
+#[tokio::test]
+async fn test_metadata() {
+```
+
+**✅ CORRECT: Numbered SUCCESS/FAIL lists**
+```rust
+/// Test:
+/// 1. SUCCESS: Create mint with additional metadata keys
+/// 2. SUCCESS: Update metadata name field
+/// 3. FAIL: Update metadata field with invalid authority
+#[tokio::test]
+#[serial]
+async fn test_metadata_field_operations() -> Result<(), RpcError> {
+```
+
+### **Error Propagation Patterns**
+
+**❌ WRONG: Using .unwrap() everywhere**
+```rust
+let result = operation(&mut rpc, params).await.unwrap();
+```
+
+**✅ CORRECT: Proper error propagation**
+```rust
+async fn test_operation() -> Result<(), RpcError> {
+    let result = operation(&mut rpc, params).await?;
+    Ok(())
+}
+```
+
+### **Helper Function Best Practices**
+
+**❌ WRONG: Hiding errors in helpers**
+```rust
+async fn create_mint_helper(rpc: &mut RPC) {
+    create_mint(rpc, params).await.unwrap(); // Hides errors!
+}
+```
+
+**✅ CORRECT: Propagate errors from helpers**
+```rust
+async fn create_mint_helper(rpc: &mut RPC) -> Result<Signature, RpcError> {
+    create_mint(rpc, params).await
 }
 ```
 
+### **Struct Parsing Best Practices**
+
+**✅ CORRECT: Use borsh deserialization for easier type handling**
+```rust
+// Parse complete structs using borsh for easier handling
+let mint_data: CompressedMint = 
+    BorshDeserialize::deserialize(&mut account_data.as_slice())
+        .expect("Failed to deserialize CompressedMint");
+        
+// Work with the complete struct
+assert_eq!(actual_mint, expected_mint);
+```
+
+**✅ CORRECT: Parse complete state, not partial data**
+```rust
+// Get complete account state before and after
+let complete_state_before = get_complete_account_state(&mut rpc, address).await;
+// ... perform operation ...
+let complete_state_after = get_complete_account_state(&mut rpc, address).await;
+
+// Apply expected changes to before state
+let mut expected_after = complete_state_before.clone();
+expected_after.some_field = new_value;
+
+// Assert complete state transition
+assert_eq!(complete_state_after, expected_after);
+```
+
 ### Integration Test Pattern
 ```rust
 use light_test_utils::assert_operation_result;

program-libs/ctoken-types/tests/solana_ctoken.rs

@@ -3,8 +3,7 @@ use light_ctoken_types::state::{
     solana_ctoken::{CompressedToken, CompressedTokenConfig, ZCompressedToken},
     ExtensionStructConfig,
 };
-use light_zero_copy::borsh_mut::DeserializeMut;
-use light_zero_copy::{borsh::Deserialize, init_mut::ZeroCopyNew};
+use light_zero_copy::{borsh::Deserialize, borsh_mut::DeserializeMut, init_mut::ZeroCopyNew};
 use rand::Rng;
 use spl_pod::{bytemuck::pod_from_bytes, primitives::PodU64, solana_program_option::COption};
 use spl_token_2022::{

program-libs/zero-copy-derive/src/shared/utils.rs

@@ -5,7 +5,9 @@ use std::{
 
 use proc_macro2::TokenStream;
 use quote::{format_ident, quote};
-use syn::{Attribute, Data, DataEnum, DeriveInput, Field, Fields, FieldsNamed, Ident, Type, TypePath};
+use syn::{
+    Attribute, Data, DataEnum, DeriveInput, Field, Fields, FieldsNamed, Ident, Type, TypePath,
+};
 
 // Global cache for storing whether a struct implements Copy
 lazy_static::lazy_static! {

program-libs/zero-copy-derive/src/zero_copy.rs

@@ -5,7 +5,9 @@ use syn::{parse_quote, DeriveInput, Field, Ident};
 
 use crate::shared::{
     meta_struct, utils,
-    z_enum::{generate_enum_deserialize_impl, generate_enum_zero_copy_struct_inner, generate_z_enum},
+    z_enum::{
+        generate_enum_deserialize_impl, generate_enum_zero_copy_struct_inner, generate_z_enum,
+    },
     z_struct::{analyze_struct_fields, generate_z_struct, FieldType},
 };
 
@@ -245,7 +247,11 @@ pub fn derive_zero_copy_impl(input: ProcTokenStream) -> syn::Result<proc_macro2:
             let (meta_fields, struct_fields) = utils::process_fields(fields);
 
             let meta_struct_def = if !meta_fields.is_empty() {
-                meta_struct::generate_meta_struct::<false>(&z_struct_meta_name, &meta_fields, hasher)?
+                meta_struct::generate_meta_struct::<false>(
+                    &z_struct_meta_name,
+                    &meta_fields,
+                    hasher,
+                )?
             } else {
                 quote! {}
             };
@@ -284,7 +290,8 @@ pub fn derive_zero_copy_impl(input: ProcTokenStream) -> syn::Result<proc_macro2:
 
             let z_enum_def = generate_z_enum(&z_enum_name, enum_data)?;
             let deserialize_impl = generate_enum_deserialize_impl(name, &z_enum_name, enum_data)?;
-            let zero_copy_struct_inner_impl = generate_enum_zero_copy_struct_inner(name, &z_enum_name)?;
+            let zero_copy_struct_inner_impl =
+                generate_enum_zero_copy_struct_inner(name, &z_enum_name)?;
 
             // Combine all implementations
             Ok(quote! {

program-libs/zero-copy-derive/tests/action_enum_test.rs

@@ -19,14 +19,15 @@ pub enum Action {
 #[cfg(test)]
 mod tests {
     use light_zero_copy::borsh::Deserialize;
+
     use super::*;
 
     #[test]
     fn test_action_enum_unit_variants() {
         // Test Update variant (discriminant 1)
         let data = [1u8];
         let (result, remaining) = Action::zero_copy_at(&data).unwrap();
-        
+
         // We can't pattern match without importing the generated type,
         // but we can verify it doesn't panic and processes correctly
         println!("Successfully deserialized Update variant");
@@ -37,17 +38,17 @@ mod tests {
     fn test_action_enum_data_variant() {
         // Test MintTo variant (discriminant 0)
         let mut data = vec![0u8]; // discriminant 0 for MintTo
-        
+
         // Add MintToAction serialized data
         // amount: 1000
         data.extend_from_slice(&1000u64.to_le_bytes());
-        
+
         // recipient: "alice" (5 bytes length + "alice")
         data.extend_from_slice(&5u32.to_le_bytes());
         data.extend_from_slice(b"alice");
 
         let (result, remaining) = Action::zero_copy_at(&data).unwrap();
-        
+
         // We can't easily pattern match without the generated type imported,
         // but we can verify it processes without errors
         println!("Successfully deserialized MintTo variant");
@@ -59,18 +60,18 @@ mod tests {
         // Test all unit variants
         let variants = [
             (1u8, "Update"),
-            (2u8, "CreateSplMint"), 
+            (2u8, "CreateSplMint"),
             (3u8, "UpdateMetadata"),
         ];
 
         for (discriminant, name) in variants {
             let data = [discriminant];
             let result = Action::zero_copy_at(&data);
-            
+
             assert!(result.is_ok(), "Failed to deserialize {} variant", name);
             let (_, remaining) = result.unwrap();
             assert_eq!(remaining.len(), 0);
             println!("Successfully deserialized {} variant", name);
         }
     }
-}
+}

program-libs/zero-copy-derive/tests/comprehensive_enum_example.rs

@@ -26,7 +26,7 @@ pub enum ZAction<'a> {
 
 impl<'a> Deserialize<'a> for Action {
     type Output = ZAction<'a>;
-    
+
     fn zero_copy_at(data: &'a [u8]) -> Result<(Self::Output, &'a [u8]), ZeroCopyError> {
         match data[0] {
             0 => {
@@ -83,36 +83,41 @@ pub enum Action {
 #[cfg(test)]
 mod tests {
     use light_zero_copy::borsh::Deserialize;
+
     use super::*;
 
     #[test]
     fn test_generated_enum_structure() {
         // The macro should generate ZAction<'a> with concrete variants
-        
+
         // Test unit variants
-        for (discriminant, expected_name) in [(1u8, "Update"), (2u8, "CreateSplMint"), (3u8, "UpdateMetadata")] {
+        for (discriminant, expected_name) in [
+            (1u8, "Update"),
+            (2u8, "CreateSplMint"),
+            (3u8, "UpdateMetadata"),
+        ] {
             let data = [discriminant];
             let (result, remaining) = Action::zero_copy_at(&data).unwrap();
             assert_eq!(remaining.len(), 0);
             println!("✓ {}: {:?}", expected_name, result);
         }
-        
+
         // Test data variant
         let mut data = vec![0u8]; // MintTo discriminant
         data.extend_from_slice(&42u64.to_le_bytes()); // amount
         data.extend_from_slice(&4u32.to_le_bytes()); // recipient length
         data.extend_from_slice(b"test"); // recipient data
-        
+
         let (result, remaining) = Action::zero_copy_at(&data).unwrap();
         assert_eq!(remaining.len(), 0);
         println!("✓ MintTo: {:?}", result);
     }
-    
+
     #[test]
     fn test_pattern_matching_example() {
         // This demonstrates the exact usage pattern the user wants
         let mut actions_data = Vec::new();
-        
+
         // Create some test actions
         // Action 1: MintTo
         actions_data.push({
@@ -122,20 +127,20 @@ mod tests {
             data.extend_from_slice(b"alice");
             data
         });
-        
-        // Action 2: Update  
+
+        // Action 2: Update
         actions_data.push(vec![1u8]);
-        
+
         // Action 3: CreateSplMint
         actions_data.push(vec![2u8]);
 
         // Process each action (simulating the user's use case)
         for (i, action_data) in actions_data.iter().enumerate() {
             let (action, _) = Action::zero_copy_at(action_data).unwrap();
-            
+
             // This is what the user wants to be able to write:
             println!("Processing action {}: {:?}", i, action);
-            
+
             // In the user's real code, this would be:
             // match action {
             //     ZAction::MintTo(mint_action) => {
@@ -153,4 +158,4 @@ mod tests {
             // }
         }
     }
-}
+}