[pull] dev from opf:dev

docs/development/running-tests/README.md

@@ -817,3 +817,22 @@ good as a test server.
 
 Most of the above applies to running tests locally, with some docker specific setup changes that are discussed [in the
 docker development documentation](../development-environment-docker).
+
+## Generators
+
+In order to support developer productivity and testing confidence, we've extracted out common setup and boilerplate for good tests
+as RSpec generators and are encouraged to use them when adding a new spec file in OpenProject.
+
+To see the list of available RSpec generators, run:
+
+```shell
+./bin/rails generate -h
+```
+
+You'll see them under the "OpenProject" generator namespace.
+
+Along with the generators, we've bundled some helpful **USAGE** guides for each to help get up and running with them. Accessing them is as simple as:
+
+```shell
+./bin/rails generate open_project:rspec:GENERATOR_NAME -h
+```

lib/generators/open_project/rspec/service/USAGE

@@ -0,0 +1,16 @@
+Description:
+    Creates a new service spec file for the given SERVICE_NAME
+    in the specified MODULE_NAME (if given). Otherwise, creates
+    the service spec file in the root /specs directory.
+
+Example:
+    bin/rails generate open_project:rspec:service Some::Service
+
+    This will create:
+        /specs/services/some/service_spec.rb
+
+Example:
+    bin/rails generate open_project:rspec:service Some::Service -m meetings
+
+    This will create:
+        /modules/meetings/specs/services/some/service_spec.rb

lib/generators/open_project/rspec/service/service_generator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# -- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) 2023 the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+# ++
+
+module OpenProject
+  module Rspec
+    module Generators
+      class ServiceGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        argument :service_name,
+                 type: :string,
+                 required: true,
+                 desc: 'Constant of the service the spec is being generated for'
+
+        class_option :module_name,
+                     aliases: %i[m],
+                     type: :string,
+                     optional: true,
+                     desc: 'Module to generate the service spec file for'
+
+        def generate_service_spec
+          template 'service_spec.rb', file_path
+        end
+
+        private
+
+        def file_path
+          namespace = service_name.deconstantize.underscore
+          file_name = "#{service_name.demodulize.underscore}_spec.rb"
+
+          Rails.root.join(service_specs_root_directory,
+                          namespace,
+                          file_name)
+        end
+
+        def service_specs_root_directory
+          if options[:module_name]
+            "modules/#{options[:module_name]}/spec/services"
+          else
+            "spec/services"
+          end
+        end
+      end
+    end
+  end
+end

lib/generators/open_project/rspec/service/templates/service_spec.rb.tt

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# -- copyright
+# OpenProject is an open source project management software.
+# Copyright (C) 2023 the OpenProject GmbH
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License version 3.
+#
+# OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+# Copyright (C) 2006-2013 Jean-Philippe Lang
+# Copyright (C) 2010-2013 the ChiliProject Team
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+#
+# See COPYRIGHT and LICENSE files for more details.
+# ++
+
+require 'spec_helper'
+# Require the file for the BaseServices shared example you're keeping
+#
+# require 'services/base_services/behaves_like_create_service'
+# require 'services/base_services/behaves_like_update_service'
+# require 'services/base_services/behaves_like_delete_service'
+
+RSpec.describe <%= service_name %> do
+  # Keep the BaseServices shared_example that applies from below
+  #
+  # it_behaves_like 'BaseServices create service'
+  # it_behaves_like 'BaseServices update service'
+  # it_behaves_like 'BaseService delete service'
+
+  # AND/OR build your own
+  # Here's something to get started with
+  shared_examples 'is success' do
+    it { is_expected.to be_success }
+  end
+
+  shared_examples 'is failure' do
+    it { is_expected.to be_failure }
+  end
+
+  let(:user) { build_stubbed(:user) }
+  let(:instance) { described_class.new(user:) }
+
+  subject(:service_call) { instance.call(params) }
+
+  describe '#call' do
+    context 'with valid params' do
+      let(:params) { raise 'Define me' }
+
+      it_behaves_like 'is success'
+    end
+
+    context 'with invalid params' do
+      it_behaves_like 'is failure'
+    end
+  end
+end