WIP: add more tests to repo-actor crate

crates/forge-forgejo/src/tests.rs

@@ -587,7 +587,6 @@ mod forgejo {
         }
     }
     mod given {
-        #![allow(dead_code)]
 
         use std::collections::HashMap;
 
@@ -727,11 +726,6 @@ mod forgejo {
             config::WebhookId::new(a_name())
         }
 
-        pub fn a_github_webhook_id() -> i64 {
-            use rand::RngCore as _;
-            rand::thread_rng().next_u32().into()
-        }
-
         pub fn a_branch_name() -> config::BranchName {
             config::BranchName::new(a_name())
         }
@@ -770,21 +764,6 @@ mod forgejo {
             git::Commit::new(a_commit_sha(), a_commit_message())
         }
 
-        pub fn a_commit_with_message(message: &git::commit::Message) -> git::Commit {
-            git::Commit::new(a_commit_sha(), message.to_owned())
-        }
-
-        pub fn a_commit_with_sha(sha: &git::commit::Sha) -> git::Commit {
-            git::Commit::new(sha.to_owned(), a_commit_message())
-        }
-
-        pub fn a_commit_with(
-            sha: &git::commit::Sha,
-            message: &git::commit::Message,
-        ) -> git::Commit {
-            git::Commit::new(sha.to_owned(), message.to_owned())
-        }
-
         pub fn a_commit_message() -> git::commit::Message {
             git::commit::Message::new(a_name())
         }
@@ -793,14 +772,6 @@ mod forgejo {
             git::commit::Sha::new(a_name())
         }
 
-        pub fn a_webhook_push(
-            sha: &git::commit::Sha,
-            message: &git::commit::Message,
-        ) -> config::webhook::Push {
-            let branch = a_branch_name();
-            config::webhook::Push::new(branch, sha.to_string(), message.to_string())
-        }
-
         pub fn a_filesystem() -> kxio::fs::FileSystem {
             kxio::fs::temp().unwrap_or_else(|e| panic!("{}", e))
         }

crates/git/Cargo.toml

@@ -50,7 +50,7 @@ thiserror = { workspace = true }
 actix = { workspace = true }
 # actix-rt = { workspace = true }
 # tokio = { workspace = true }
-#
+
 [dev-dependencies]
 # Testing
 assert2 = { workspace = true }

crates/git/src/repository/mod.rs

@@ -1,10 +1,14 @@
 //
 #[cfg(test)]
 mod mock;
+#[cfg(test)]
+pub use mock::MockRepository;
+#[cfg(test)]
+pub use open::MockOpenRepository;
+
 mod open;
 mod real;
-#[cfg(test)]
+pub mod test;
-mod test;
 
 #[cfg(test)]
 mod tests;
@@ -12,21 +16,15 @@ mod tests;
 use git_next_config as config;
 use git_next_config::GitDir;
 
-#[cfg(test)]
-pub use mock::MockRepository;
-#[cfg(test)]
 pub use open::otest::OnFetch;
-#[cfg(test)]
 pub use open::otest::OnPush;
-#[cfg(test)]
+
-pub use open::MockOpenRepository;
 pub use open::OpenRepository;
 pub use open::OpenRepositoryLike;
 pub use open::RealOpenRepository;
 pub use real::RealRepository;
 use tracing::info;
 
-#[cfg(test)]
 use crate::repository::test::TestRepository;
 
 use crate::validation::repo::validate_repo;
@@ -39,7 +37,6 @@ pub enum Repository {
     Real,
     #[cfg(test)]
     Mock(MockRepository),
-    #[cfg(test)]
     Test(TestRepository),
 }
 
@@ -52,9 +49,8 @@ pub fn mock() -> MockRepository {
     MockRepository::new()
 }
 
-#[cfg(test)]
+pub fn test(fs: kxio::fs::FileSystem) -> TestRepository {
-pub const fn test(fs: kxio::fs::FileSystem) -> TestRepository {
+    TestRepository::new(false, fs, Default::default(), Default::default())
-    TestRepository::new(false, fs, vec![], vec![])
 }
 
 // #[cfg(test)]
@@ -92,10 +88,10 @@ impl std::ops::Deref for Repository {
     fn deref(&self) -> &Self::Target {
         match self {
             Self::Real => &real::RealRepository,
+            Self::Test(test_repository) => test_repository,
+
             #[cfg(test)]
             Self::Mock(mock_repository) => mock_repository,
-            #[cfg(test)]
-            Self::Test(test_repository) => test_repository,
         }
     }
 }

crates/git/src/repository/open/mod.rs

@@ -1,12 +1,10 @@
 //
-#![allow(dead_code)]
 
 #[cfg(test)]
 mod tests;
 
 pub mod oreal;
 
-#[cfg(test)]
 pub mod otest;
 
 #[cfg(test)]
@@ -23,7 +21,6 @@ use git_next_config as config;
 #[cfg(test)]
 pub use omock::MockOpenRepository;
 pub use oreal::RealOpenRepository;
-#[cfg(test)]
 pub use otest::TestOpenRepository;
 
 #[derive(Clone, Debug)]
@@ -32,6 +29,15 @@ pub enum OpenRepository {
     ///
     /// This variant is the normal implementation for use in production code.
     Real(RealOpenRepository),
+
+    /// A real git repository, but with preprogrammed responses to network access.
+    ///
+    /// This variant is for use only in testing. Requests to methods
+    /// that would require network access, such as to the git remote
+    /// server will result in an error, unless a predefined change
+    /// has been scheduled for that request.
+    Test(TestOpenRepository),
+
     /// A fake git repository.
     ///
     /// This variant has no on-disk presense, and only fakes some of
@@ -40,14 +46,6 @@ pub enum OpenRepository {
     /// that instead.
     #[cfg(test)]
     Mock(git::repository::MockOpenRepository), // TODO: (#38) contain a mock model of a repo
-    /// A real git repository, but with preprogrammed responses to network access.
-    ///
-    /// This variant is for use only in testing. Requests to methods
-    /// that would require network access, such as to the git remote
-    /// server will result in an error, unless a predefined change
-    /// has been scheduled for that request.
-    #[cfg(test)]
-    Test(TestOpenRepository),
 }
 
 pub fn real(gix_repo: gix::Repository) -> OpenRepository {
@@ -57,29 +55,21 @@ pub fn real(gix_repo: gix::Repository) -> OpenRepository {
 }
 
 #[cfg(not(tarpaulin_include))] // don't test mocks
-#[cfg(test)]
-pub const fn mock(mock: git::repository::MockOpenRepository) -> OpenRepository {
-    OpenRepository::Mock(mock)
-}
-
-#[cfg(not(tarpaulin_include))] // don't test mocks
-#[cfg(test)]
 pub fn test(
     gitdir: &config::GitDir,
     fs: kxio::fs::FileSystem,
-    on_fetch: Vec<otest::OnFetch>,
+    on_fetch: Arc<Mutex<Vec<otest::OnFetch>>>,
-    on_push: Vec<otest::OnPush>,
+    on_push: Arc<Mutex<Vec<otest::OnPush>>>,
 ) -> OpenRepository {
     OpenRepository::Test(TestOpenRepository::new(gitdir, fs, on_fetch, on_push))
 }
 
 #[cfg(not(tarpaulin_include))] // don't test mocks
-#[cfg(test)]
 pub fn test_bare(
     gitdir: &config::GitDir,
     fs: kxio::fs::FileSystem,
-    on_fetch: Vec<otest::OnFetch>,
+    on_fetch: Arc<Mutex<Vec<otest::OnFetch>>>,
-    on_push: Vec<otest::OnPush>,
+    on_push: Arc<Mutex<Vec<otest::OnPush>>>,
 ) -> OpenRepository {
     OpenRepository::Test(TestOpenRepository::new_bare(gitdir, fs, on_fetch, on_push))
 }
@@ -118,10 +108,10 @@ impl std::ops::Deref for OpenRepository {
     fn deref(&self) -> &Self::Target {
         match self {
             Self::Real(real) => real,
+            Self::Test(test) => test,
+
             #[cfg(test)]
             Self::Mock(mock) => mock,
-            #[cfg(test)]
-            Self::Test(test) => test,
         }
     }
 }

crates/git/src/repository/open/otest.rs

@@ -1,16 +1,13 @@
 //
 use crate as git;
-use derive_more::Constructor;
+use derive_more::{Constructor, Deref};
 use git_next_config as config;
 
 use std::{
-    cell::Cell,
     path::Path,
-    sync::{Arc, Mutex},
+    sync::{Arc, Mutex, RwLock},
 };
 
-use assert2::let_assert;
-
 pub type OnFetchFn =
     fn(&config::RepoBranches, &config::GitDir, &kxio::fs::FileSystem) -> git::fetch::Result<()>;
 #[derive(Clone, Debug, Constructor)]
@@ -64,12 +61,10 @@ impl OnPush {
 
 #[derive(Clone, Debug)]
 pub struct TestOpenRepository {
-    gitdir: config::GitDir,
+    on_fetch: Arc<Mutex<Vec<OnFetch>>>,
-    fs: kxio::fs::FileSystem,
+    fetch_counter: Arc<RwLock<usize>>,
-    on_fetch: Vec<OnFetch>,
+    on_push: Arc<Mutex<Vec<OnPush>>>,
-    fetch_counter: Cell<usize>,
+    push_counter: Arc<RwLock<usize>>,
-    on_push: Vec<OnPush>,
-    push_counter: Cell<usize>,
     real: git::repository::RealOpenRepository,
 }
 impl git::repository::OpenRepositoryLike for TestOpenRepository {
@@ -82,12 +77,24 @@ impl git::repository::OpenRepositoryLike for TestOpenRepository {
     }
 
     fn fetch(&self) -> Result<(), git::fetch::Error> {
-        let i = self.fetch_counter.get();
+        let i: usize = *self
+            .fetch_counter
+            .read()
+            .map_err(|_| git::fetch::Error::Lock)?
+            .deref();
         eprintln!("Fetch: {i}");
-        self.fetch_counter.set(i + 1);
+        self.fetch_counter
-        self.on_fetch.get(i).map(|f| f.invoke()).unwrap_or_else(|| {
+            .write()
+            .map_err(|_| git::fetch::Error::Lock)
+            .map(|mut c| *c += 1)?;
+        self.on_fetch
+            .lock()
+            .map_err(|_| git::fetch::Error::Lock)
+            .map(|a| {
+                a.get(i).map(|f| f.invoke()).unwrap_or_else(|| {
                     unimplemented!("Unexpected fetch");
                 })
+            })?
     }
 
     fn push(
@@ -97,14 +104,26 @@ impl git::repository::OpenRepositoryLike for TestOpenRepository {
         to_commit: &git::GitRef,
         force: &git::push::Force,
     ) -> git::push::Result<()> {
-        let i = self.push_counter.get();
+        let i: usize = *self
-        self.push_counter.set(i + 1);
+            .push_counter
+            .read()
+            .map_err(|_| git::fetch::Error::Lock)?
+            .deref();
+        eprintln!("Push: {i}");
+        self.push_counter
+            .write()
+            .map_err(|_| git::fetch::Error::Lock)
+            .map(|mut c| *c += 1)?;
         self.on_push
-            .get(i)
+            .lock()
+            .map_err(|_| git::fetch::Error::Lock)
+            .map(|a| {
+                a.get(i)
                     .map(|f| f.invoke(repo_details, branch_name, to_commit, force))
                     .unwrap_or_else(|| {
                         unimplemented!("Unexpected push");
                     })
+            })?
     }
 
     fn commit_log(
@@ -127,38 +146,36 @@ impl TestOpenRepository {
     pub fn new(
         gitdir: &config::GitDir,
         fs: kxio::fs::FileSystem,
-        on_fetch: Vec<OnFetch>,
+        on_fetch: Arc<Mutex<Vec<OnFetch>>>,
-        on_push: Vec<OnPush>,
+        on_push: Arc<Mutex<Vec<OnPush>>>,
     ) -> Self {
         let pathbuf = fs.base().join(gitdir.to_path_buf());
-        let_assert!(Ok(gix) = gix::init(pathbuf), "git init");
+        #[allow(clippy::expect_used)]
+        let gix = gix::init(pathbuf).expect("git init");
         Self::write_origin(gitdir, &fs);
         Self {
-            gitdir: gitdir.clone(),
-            fs,
             on_fetch,
-            fetch_counter: Cell::new(0),
+            fetch_counter: Arc::new(RwLock::new(0)),
             on_push,
-            push_counter: Cell::new(0),
+            push_counter: Arc::new(RwLock::new(0)),
             real: git::repository::RealOpenRepository::new(Arc::new(Mutex::new(gix))),
         }
     }
     pub fn new_bare(
         gitdir: &config::GitDir,
         fs: kxio::fs::FileSystem,
-        on_fetch: Vec<OnFetch>,
+        on_fetch: Arc<Mutex<Vec<OnFetch>>>,
-        on_push: Vec<OnPush>,
+        on_push: Arc<Mutex<Vec<OnPush>>>,
     ) -> Self {
         let pathbuf = fs.base().join(gitdir.to_path_buf());
-        let_assert!(Ok(gix) = gix::init_bare(pathbuf), "git init bare");
+        #[allow(clippy::expect_used)]
+        let gix = gix::init_bare(pathbuf).expect("git init bare");
         Self::write_origin(gitdir, &fs);
         Self {
-            gitdir: gitdir.clone(),
-            fs,
             on_fetch,
-            fetch_counter: Cell::new(0),
+            fetch_counter: Arc::new(RwLock::new(0)),
             on_push,
-            push_counter: Cell::new(0),
+            push_counter: Arc::new(RwLock::new(0)),
             real: git::repository::RealOpenRepository::new(Arc::new(Mutex::new(gix))),
         }
     }

crates/git/src/repository/test.rs

@@ -1,3 +1,5 @@
+use std::sync::{Arc, Mutex};
+
 //
 use derive_more::Constructor;
 
@@ -9,16 +11,16 @@ use git_next_config as config;
 pub struct TestRepository {
     is_bare: bool,
     fs: kxio::fs::FileSystem,
-    on_fetch: Vec<git::repository::open::otest::OnFetch>,
+    on_fetch: Arc<Mutex<Vec<git::repository::open::otest::OnFetch>>>,
-    on_push: Vec<git::repository::open::otest::OnPush>,
+    on_push: Arc<Mutex<Vec<git::repository::open::otest::OnPush>>>,
 }
 impl TestRepository {
     pub fn on_fetch(&mut self, on_fetch: git::repository::OnFetch) {
-        self.on_fetch.push(on_fetch);
+        let _ = self.on_fetch.lock().map(|mut a| a.push(on_fetch));
     }
 
     pub fn on_push(&mut self, on_push: git::repository::OnPush) {
-        self.on_push.push(on_push);
+        let _ = self.on_push.lock().map(|mut a| a.push(on_push));
     }
 
     pub const fn fs(&self) -> &kxio::fs::FileSystem {

crates/git/src/tests.rs

@@ -210,7 +210,6 @@ mod repo_details {
     }
 }
 pub mod given {
-    #![allow(dead_code)]
     use std::path::PathBuf;
 
     //
@@ -221,28 +220,12 @@ pub mod given {
     };
     use config::{
         BranchName, ForgeAlias, ForgeConfig, ForgeType, GitDir, RepoAlias, RepoBranches,
-        RepoConfig, ServerRepoConfig, WebhookAuth, WebhookId,
+        RepoConfig, ServerRepoConfig,
     };
     use git_next_config as config;
 
-    use rand::RngCore;
-
     use crate::RepoDetails;
 
-    pub fn a_webhook_auth() -> WebhookAuth {
-        WebhookAuth::generate()
-    }
-
-    pub enum Header {
-        Valid(WebhookAuth, config::webhook::message::Body),
-        Missing,
-        Invalid,
-    }
-
-    pub fn a_webhook_message_body() -> config::webhook::message::Body {
-        config::webhook::message::Body::new(a_name())
-    }
-
     pub fn repo_branches() -> RepoBranches {
         RepoBranches::new(
             format!("main-{}", a_name()),
@@ -259,21 +242,6 @@ pub mod given {
         RepoAlias::new(a_name())
     }
 
-    pub fn a_network() -> kxio::network::MockNetwork {
-        kxio::network::MockNetwork::new()
-    }
-
-    pub fn a_webhook_url(
-        forge_alias: &ForgeAlias,
-        repo_alias: &RepoAlias,
-    ) -> git_next_config::server::WebhookUrl {
-        config::server::Webhook::new(a_name()).url(forge_alias, repo_alias)
-    }
-
-    pub fn any_webhook_url() -> git_next_config::server::WebhookUrl {
-        a_webhook_url(&a_forge_alias(), &a_repo_alias())
-    }
-
     pub fn a_pathbuf() -> PathBuf {
         PathBuf::from(given::a_name())
     }
@@ -291,14 +259,6 @@ pub mod given {
         generate(5)
     }
 
-    pub fn a_webhook_id() -> WebhookId {
-        WebhookId::new(a_name())
-    }
-
-    pub fn a_github_webhook_id() -> i64 {
-        rand::thread_rng().next_u32().into()
-    }
-
     pub fn a_branch_name() -> BranchName {
         BranchName::new(a_name())
     }
@@ -349,10 +309,6 @@ pub mod given {
         git::Commit::new(sha.to_owned(), a_commit_message())
     }
 
-    pub fn a_commit_with(sha: &git::commit::Sha, message: &git::commit::Message) -> git::Commit {
-        git::Commit::new(sha.to_owned(), message.to_owned())
-    }
-
     pub fn a_commit_message() -> git::commit::Message {
         git::commit::Message::new(a_name())
     }

crates/repo-actor/Cargo.toml

@@ -42,12 +42,19 @@ ulid = { workspace = true }
 
 # boilerplate
 derive_more = { workspace = true }
+thiserror = { workspace = true }
 
 # Actors
 actix = { workspace = true }
 actix-rt = { workspace = true }
 tokio = { workspace = true }
 
+[dev-dependencies]
+# Testing
+assert2 = { workspace = true }
+rand = { workspace = true }
+pretty_assertions = { workspace = true }
+
 [lints.clippy]
 nursery = { level = "warn", priority = -1 }
 # pedantic = "warn"

crates/repo-actor/src/branch.rs

@@ -1,78 +1,67 @@
 //
-use actix::prelude::*;
+use crate as actor;
-
 use git_next_config as config;
 use git_next_git as git;
+
+use derive_more::Display;
 use tracing::{info, warn};
 
-use crate::{MessageToken, ValidateRepo};
-
-use std::time::Duration;
-
 // advance next to the next commit towards the head of the dev branch
 #[tracing::instrument(fields(next), skip_all)]
 pub async fn advance_next(
-    next: git::Commit,
+    next: &git::Commit,
-    dev_commit_history: Vec<git::Commit>,
+    dev_commit_history: &[git::Commit],
     repo_details: git::RepoDetails,
     repo_config: config::RepoConfig,
     repository: git::OpenRepository,
-    addr: Addr<super::RepoActor>,
+    message_token: actor::MessageToken,
-    message_token: MessageToken,
+) -> Result<actor::MessageToken> {
-) {
+    let commit =
-    let next_commit = find_next_commit_on_dev(next, dev_commit_history);
+        find_next_commit_on_dev(next, dev_commit_history).ok_or_else(|| Error::NextAtDev)?;
-    let Some(commit) = next_commit else {
+    validate_commit_message(commit.message())?;
-        warn!("No commits to advance next to");
-        return;
-    };
-    if let Some(problem) = validate_commit_message(commit.message()) {
-        warn!("Can't advance next to commit '{}': {}", commit, problem);
-        return;
-    }
     info!("Advancing next to commit '{}'", commit);
-    if let Err(err) = git::push::reset(
+    git::push::reset(
         &repository,
         &repo_details,
         &repo_config.branches().next(),
         &commit.into(),
         &git::push::Force::No,
-    ) {
+    )?;
-        warn!(?err, "Failed")
+    Ok(message_token)
-    }
-    tokio::time::sleep(Duration::from_secs(10)).await;
-    addr.do_send(ValidateRepo { message_token })
 }
 
 #[tracing::instrument]
-fn validate_commit_message(message: &git::commit::Message) -> Option<String> {
+fn validate_commit_message(message: &git::commit::Message) -> Result<()> {
     let message = &message.to_string();
     if message.to_ascii_lowercase().starts_with("wip") {
-        return Some("Is Work-In-Progress".to_string());
+        return Err(Error::IsWorkInProgress);
     }
     match git_conventional::Commit::parse(message) {
         Ok(commit) => {
             info!(?commit, "Pass");
-            None
+            Ok(())
         }
         Err(err) => {
             warn!(?err, "Fail");
-            Some(err.kind().to_string())
+            Err(Error::InvalidCommitMessage {
+                reason: err.kind().to_string(),
+            })
         }
     }
 }
 
 pub fn find_next_commit_on_dev(
-    next: git::Commit,
+    next: &git::Commit,
-    dev_commit_history: Vec<git::Commit>,
+    dev_commit_history: &[git::Commit],
 ) -> Option<git::Commit> {
-    let mut next_commit: Option<git::Commit> = None;
+    let mut next_commit: Option<&git::Commit> = None;
-    for commit in dev_commit_history.into_iter() {
+    for commit in dev_commit_history.iter() {
         if commit == next {
             break;
         };
         next_commit.replace(commit);
     }
-    next_commit
+    next_commit.cloned()
 }
 
 // advance main branch to the commit 'next'
@@ -82,15 +71,30 @@ pub async fn advance_main(
     repo_details: &git::RepoDetails,
     repo_config: &config::RepoConfig,
     repository: &git::OpenRepository,
-) {
+) -> Result<()> {
     info!("Advancing main to next");
-    if let Err(err) = git::push::reset(
+    git::push::reset(
         repository,
         repo_details,
         &repo_config.branches().main(),
         &next.into(),
         &git::push::Force::No,
-    ) {
+    )?;
-        warn!(?err, "Failed")
+    Ok(())
-    };
+}
+
+pub type Result<T> = core::result::Result<T, Error>;
+#[derive(Debug, thiserror::Error, Display)]
+pub enum Error {
+    #[display("push: {}", 0)]
+    Push(#[from] git::push::Error),
+
+    #[display("no commits to advance next to")]
+    NextAtDev,
+
+    #[display("commit is a Work-in-progress")]
+    IsWorkInProgress,
+
+    #[display("commit message is not in conventional commit format: {reason}")]
+    InvalidCommitMessage { reason: String },
 }

crates/repo-actor/src/lib.rs

@@ -259,15 +259,27 @@ impl Handler<StartMonitoring> for RepoActor {
                 .wait(ctx);
         } else if dev_ahead_of_next {
             if let Some(repository) = self.open_repository.clone() {
-                branch::advance_next(
+                let repo_details = self.repo_details.clone();
-                    msg.next,
+                let message_token = self.message_token;
-                    msg.dev_commit_history,
+                async move {
-                    self.repo_details.clone(),
+                    match branch::advance_next(
+                        &msg.next,
+                        &msg.dev_commit_history,
+                        repo_details,
                         repo_config,
                         repository,
-                    addr,
+                        message_token,
-                    self.message_token,
                     )
+                    .await
+                    {
+                        Ok(message_token) => {
+                            // pause to allow any CI checks to be started
+                            tokio::time::sleep(Duration::from_secs(10)).await;
+                            addr.do_send(ValidateRepo { message_token })
+                        }
+                        Err(err) => warn!("advance next: {err}"),
+                    }
+                }
                 .in_current_span()
                 .into_actor(self)
                 .wait(ctx);
@@ -312,12 +324,16 @@ impl Handler<AdvanceMainTo> for RepoActor {
         let addr = ctx.address();
         let message_token = self.message_token;
         async move {
-            branch::advance_main(msg.0, &repo_details, &repo_config, &repository).await;
+            match branch::advance_main(msg.0, &repo_details, &repo_config, &repository).await {
-            match repo_config.source() {
+                Err(err) => {
+                    warn!("advance main: {err}");
+                }
+                Ok(_) => match repo_config.source() {
                     git_next_config::RepoConfigSource::Repo => addr.do_send(LoadConfigFromRepo),
                     git_next_config::RepoConfigSource::Server => {
                         addr.do_send(ValidateRepo { message_token })
                     }
+                },
             }
         }
         .in_current_span()

crates/repo-actor/src/tests.rs

@@ -1,34 +1,673 @@
 //
-use super::*;
+#![allow(unused_imports)] // TODO remove this
-mod branch {
+
-    use super::super::branch::*;
+use crate as actor;
+use git_next_config as config;
+use git_next_forge as forge;
+use git_next_git as git;
+
 use super::*;
 
+use assert2::let_assert;
+
+type TestResult = Result<(), Box<dyn std::error::Error>>;
+
+mod branch {
+    use super::*;
+
+    mod advance_next {
+        use super::*;
+        mod when_at_dev {
+            // next and dev branches are the same
+            use super::*;
+            #[tokio::test]
+            async fn should_not_push() -> TestResult {
+                let next = given::a_commit();
+                let dev_commit_history = &[next.clone()];
+                let fs = given::a_filesystem();
+                let repo_details = given::repo_details(&fs);
+                let repo_config = given::a_repo_config();
+                let (repository, _, _) = given::an_open_repository(&fs);
+                // no on_push defined - so any call to push will cause an error
+                let message_token = given::a_message_token();
+                let_assert!(
+                    Err(err) = actor::branch::advance_next(
+                        &next,
+                        dev_commit_history,
+                        repo_details,
+                        repo_config,
+                        repository,
+                        message_token,
+                    )
+                    .await
+                );
+                eprintln!("Got: {err}");
+                assert!(matches!(err, actor::branch::Error::NextAtDev));
+                Ok(())
+            }
+        }
+        mod can_advance {
+            // dev has at least one commit ahead of next
+            use super::*;
+            mod to_wip_commit {
+                // commit on dev is either invalid message or a WIP
+                use super::*;
+                #[tokio::test]
+                async fn should_not_push() -> TestResult {
+                    let next = given::a_commit();
+                    let dev = given::a_commit_with_message(&git::commit::Message::new(
+                        "wip: test: message".to_string(),
+                    ));
+                    let dev_commit_history = &[dev.clone(), next.clone()];
+                    let fs = given::a_filesystem();
+                    let repo_details = given::repo_details(&fs);
+                    let repo_config = given::a_repo_config();
+                    let (repository, _, _) = given::an_open_repository(&fs);
+                    // no on_push defined - so any call to push will cause an error
+                    let message_token = given::a_message_token();
+                    let_assert!(
+                        Err(err) = actor::branch::advance_next(
+                            &next,
+                            dev_commit_history,
+                            repo_details,
+                            repo_config,
+                            repository,
+                            message_token,
+                        )
+                        .await
+                    );
+                    eprintln!("Got: {err}");
+                    assert!(matches!(err, actor::branch::Error::IsWorkInProgress));
+                    Ok(())
+                }
+            }
+            mod to_invalid_commit {
+                // commit on dev is either invalid message or a WIP
+                use super::*;
+                #[tokio::test]
+                async fn should_not_push_and_error() -> TestResult {
+                    let next = given::a_commit();
+                    let dev = given::a_commit();
+                    let dev_commit_history = &[dev.clone(), next.clone()];
+                    let fs = given::a_filesystem();
+                    let repo_details = given::repo_details(&fs);
+                    let repo_config = given::a_repo_config();
+                    let (repository, _, _) = given::an_open_repository(&fs);
+                    // no on_push defined - so any call to push will cause an error
+                    let message_token = given::a_message_token();
+                    let_assert!(
+                        Err(err) = actor::branch::advance_next(
+                            &next,
+                            dev_commit_history,
+                            repo_details,
+                            repo_config,
+                            repository,
+                            message_token,
+                        )
+                        .await
+                    );
+                    eprintln!("Got: {err}");
+                    assert!(matches!(
+                        err,
+                        actor::branch::Error::InvalidCommitMessage{reason}
+                        if reason == "Missing type in the commit summary, expected `type: description`"
+                    ));
+                    Ok(())
+                }
+            }
+            mod to_valid_commit {
+                // commit on dev is valid conventional commit message
+                use super::*;
+                mod push_is_err {
+                    use git::repository::{OnFetch, OnPush};
+
+                    // the git push command fails
+                    use super::*;
+                    #[tokio::test]
+                    async fn should_error() -> TestResult {
+                        let next = given::a_commit();
+                        let dev = given::a_commit_with_message(&git::commit::Message::new(
+                            "test: message".to_string(),
+                        ));
+                        let dev_commit_history = &[dev.clone(), next.clone()];
+                        let fs = given::a_filesystem();
+                        let repo_details = given::repo_details(&fs);
+                        let repo_config = given::a_repo_config();
+                        let (repository, gitdir, mut test_repository) =
+                            given::an_open_repository(&fs);
+                        let repo_branches = repo_config.branches();
+                        test_repository.on_fetch(OnFetch::new(
+                            repo_branches.clone(),
+                            gitdir.clone(),
+                            fs.clone(),
+                            |_, _, _| git::fetch::Result::Ok(()),
+                        ));
+                        test_repository.on_push(OnPush::new(
+                            repo_branches.clone(),
+                            gitdir,
+                            fs,
+                            |_, _, _, _, _, _, _| git::push::Result::Err(git::push::Error::Lock),
+                        ));
+                        let message_token = given::a_message_token();
+                        let_assert!(
+                            Err(err) = actor::branch::advance_next(
+                                &next,
+                                dev_commit_history,
+                                repo_details,
+                                repo_config,
+                                repository,
+                                message_token,
+                            )
+                            .await
+                        );
+                        eprintln!("Got: {err:?}");
+                        assert!(matches!(
+                            err,
+                            actor::branch::Error::Push(git::push::Error::Lock)
+                        ));
+                        Ok(())
+                    }
+                }
+                mod push_is_ok {
+                    // the git push command succeeds
+                    use git_next_git::repository::{OnFetch, OnPush};
+
+                    // the git push command fails
+                    use super::*;
+                    #[tokio::test]
+                    async fn should_ok() -> TestResult {
+                        let next = given::a_commit();
+                        let dev = given::a_commit_with_message(&git::commit::Message::new(
+                            "test: message".to_string(),
+                        ));
+                        let dev_commit_history = &[dev.clone(), next.clone()];
+                        let fs = given::a_filesystem();
+                        let repo_details = given::repo_details(&fs);
+                        let repo_config = given::a_repo_config();
+                        let (repository, gitdir, mut test_repository) =
+                            given::an_open_repository(&fs);
+                        let repo_branches = repo_config.branches();
+                        test_repository.on_fetch(OnFetch::new(
+                            repo_branches.clone(),
+                            gitdir.clone(),
+                            fs.clone(),
+                            |_, _, _| git::fetch::Result::Ok(()),
+                        ));
+                        test_repository.on_push(OnPush::new(
+                            repo_branches.clone(),
+                            gitdir,
+                            fs,
+                            |_, _, _, _, _, _, _| git::push::Result::Ok(()),
+                        ));
+                        let message_token = given::a_message_token();
+                        let_assert!(
+                            Ok(mt) = actor::branch::advance_next(
+                                &next,
+                                dev_commit_history,
+                                repo_details,
+                                repo_config,
+                                repository,
+                                message_token,
+                            )
+                            .await
+                        );
+                        eprintln!("Got: {mt:?}");
+                        assert_eq!(mt, message_token);
+                        Ok(())
+                    }
+                }
+            }
+        }
+    }
+    mod advance_main {
+        use git::repository::{OnFetch, OnPush};
+
+        use super::*;
+        #[tokio::test]
+        async fn push_is_error_should_error() {
+            let commit = given::a_commit();
+            let fs = given::a_filesystem();
+            let repo_details = given::repo_details(&fs);
+            let repo_config = given::a_repo_config();
+            let (open_repository, gitdir, mut test_repository) = given::an_open_repository(&fs);
+            let repo_branches = repo_config.branches();
+            test_repository.on_fetch(OnFetch::new(
+                repo_branches.clone(),
+                gitdir.clone(),
+                fs.clone(),
+                |_, _, _| git::fetch::Result::Ok(()),
+            ));
+            test_repository.on_push(OnPush::new(
+                repo_branches.clone(),
+                gitdir,
+                fs,
+                |_, _, _, _, _, _, _| git::push::Result::Err(git::push::Error::Lock),
+            ));
+            let_assert!(
+                Err(err) = actor::branch::advance_main(
+                    commit,
+                    &repo_details,
+                    &repo_config,
+                    &open_repository
+                )
+                .await
+            );
+            assert!(matches!(
+                err,
+                actor::branch::Error::Push(git::push::Error::Lock)
+            ));
+        }
+        #[tokio::test]
+        async fn push_is_ok_should_ok() {
+            let commit = given::a_commit();
+            let fs = given::a_filesystem();
+            let repo_details = given::repo_details(&fs);
+            let repo_config = given::a_repo_config();
+            let (open_repository, gitdir, mut test_repository) = given::an_open_repository(&fs);
+            let repo_branches = repo_config.branches();
+            test_repository.on_fetch(OnFetch::new(
+                repo_branches.clone(),
+                gitdir.clone(),
+                fs.clone(),
+                |_, _, _| git::fetch::Result::Ok(()),
+            ));
+            test_repository.on_push(OnPush::new(
+                repo_branches.clone(),
+                gitdir,
+                fs,
+                |_, _, _, _, _, _, _| git::push::Result::Ok(()),
+            ));
+            let_assert!(
+                Ok(_) = actor::branch::advance_main(
+                    commit,
+                    &repo_details,
+                    &repo_config,
+                    &open_repository
+                )
+                .await
+            );
+        }
+    }
     #[actix_rt::test]
     async fn test_find_next_commit_on_dev() {
-        let next = git::Commit::new(
+        let next = given::a_commit();
-            git::commit::Sha::new("current-next".to_string()),
+        let expected = given::a_commit();
-            git::commit::Message::new("foo".to_string()),
-        );
-        let expected = git::Commit::new(
-            git::commit::Sha::new("dev-next".to_string()),
-            git::commit::Message::new("next-should-go-here".to_string()),
-        );
         let dev_commit_history = vec![
-            git::Commit::new(
+            given::a_commit(), // dev HEAD
-                git::commit::Sha::new("dev".to_string()),
-                git::commit::Message::new("future".to_string()),
-            ),
             expected.clone(),
-            next.clone(),
+            next.clone(),      // next - advancing towards dev HEAD
-            git::Commit::new(
+            given::a_commit(), // parent of next
-                git::commit::Sha::new("current-main".to_string()),
-                git::commit::Message::new("history".to_string()),
-            ),
         ];
 
-        let next_commit = find_next_commit_on_dev(next, dev_commit_history);
+        let next_commit = actor::branch::find_next_commit_on_dev(&next, &dev_commit_history);
 
         assert_eq!(next_commit, Some(expected), "Found the wrong commit");
     }
 }
+pub mod given {
+    #![allow(dead_code)] // TODO: remove this
+    #![allow(unused_imports)] // TODO: remove this
+
+    use git_next_git::repository::RepositoryLike as _;
+    use rand::RngCore;
+    use std::path::PathBuf;
+
+    use super::*;
+    use config::{
+        BranchName, ForgeAlias, ForgeConfig, ForgeType, GitDir, RepoAlias, RepoBranches,
+        RepoConfig, ServerRepoConfig, WebhookAuth, WebhookId,
+    };
+    use git::RepoDetails;
+
+    pub fn a_webhook_auth() -> WebhookAuth {
+        WebhookAuth::generate()
+    }
+
+    pub enum Header {
+        Valid(WebhookAuth, config::webhook::message::Body),
+        Missing,
+        Invalid,
+    }
+
+    pub fn a_webhook_message_body() -> config::webhook::message::Body {
+        config::webhook::message::Body::new(a_name())
+    }
+
+    pub fn repo_branches() -> RepoBranches {
+        RepoBranches::new(
+            format!("main-{}", a_name()),
+            format!("next-{}", a_name()),
+            format!("dev-{}", a_name()),
+        )
+    }
+
+    pub fn a_forge_alias() -> ForgeAlias {
+        ForgeAlias::new(a_name())
+    }
+
+    pub fn a_repo_alias() -> RepoAlias {
+        RepoAlias::new(a_name())
+    }
+
+    pub fn a_network() -> kxio::network::MockNetwork {
+        kxio::network::MockNetwork::new()
+    }
+
+    pub fn a_webhook_url(
+        forge_alias: &ForgeAlias,
+        repo_alias: &RepoAlias,
+    ) -> git_next_config::server::WebhookUrl {
+        config::server::Webhook::new(a_name()).url(forge_alias, repo_alias)
+    }
+
+    pub fn any_webhook_url() -> git_next_config::server::WebhookUrl {
+        a_webhook_url(&a_forge_alias(), &a_repo_alias())
+    }
+
+    pub fn a_pathbuf() -> PathBuf {
+        PathBuf::from(given::a_name())
+    }
+
+    pub fn a_name() -> String {
+        use rand::Rng;
+        use std::iter;
+
+        fn generate(len: usize) -> String {
+            const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+            let mut rng = rand::thread_rng();
+            let one_char = || CHARSET[rng.gen_range(0..CHARSET.len())] as char;
+            iter::repeat_with(one_char).take(len).collect()
+        }
+        generate(5)
+    }
+
+    pub fn a_webhook_id() -> WebhookId {
+        WebhookId::new(a_name())
+    }
+
+    pub fn a_github_webhook_id() -> i64 {
+        rand::thread_rng().next_u32().into()
+    }
+
+    pub fn a_branch_name() -> BranchName {
+        BranchName::new(a_name())
+    }
+
+    pub fn a_git_dir(fs: &kxio::fs::FileSystem) -> GitDir {
+        let dir_name = a_name();
+        let dir = fs.base().join(dir_name);
+        GitDir::new(&dir)
+    }
+
+    pub fn a_forge_config() -> ForgeConfig {
+        ForgeConfig::new(
+            ForgeType::MockForge,
+            a_name(),
+            a_name(),
+            a_name(),
+            Default::default(), // no repos
+        )
+    }
+
+    pub fn a_server_repo_config() -> ServerRepoConfig {
+        let main = a_branch_name().into_string();
+        let next = a_branch_name().into_string();
+        let dev = a_branch_name().into_string();
+        ServerRepoConfig::new(
+            format!("{}/{}", a_name(), a_name()),
+            main.clone(),
+            None,
+            Some(main),
+            Some(next),
+            Some(dev),
+        )
+    }
+
+    pub fn a_repo_config() -> RepoConfig {
+        RepoConfig::new(given::repo_branches(), config::RepoConfigSource::Repo)
+    }
+
+    pub fn a_commit() -> git::Commit {
+        git::Commit::new(a_commit_sha(), a_commit_message())
+    }
+
+    pub fn a_commit_with_message(message: &git::commit::Message) -> git::Commit {
+        git::Commit::new(a_commit_sha(), message.to_owned())
+    }
+
+    pub fn a_commit_with_sha(sha: &git::commit::Sha) -> git::Commit {
+        git::Commit::new(sha.to_owned(), a_commit_message())
+    }
+
+    pub fn a_commit_with(sha: &git::commit::Sha, message: &git::commit::Message) -> git::Commit {
+        git::Commit::new(sha.to_owned(), message.to_owned())
+    }
+
+    pub fn a_commit_message() -> git::commit::Message {
+        git::commit::Message::new(a_name())
+    }
+
+    pub fn a_commit_sha() -> git::commit::Sha {
+        git::commit::Sha::new(a_name())
+    }
+
+    pub fn a_webhook_push(
+        sha: &git::commit::Sha,
+        message: &git::commit::Message,
+    ) -> config::webhook::Push {
+        let branch = a_branch_name();
+        config::webhook::Push::new(branch, sha.to_string(), message.to_string())
+    }
+
+    pub fn a_filesystem() -> kxio::fs::FileSystem {
+        kxio::fs::temp().unwrap_or_else(|e| panic!("{}", e))
+    }
+
+    pub fn repo_details(fs: &kxio::fs::FileSystem) -> git::RepoDetails {
+        let generation = git::Generation::new();
+        let repo_alias = a_repo_alias();
+        let server_repo_config = a_server_repo_config();
+        let forge_alias = a_forge_alias();
+        let forge_config = a_forge_config();
+        let gitdir = a_git_dir(fs);
+        RepoDetails::new(
+            generation,
+            &repo_alias,
+            &server_repo_config,
+            &forge_alias,
+            &forge_config,
+            gitdir,
+        )
+    }
+
+    pub fn an_open_repository(
+        fs: &kxio::fs::FileSystem,
+    ) -> (
+        git::repository::OpenRepository,
+        GitDir,
+        git::repository::test::TestRepository,
+    ) {
+        #![allow(clippy::expect_used)]
+        let gitdir = a_git_dir(fs);
+        let repo = git::repository::test(fs.clone());
+        let or = repo.open(&gitdir).expect("open repo");
+        (or, gitdir, repo)
+    }
+
+    pub fn a_message_token() -> MessageToken {
+        MessageToken::new()
+    }
+}
+pub mod then {
+    #![allow(dead_code)] // TODO: remove this
+    #![allow(unused_imports)] // TODO: remove this
+
+    use std::path::{Path, PathBuf};
+
+    type TestResult = Result<(), Box<dyn std::error::Error>>;
+
+    use super::*;
+
+    pub fn commit_named_file_to_branch(
+        file_name: &Path,
+        contents: &str,
+        fs: &kxio::fs::FileSystem,
+        gitdir: &config::GitDir,
+        branch_name: &config::BranchName,
+    ) -> TestResult {
+        // git checkout ${branch_name}
+        git_checkout_new_branch(branch_name, gitdir)?;
+        // echo ${word} > file-${word}
+        let pathbuf = PathBuf::from(gitdir);
+        let file = fs.base().join(pathbuf).join(file_name);
+        #[allow(clippy::expect_used)]
+        fs.file_write(&file, contents)?;
+        // git add ${file}
+        git_add_file(gitdir, &file)?;
+        // git commit -m"Added ${file}"
+        git_commit(gitdir, &file)?;
+
+        then::push_branch(fs, gitdir, branch_name)?;
+
+        Ok(())
+    }
+
+    pub fn create_a_commit_on_branch(
+        fs: &kxio::fs::FileSystem,
+        gitdir: &config::GitDir,
+        branch_name: &config::BranchName,
+    ) -> TestResult {
+        // git checkout ${branch_name}
+        git_checkout_new_branch(branch_name, gitdir)?;
+        // echo ${word} > file-${word}
+        let word = given::a_name();
+        let pathbuf = PathBuf::from(gitdir);
+        let file = fs.base().join(pathbuf).join(&word);
+        fs.file_write(&file, &word)?;
+        // git add ${file}
+        git_add_file(gitdir, &file)?;
+        // git commit -m"Added ${file}"
+        git_commit(gitdir, &file)?;
+
+        then::push_branch(fs, gitdir, branch_name)?;
+
+        Ok(())
+    }
+
+    fn push_branch(
+        fs: &kxio::fs::FileSystem,
+        gitdir: &config::GitDir,
+        branch_name: &config::BranchName,
+    ) -> TestResult {
+        let gitrefs = fs
+            .base()
+            .join(gitdir.to_path_buf())
+            .join(".git")
+            .join("refs");
+        let local_branch = gitrefs.join("heads").join(branch_name.to_string().as_str());
+        let origin_heads = gitrefs.join("remotes").join("origin");
+        let remote_branch = origin_heads.join(branch_name.to_string().as_str());
+        let contents = fs.file_read_to_string(&local_branch)?;
+        fs.dir_create_all(&origin_heads)?;
+        fs.file_write(&remote_branch, &contents)?;
+        Ok(())
+    }
+
+    pub fn git_checkout_new_branch(
+        branch_name: &git_next_config::BranchName,
+        gitdir: &git_next_config::GitDir,
+    ) -> TestResult {
+        exec(
+            format!("git checkout -b {}", branch_name),
+            std::process::Command::new("/usr/bin/git")
+                .current_dir(gitdir.to_path_buf())
+                .args(["checkout", "-b", branch_name.to_string().as_str()])
+                .output(),
+        )?;
+        Ok(())
+    }
+
+    pub fn git_switch(
+        branch_name: &git_next_config::BranchName,
+        gitdir: &git_next_config::GitDir,
+    ) -> TestResult {
+        exec(
+            format!("git switch {}", branch_name),
+            std::process::Command::new("/usr/bin/git")
+                .current_dir(gitdir.to_path_buf())
+                .args(["switch", branch_name.to_string().as_str()])
+                .output(),
+        )
+    }
+
+    fn exec(label: String, output: Result<std::process::Output, std::io::Error>) -> TestResult {
+        eprintln!("== {label}");
+        match output {
+            Ok(output) => {
+                eprintln!(
+                    "\nstdout:\n{}",
+                    String::from_utf8_lossy(output.stdout.as_slice())
+                );
+                eprintln!(
+                    "\nstderr:\n{}",
+                    String::from_utf8_lossy(output.stderr.as_slice())
+                );
+                eprintln!("=============================");
+                Ok(())
+            }
+            Err(err) => {
+                eprintln!("ERROR: {err:#?}");
+                Ok(Err(err)?)
+            }
+        }
+    }
+
+    fn git_add_file(gitdir: &git_next_config::GitDir, file: &Path) -> TestResult {
+        exec(
+            format!("git add {file:?}"),
+            std::process::Command::new("/usr/bin/git")
+                .current_dir(gitdir.to_path_buf())
+                .args(["add", file.display().to_string().as_str()])
+                .output(),
+        )
+    }
+
+    fn git_commit(gitdir: &git_next_config::GitDir, file: &Path) -> TestResult {
+        exec(
+            format!(r#"git commit -m"Added {file:?}""#),
+            std::process::Command::new("/usr/bin/git")
+                .current_dir(gitdir.to_path_buf())
+                .args([
+                    "commit",
+                    format!(r#"-m"Added {}"#, file.display().to_string().as_str()).as_str(),
+                ])
+                .output(),
+        )
+    }
+
+    pub fn git_log_all(gitdir: &config::GitDir) -> TestResult {
+        exec(
+            "git log --all --oneline --decorate --graph".to_string(),
+            std::process::Command::new("/usr/bin/git")
+                .current_dir(gitdir.to_path_buf())
+                .args(["log", "--all", "--oneline", "--decorate", "--graph"])
+                .output(),
+        )
+    }
+
+    pub fn get_sha_for_branch(
+        fs: &kxio::fs::FileSystem,
+        gitdir: &git_next_config::GitDir,
+        branch_name: &git_next_config::BranchName,
+    ) -> Result<git::commit::Sha, Box<dyn std::error::Error>> {
+        let main_ref = fs
+            .base()
+            .join(gitdir.to_path_buf())
+            .join(".git")
+            .join("refs")
+            .join("heads")
+            .join(branch_name.to_string().as_str());
+        let sha = fs.file_read_to_string(&main_ref)?;
+        Ok(git::commit::Sha::new(sha.trim().to_string()))
+    }
+}