refactor: add more examples for cursor rules and move dev descriptions to dev.yml

Author: kieran-osgood-shopify

.cursor/rules/swift-development.mdc

@@ -21,22 +21,26 @@ alwaysApply: true
 3. **Test Issues** → `dev test` - Checks for failing tests 
 
 ### Available dev commands:
-```bash
-# Code Quality
-dev lint          # Check format & lint issues (alias: dev style)
-dev fix           # auto fixes formatting and linting issues
-
-# Building
-dev build packages    # Build ShopifyCheckoutSheetKit & ShopifyAcceleratedCheckouts
-dev build samples     # Build sample apps
-
-# Testing  
-dev test packages     # Test the packages
-dev test samples      # Test sample apps
-
-# Apollo/GraphQL
-dev apollo download_schema  # Download GraphQL schema
-dev apollo codegen         # Generate Apollo client code
+**See `dev.yml` in project root for complete list of commands and descriptions.**
+
+Key commands for verification:
+- `dev lint` (alias: `dev style`) - Check format & lint issues
+- `dev fix` - Auto-fix formatting and linting issues  
+- `dev build packages` - Build both packages
+- `dev test packages` - Run all tests
+
+## Concurrency Best Practices
+
+### DO: Use actors for thread-safe shared state
+```swift
+actor QueryCache {
+    private var cache: [String: Any] = [:]
+    private var inflightRequests: [String: Any] = [:]
+    
+    func loadCached<T>(...) async throws -> T {
+        // Safe concurrent access to shared state
+    }
+}
 ```
 
 ## Workflow Best Practices

.cursor/rules/swift-test.mdc

@@ -11,19 +11,6 @@ alwaysApply: true
 ### DO:
 - Create separate test methods for each test case
 - Use `guard` statements with `XCTFail` for unwrapping optionals
-- Write focused tests that test one thing at a time
-- Use descriptive test method names that explain what is being tested
-- Catch only one error type per test
-- Create separate test methods instead of conditional logic
-
-### DON'T:
-- Use typed catches when testing throwing expressions
-- Delete and recreate test files when debugging
-- Add boilerplate comments like "// Given", "// When", "// Then"
-
-## Code Examples
-
-### ✅ CORRECT: Unwrapping optionals
 ```swift
 func testSomething() {
     guard let result = someOptionalValue else {
@@ -33,36 +20,61 @@ func testSomething() {
     XCTAssertEqual(result, expectedValue)
 }
 ```
+- Write focused tests that test one thing at a time
+- Use descriptive test method names in the format `test_<methodName>_<withCircumstances>_<shouldExpectation>`
+```
+    func test_canTransition_fromAppleSheetPresentedState_shouldAllowPaymentAuthorizationAndInterruptAndCompleted() 
+    func test_ensureCurrencyNotChanged_withNoInitialCurrency_shouldNotThrow() 
+```
 
-### ❌ INCORRECT: Conditional test logic
-```swift
-// DON'T DO THIS
-func testSomething() {
-    if condition {
-        XCTAssertTrue(something)
-    } else {
-        XCTAssertFalse(something)
+- If a function may throw multiple types of errors, write multiple tests to capture them in isolation
+```
+func throwingFunction() {
+    if someCondition {
+        throw Error.foo
+      } else 
+      throw Error.bar
+  }
+
+  func test_throwingFunction_whenSomeConditionTrue_shouldThrowFoo() {
+    do {
+        _ = try await storefront.createCart()
+        XCTFail("Expected error to be thrown")
+    } catch {
+      guard case let error = Error.foo else {
+        XCTFail("Expected .foo")
+      }
     }
-}
+  }
+  func test_throwingFunction_whenSomeConditionTrue_shouldThrowBar(){
+    do {
+        _ = try await storefront.createCart()
+        XCTFail("Expected error to be thrown")
+    } catch {
+      guard case let error = Error.foo else {
+        XCTFail("Expected .foo")
+      }
+    }
+  }
 ```
 
-### ✅ CORRECT: Separate test methods
-```swift
-func testSomething_whenConditionTrue() {
-    // Test for true condition
-}
+## Code Examples
 
-func testSomething_whenConditionFalse() {
-    // Test for false condition
+### ✅ CORRECT: Unwrapping optionals
+```swift
+func testSomething() {
+    guard let result = someOptionalValue else {
+        XCTFail("Expected non-nil value")
+        return
+    }
+    XCTAssertEqual(result, expectedValue)
 }
 ```
 
-## Error Testing
-
-When testing throwing functions:
-- Test only ONE error type per test method
-- Avoid typed catch blocks that check for specific error types
-- Let unhandled errors fail the test naturally
+### DON'T:
+- Use typed catches when testing throwing expressions
+- Delete and recreate test files when debugging
+- Add boilerplate comments like "// Given", "// When", "// Then"
 
 ## Comments
 

dev.yml

@@ -30,29 +30,29 @@ check:
 commands:
   lint:
     aliases: [style]
-    desc: Check Format & Lint issues
+    desc: Check format and lint issues across all Swift files using SwiftLint and SwiftFormat
     run: scripts/lint
   fix:
-    desc: Autofix Format & Lint issues
+    desc: Automatically fix format and lint issues where possible
     run: scripts/lint fix
   build:
     subcommands:
       packages:
-        desc: Build the Package
+        desc: Build both ShopifyCheckoutSheetKit and ShopifyAcceleratedCheckouts packages
         run: |
           ./scripts/xcode_run build ShopifyCheckoutSheetKit
           ./scripts/xcode_run build ShopifyAcceleratedCheckouts
       samples:
-        desc: Build the Samples
+        desc: Build all sample applications to verify integration
         run: ./scripts/build_samples
   test:
     subcommands:
       packages:
-        desc: Test the Packages
+        desc: Run all unit and integration tests for the packages
         run: |
           ./scripts/xcode_run test ShopifyCheckoutSheetKit-Package
       samples:
-        desc: Test the Samples
+        desc: Run tests for sample applications
         run: ./scripts/test_samples
 
   apollo:
@@ -68,7 +68,7 @@ commands:
           rover graph introspect https://$DOMAIN/api/$API_VERSION/graphql --header="X-Shopify-Storefront-Access-Token: $TOKEN" --output schema.$API_VERSION.graphqls
 
       codegen:
-        desc: Generate Apollo Client
+        desc: Generate Apollo Client models and request functions for sample app
         run: |
           cd ./Samples/ShopifyAcceleratedCheckoutsApp/
           ./apollo-ios-cli generate