From ae2c9c3572a7e5d0fa346711bea1fd8566ae7640 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Tue, 19 Nov 2024 11:11:24 -0800 Subject: [PATCH 1/5] Add tests for new exercise generator --- generators/.rspec | 1 + generators/spec/exercise_generator_spec.rb | 88 +++++++++++++++++++ generators/spec/spec_helper.rb | 98 ++++++++++++++++++++++ 3 files changed, 187 insertions(+) create mode 100644 generators/.rspec create mode 100644 generators/spec/exercise_generator_spec.rb create mode 100644 generators/spec/spec_helper.rb diff --git a/generators/.rspec b/generators/.rspec new file mode 100644 index 0000000000..c99d2e7396 --- /dev/null +++ b/generators/.rspec @@ -0,0 +1 @@ +--require spec_helper diff --git a/generators/spec/exercise_generator_spec.rb b/generators/spec/exercise_generator_spec.rb new file mode 100644 index 0000000000..284173022f --- /dev/null +++ b/generators/spec/exercise_generator_spec.rb @@ -0,0 +1,88 @@ +require_relative "../exercise_generator" + +describe ExerciseGenerator do + describe "#generate" do + subject(:generator) { described_class.new("test_namespace", "1_test_group", "test_exercise") } + + before do + allow(FileUtils).to receive(:mkdir_p) + allow(FileUtils).to receive(:copy_entry) + allow(FileUtils).to receive(:touch) + allow(File).to receive(:write) + end + + it "sends a `::touch` message to `FileUtils` to create the exercise file in the `exercises` subdir of the exercise directory" do + generator.generate + + expected_filename = "test_namespace/1_test_group/exercises/test_exercise.rb" + expect(FileUtils).to have_received(:touch).with(expected_filename) + end + + it "sends a `::write` message to `File` to create the spec file in the `spec` subdir of the exercise directory" do + generator.generate + + expected_filename = "test_namespace/1_test_group/spec/test_exercise_spec.rb" + expected_content = <<~FILE_CONTENT + require 'spec_helper' + require_relative '../exercises/test_exercise' + + RSpec.describe '' do + end + FILE_CONTENT + + expect(File).to have_received(:write).with(expected_filename, expected_content) + end + + context "when the directory structure does not exist for the exercise" do + before do + allow(Dir).to receive(:exist?).and_return(false) + end + + it "sends a `::mkdir_p` message to `FileUtils` to create exercise path" do + generator.generate + + expected_path = "test_namespace/1_test_group" + expect(FileUtils).to have_received(:mkdir_p).with(expected_path) + end + + it "sends a `::copy_entry` message to `FileUtils` to copy boilerplate into exercise directory" do + generator.generate + + expected_source = "generators/exercise_template" + expected_target = "test_namespace/1_test_group" + expect(FileUtils).to have_received(:copy_entry).with(expected_source, expected_target) + end + + it "sends a `::mkdir_p` message to `FileUtils` to create solutions path" do + generator.generate + + expected_path = "solutions/test_namespace/1_test_group" + expect(FileUtils).to have_received(:mkdir_p).with(expected_path) + end + + it "sends a `::copy_entry` message to `FileUtils` to copy boilerplate into solutions directory" do + generator.generate + + expected_source = "generators/exercise_template" + expected_target = "solutions/test_namespace/1_test_group" + expect(FileUtils).to have_received(:copy_entry).with(expected_source, expected_target) + end + end + + context "when the directory structure already exists for exercise" do + before do + allow(Dir).to receive(:exist?).and_return(true) + end + + it "does not send `::mkdir_p` message to `FileUtils`" do + generator.generate + expect(FileUtils).not_to have_received(:mkdir_p) + end + + it "does not send a `::copy_entry` message to `FileUtils`" do + generator.generate + expect(FileUtils).not_to have_received(:copy_entry) + end + end + end +end diff --git a/generators/spec/spec_helper.rb b/generators/spec/spec_helper.rb new file mode 100644 index 0000000000..c80d44b974 --- /dev/null +++ b/generators/spec/spec_helper.rb @@ -0,0 +1,98 @@ +# This file was generated by the `rspec --init` command. Conventionally, all +# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`. +# The generated `.rspec` file contains `--require spec_helper` which will cause +# this file to always be loaded, without a need to explicitly require it in any +# files. +# +# Given that it is always loaded, you are encouraged to keep this file as +# light-weight as possible. Requiring heavyweight dependencies from this file +# will add to the boot time of your test suite on EVERY test run, even for an +# individual file that may not need all of that loaded. Instead, consider making +# a separate helper file that requires the additional dependencies and performs +# the additional setup, and require it from the spec files that actually need +# it. +# +# See https://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration +RSpec.configure do |config| + # rspec-expectations config goes here. You can use an alternate + # assertion/expectation library such as wrong or the stdlib/minitest + # assertions if you prefer. + config.expect_with :rspec do |expectations| + # This option will default to `true` in RSpec 4. It makes the `description` + # and `failure_message` of custom matchers include text for helper methods + # defined using `chain`, e.g.: + # be_bigger_than(2).and_smaller_than(4).description + # # => "be bigger than 2 and smaller than 4" + # ...rather than: + # # => "be bigger than 2" + expectations.include_chain_clauses_in_custom_matcher_descriptions = true + end + + # rspec-mocks config goes here. You can use an alternate test double + # library (such as bogus or mocha) by changing the `mock_with` option here. + config.mock_with :rspec do |mocks| + # Prevents you from mocking or stubbing a method that does not exist on + # a real object. This is generally recommended, and will default to + # `true` in RSpec 4. + mocks.verify_partial_doubles = true + end + + # This option will default to `:apply_to_host_groups` in RSpec 4 (and will + # have no way to turn it off -- the option exists only for backwards + # compatibility in RSpec 3). It causes shared context metadata to be + # inherited by the metadata hash of host groups and examples, rather than + # triggering implicit auto-inclusion in groups with matching metadata. + config.shared_context_metadata_behavior = :apply_to_host_groups + +# The settings below are suggested to provide a good initial experience +# with RSpec, but feel free to customize to your heart's content. +=begin + # This allows you to limit a spec run to individual examples or groups + # you care about by tagging them with `:focus` metadata. When nothing + # is tagged with `:focus`, all examples get run. RSpec also provides + # aliases for `it`, `describe`, and `context` that include `:focus` + # metadata: `fit`, `fdescribe` and `fcontext`, respectively. + config.filter_run_when_matching :focus + + # Allows RSpec to persist some state between runs in order to support + # the `--only-failures` and `--next-failure` CLI options. We recommend + # you configure your source control system to ignore this file. + config.example_status_persistence_file_path = "spec/examples.txt" + + # Limits the available syntax to the non-monkey patched syntax that is + # recommended. For more details, see: + # https://rspec.info/features/3-12/rspec-core/configuration/zero-monkey-patching-mode/ + config.disable_monkey_patching! + + # This setting enables warnings. It's recommended, but in some cases may + # be too noisy due to issues in dependencies. + config.warnings = true + + # Many RSpec users commonly either run the entire suite or an individual + # file, and it's useful to allow more verbose output when running an + # individual spec file. + if config.files_to_run.one? + # Use the documentation formatter for detailed output, + # unless a formatter has already been configured + # (e.g. via a command-line flag). + config.default_formatter = "doc" + end + + # Print the 10 slowest examples and example groups at the + # end of the spec run, to help surface which specs are running + # particularly slow. + config.profile_examples = 10 + + # Run specs in random order to surface order dependencies. If you find an + # order dependency and want to debug it, you can fix the order by providing + # the seed, which is printed after each run. + # --seed 1234 + config.order = :random + + # Seed global randomization in this process using the `--seed` CLI option. + # Setting this allows you to use `--seed` to deterministically reproduce + # test failures related to randomization by passing the same `--seed` value + # as the one that triggered the failure. + Kernel.srand config.seed +=end +end From 3b24e6c678b8d40ad58b8ccdcba499e7350bf4b3 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Tue, 19 Nov 2024 11:12:00 -0800 Subject: [PATCH 2/5] Add code for new exercise generator --- generators/exercise_generator.rb | 59 ++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 generators/exercise_generator.rb diff --git a/generators/exercise_generator.rb b/generators/exercise_generator.rb new file mode 100644 index 0000000000..6f0ae8633f --- /dev/null +++ b/generators/exercise_generator.rb @@ -0,0 +1,59 @@ +require "fileutils" + +class ExerciseGenerator + def initialize(namespace, exercise_group_name, exercise_name) + @namespace = namespace + @exercise_group_name = exercise_group_name + @exercise_name = exercise_name + end + + TEMPLATE_DIR_PATH = "generators/exercise_template".freeze + + def generate + unless Dir.exist?(exercise_directory_path) + make_exercise_directory + make_solutions_directory + end + + FileUtils.touch(exercise_file_path) + File.write(spec_file_path, spec_template) + end + + private + + attr_reader :namespace, :exercise_group_name, :exercise_name + + def exercise_directory_path + File.join(namespace, exercise_group_name) + end + + def exercise_file_path + File.join(exercise_directory_path, "exercises", "#{exercise_name}.rb") + end + + def spec_file_path + File.join(exercise_directory_path, "spec", "#{exercise_name}_spec.rb") + end + + def spec_template + <<~SPEC + require 'spec_helper' + require_relative '../exercises/#{exercise_name}' + + RSpec.describe '' do + end + SPEC + end + + def make_exercise_directory + FileUtils::mkdir_p(exercise_directory_path) + FileUtils::copy_entry(TEMPLATE_DIR_PATH, exercise_directory_path) + end + + def make_solutions_directory + solutions_directory_path = File.join("solutions", exercise_directory_path) + + FileUtils::mkdir_p(solutions_directory_path) + FileUtils::copy_entry(TEMPLATE_DIR_PATH, solutions_directory_path) + end +end From 105a1216670ae7ea97c8e568ccee856a3b451849 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Tue, 19 Nov 2024 11:12:28 -0800 Subject: [PATCH 3/5] Add directory for exercise template structure --- generators/exercise_template/.rspec | 1 + .../exercise_template/spec/spec_helper.rb | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 generators/exercise_template/.rspec create mode 100644 generators/exercise_template/spec/spec_helper.rb diff --git a/generators/exercise_template/.rspec b/generators/exercise_template/.rspec new file mode 100644 index 0000000000..279bfd9e99 --- /dev/null +++ b/generators/exercise_template/.rspec @@ -0,0 +1 @@ +--require spec_helper --format documentation --color diff --git a/generators/exercise_template/spec/spec_helper.rb b/generators/exercise_template/spec/spec_helper.rb new file mode 100644 index 0000000000..71b90cde10 --- /dev/null +++ b/generators/exercise_template/spec/spec_helper.rb @@ -0,0 +1,18 @@ +RSpec.configure do |config| + config.expect_with :rspec do |expectations| + expectations.include_chain_clauses_in_custom_matcher_descriptions = true + end + + config.mock_with :rspec do |mocks| + mocks.verify_partial_doubles = true + end + + config.shared_context_metadata_behavior = :apply_to_host_groups +end + +module FormatterOverrides + def dump_pending(_) + end +end + +RSpec::Core::Formatters::DocumentationFormatter.prepend FormatterOverrides From 2dbb7e2464bf24226a8bf9fd7afe7786fe8f083e Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Tue, 19 Nov 2024 11:12:56 -0800 Subject: [PATCH 4/5] Add script for quickly bootstrapping new exercises --- bin/generate_exercise | 5 +++++ 1 file changed, 5 insertions(+) create mode 100755 bin/generate_exercise diff --git a/bin/generate_exercise b/bin/generate_exercise new file mode 100755 index 0000000000..4768bb1ea2 --- /dev/null +++ b/bin/generate_exercise @@ -0,0 +1,5 @@ +#!/usr/bin/env ruby + +require_relative "../generators/exercise_generator" + +ExerciseGenerator.new(*ARGV).generate From 5f9d0b657ba3e1951057db8aad7695931074d138 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Tue, 19 Nov 2024 13:26:18 -0800 Subject: [PATCH 5/5] Add documentation for generator script to README --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index a92f0616a6..38587e93c8 100644 --- a/README.md +++ b/README.md @@ -40,3 +40,32 @@ If your shell reports that it cannot find the rspec binary, it may be necessary ## Usage Each directory contains a read me with instructions for the exercises within them. + +## Contributing + +Make sure that when changing an exercise or its tests that you also make the required changes to that exercise's solution under the `solutions/` directory. + +If you're writing an entirely new exercise, there's a script provided to help generate the correct directory structure and boilerplate. An example use for if you wanted to create a new exercise in `ruby_basics` for working with Ruby blocks: + +```bash +bin/generate_exercise ruby_basics 13_blocks block_exercises +``` + +This will setup the following structure automatically: + +```bash +. +├── ruby_basics +│ └── 13_blocks +│ ├── exercises +│ │ └── block_exercises.rb +│ └── spec +│ ├── block_exercises_spec.rb +│ └── spec_helper.rb +└── solutions + └── ruby_basics + └── 13_blocks + ├── exercises + └── spec + └── spec_helper.rb +```