Add specification-drvien test suite

.github/workflows/ci.yml

@@ -39,6 +39,8 @@ jobs:
 
     - name: Run tests
       run: bundle exec rake spec
+      env:
+        SPEC_MD: spec/kramdown_rpf-legacy-spec.md
 
   publish:
     needs: [lint, test]

Gemfile

@@ -6,7 +6,10 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
+  gem 'compare-xml'
+  gem 'nokogiri'
   gem 'rake'
+  gem 'rexml', '~> 3.4'
   gem 'rspec', require: false
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false

README.md

@@ -136,6 +136,24 @@ question: Here is a heading for a quiz with three possible answers. How do you f
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Testing against the spec
+
+The formal spec lives at `spec/kramdown_rpf-legacy-spec.md`. This is used to test that the output of the gem matches the expected output for a variety of inputs. To run these tests, run:
+
+```sh
+bundle exec rspec
+```
+
+If you wish to use a different spec, you can set the `SPEC_MD` environment variable:
+
+```
+SPEC_MD=my-new-spec.md bundle exec rake spec
+```
+
+This is also run automatically in CI.
+
+**If you add or change examples in `examples/`, you must update the spec file accordingly** — both here in `spec/kramdown_rpf-legacy-spec.md` and in the canonical copy in the [documentation repository](https://github.com/RaspberryPiFoundation/documentation) at `docs/technology/codebases-and-products/raspberry-flavoured-markdown/kramdown_rpf-legacy-spec.md`.
+
 To install this gem onto your local machine, run `bundle exec rake install`.
 
 ### Release a new version

spec/i18n_spec.rb

@@ -20,8 +20,10 @@
     values = file_contents[1]['kramdown_rpf']
 
     context("with #{locale} locale") do
-      before do
+      around do |example|
         I18n.locale = locale
+        example.run
+        I18n.locale = I18n.default_locale
       end
 
       it('converts hint title') do