forgecode: Instructions file for Codex

Agent Guidelines

This document contains guidelines and best practices for AI agents working with this codebase.

Error Management

• Use anyhow::Result for error handling in services and repositories.
• Create domain errors using thiserror.
• Never implement From for converting domain errors, manually convert them

Writing Tests

• All tests should be written in three discrete steps:

  use pretty_assertions::assert_eq; // Always use pretty assertions
  
  fn test_foo() {
      let setup = ...; // Instantiate a fixture or setup for the test
      let actual = ...; // Execute the fixture to create an output
      let expected = ...; // Define a hand written expected result
      assert_eq!(actual, expected); // Assert that the actual result matches the expected result
  }
  

• Use pretty_assertions for better error messages.

• Use fixtures to create test data.

• Use assert_eq! for equality checks.

• Use assert!(...) for boolean checks.

• Use unwraps in test functions and anyhow::Result in fixtures.

• Keep the boilerplate to a minimum.

• Use words like fixture, actual and expected in test functions.

• Fixtures should be generic and reusable.

• Test should always be written in the same file as the source code.

• Use new, Default and derive_setters::Setters to create actual, expected and specially fixtures. For example:

  Good:

  User::default().age(12).is_happy(true).name("John")
  User::new("Job").age(12).is_happy()
  User::test() // Special test constructor
  

  Bad:

  User {name: "John".to_string(), is_happy: true, age: 12}
  User::with_name("Job") // Bad name, should stick to User::new() or User::test()
  

• Use unwrap() unless the error information is useful. Use expect instead of panic! when error message is useful. For example:

  Good:

  users.first().expect("List should not be empty")
  

  Bad:

  if let Some(user) = users.first() {
      // ...
  } else {
      panic!("List should not be empty")
  }