jekyll-test-harness 0.1.0.alpha

data/readme.md

@@ -0,0 +1,231 @@
+# Jekyll Test Harness
+
+![Alpha](https://img.shields.io/badge/status-alpha-red)
+
+Simple integration testing for Jekyll plugins. Extends RSpec or Minitest with helper methods for building a real Jekyll site, with your plugin available, to test how it actually runs within Jekyll.
+
+
+## Setup
+
+```ruby
+# Gemfile
+group :test do
+  gem 'jekyll-test-harness'
+  gem 'rspec', '~> 3.13' # if using RSpec
+  gem 'minitest', '>= 5.0' # if using Minitest
+end
+```
+
+Load the harness:
+
+```ruby
+# spec/spec_helper.rb or test/test_helper.rb
+require 'rspec' # or below
+require 'minitest/autorun' # or above
+require 'jekyll_test_harness'
+require 'my_plugin'
+
+JekyllTestHarness.install!
+```
+
+`JekyllTestHarness.install!` auto-detects your test framework. You can also pass global configuration options:
+
+```ruby
+JekyllTestHarness.install!(
+  framework: :rspec # or :minitest, to be explicit
+  failures: :clean,          # or :keep
+  output: nil                # nil => system temp, or project-relative string like 'tmp/jekyll-sites'
+)
+```
+
+If both RSpec and Minitest are loaded in the same process, set `framework:` explicitly.
+
+Options:
+
+- `failures:`
+  - `:clean` (default): remove temporary site directories after failures.
+  - `:keep`: keep failed build directories for debugging.
+- `output:`
+  - `nil` (default): build under system temp.
+  - relative path: resolved from the project root captured during `install!`.
+  - absolute path: used as-is.
+
+
+## Compatibility
+
+- Ruby: `>= 2.4.4`
+- Jekyll: `>= 3.8.5`, `< 5.0`
+
+
+## Test DSL
+
+After calling `install!`, your examples/tests get these helper methods:
+
+- `jekyll_build(...) { |site, files| ... }`
+- `jekyll_config(hash = nil, file: nil)`
+- `jekyll_files { ... }`
+- `jekyll_blueprint(config:, files:)`
+- `jekyll_merge(base, new)`
+
+### `jekyll_build`
+
+Builds a fresh throwaway Jekyll site for one test, runs a real Jekyll build (`Jekyll::Site#process`), and yields:
+
+- `site`: the built `Jekyll::Site` object (collections, documents, metadata, etc.)
+- `files`: inspect the files that were output by Jekyll
+
+```ruby
+jekyll_build(blueprint = nil, config: nil, files: nil) do |site, files|
+  # assertions
+end
+```
+
+No default scaffold is written automatically. Supply your own files/layouts/content.
+
+When the first argument is a blueprint, `jekyll_build` runs in explicit blueprint mode:
+
+- buffered values from `jekyll_config` and `jekyll_files` are ignored for that build.
+- only blueprint data plus explicit `config:`/`files:` overrides are used.
+- every `jekyll_build` call flushes buffered config/files, whether buffers are used in that call or not.
+
+### `files` object
+
+`jekyll_build` yields a `files` helper with:
+
+- `dir`:
+  absolute output directory.
+- `path(relative_path)`:
+  absolute path under output directory.
+- `read(relative_path)`:
+  reads file from output directory.
+- `list(root = nil)`:
+  returns output file paths relative to output directory.
+
+Source inspection methods are also available:
+
+- `source_dir`
+- `source_path(relative_path)`
+- `source_read(relative_path)`
+- `source_list(root = nil)`
+
+`relative_path` arguments are validated to prevent path traversal outside the temporary site.
+
+### `jekyll_config(hash = nil, file: nil)`
+
+Builds config data and appends it to the internal config buffer.
+
+- `hash` can be provided directly.
+- `file:` loads YAML from a fixture path relative to project root.
+- if both are provided, `hash` merges over loaded fixture YAML.
+
+Each call returns the resolved hash and merges it into the buffer.
+
+When calling `jekyll_build`, if `config:` is omitted and no blueprint is passed, the buffered value from `jekyll_config` is used. Either way, the buffer is then flushed.
+
+Safety rule:
+
+- user-provided `source` and `destination` config keys are ignored.
+- the harness always enforces its own temporary `source`/`destination` paths.
+- a warning is emitted when either key is provided.
+
+### `jekyll_files { ... }`
+
+Use this helper to specify the files within the test Jekyll site. Builds nested file hashes with DSL methods and appends result to the internal files buffer.
+
+```ruby
+files = jekyll_files do
+  folder '_layouts' do
+    file 'default.html' do
+      '<html><body>{{ content }}</body></html>'
+    end
+  end
+  file 'index.md' do
+    frontmatter('layout' => 'default')
+    contents('Hello from buffered files')
+  end
+end
+```
+
+- `folder(name) { ... }` can contain nested `folder`/`file` calls.
+- `file(name) { ... }` block defines file contents.
+- Inside a `file` block, these helpers are available:
+  - `frontmatter(hash = nil, file: nil)`
+    - YAML-dumps hash between `---` separators.
+    - `file:` loads YAML fixture first, then merges inline hash over it.
+  - `contents(string = nil, file: nil)`
+    - passes string through directly.
+    - `file:` loads raw fixture text.
+- If `frontmatter`/`contents` are not used, file block can directly return:
+  - `String` (written directly)
+  - `Array` (joined with newlines)
+  - `Hash` (YAML-dumped)
+
+Each `jekyll_files` call both returns the generated hash and merges it into the internal files buffer. The returned hash could be passed to `jekyll_build` or `jekyll_blueprint`.
+
+When calling `jekyll_build`, if `files:` is omitted and no blueprint is passed, the buffered value from `jekyll_files` is used. Either way, the buffer is then flushed.
+
+### `jekyll_blueprint(config:, files:)`
+
+Creates a reusable blueprint object that stores config and file hashes for composition.
+
+```ruby
+base_blueprint = jekyll_blueprint(
+  config: { 'my_plugin' => { 'mode' => 'base' } },
+  files: {
+    '_layouts' => { 'default.html' => '<html><body>{{ content }}</body></html>' },
+    'index.md' => "---\nlayout: default\n---\nBase body\n"
+  }
+)
+```
+
+A blueprint can be passed as the first parameter of `jekyll_build`. If `config` or `files` are also passed, these are merged over the blueprint.
+
+Passing a blueprint also disables buffered `jekyll_config`/`jekyll_files` input for that build.
+
+### `jekyll_merge(base, new)`
+
+Used for deep merges:
+
+- Hash + Hash => deep hash merge
+- JekyllBlueprint + JekyllBlueprint => new merged blueprint.
+
+
+## Example
+
+```ruby
+RSpec.describe 'my plugin integration' do
+  it 'renders expected output' do
+    jekyll_config(file: 'spec/fixtures/jekyll/base_config.yml')
+
+    jekyll_files do
+      folder '_layouts' do
+        file 'default.html' do
+          '<html><body>{{ content }}</body></html>'
+        end
+      end
+
+      folder '_posts' do
+        file '2026-01-01-demo.md' do
+          frontmatter('layout' => 'default', 'permalink' => '/docs/demo.html')
+          contents('Hello')
+        end
+      end
+    end
+
+    jekyll_build do |site, files|
+      post = site.collections.fetch('posts').docs.first
+      html = files.read('docs/demo.html')
+      expect(post).not_to be_nil
+      expect(html).to include('Hello')
+    end
+  end
+end
+```
+
+## Release Notes
+
+See `CHANGELOG.md`.
+
+## Licence
+
+`jekyll-test-harness` is licensed under `LGPL-3.0-or-later`. See `LICENSE.txt`.

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-test-harness
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha
+platform: ruby
+authors:
+- Convincible
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.5
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+description: Builds isolated temporary Jekyll sites for plugin testing with RSpec
+  or Minitest, plus optional helper DSL.
+email:
+- development@convincible.media
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/jekyll_test_harness.rb
+- lib/jekyll_test_harness/core/configuration.rb
+- lib/jekyll_test_harness/core/data_tools.rb
+- lib/jekyll_test_harness/core/errors.rb
+- lib/jekyll_test_harness/core/file_tree.rb
+- lib/jekyll_test_harness/core/files_dsl.rb
+- lib/jekyll_test_harness/core/fixture_loader.rb
+- lib/jekyll_test_harness/core/jekyll_blueprint.rb
+- lib/jekyll_test_harness/core/paths.rb
+- lib/jekyll_test_harness/core/site_harness.rb
+- lib/jekyll_test_harness/core/temporary_directory.rb
+- lib/jekyll_test_harness/entrypoint.rb
+- lib/jekyll_test_harness/framework/helpers.rb
+- lib/jekyll_test_harness/framework/installer.rb
+- lib/jekyll_test_harness/version.rb
+- readme.md
+homepage: https://github.com/ConvincibleMedia/jekyll-test-harness
+licenses:
+- LGPL-3.0-or-later
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Reusable integration test harness for Jekyll plugin development.
+test_files: []