activemail 1.2.3 → 2.0.0

data/lib/activemail/inliner/roadie.rb

@@ -22,7 +22,7 @@ module ActiveMail
         require 'roadie'
       rescue LoadError
         # Unify on Inliner::Error (LoadError is not a StandardError, so the
-        # interceptor's rescue would otherwise miss it); the LoadError is #cause.
+        # Pipeline's rescue would otherwise miss it); the LoadError is #cause.
         raise ActiveMail::Inliner::Error, "ActiveMail::Inliner::Roadie requires the 'roadie' gem. Add it to your Gemfile."
       end
     end

data/lib/activemail/inliner.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+require_relative 'inliner/base'
+require_relative 'inliner/premailer'
+require_relative 'inliner/roadie'
+require_relative 'inliner/null'
+
+module ActiveMail
+  module Inliner
+    extend T::Sig
+
+    ADAPTERS = T.let(
+      { premailer: Premailer, roadie: Roadie, null: Null }.freeze,
+      T::Hash[Symbol, T.class_of(Base)]
+    )
+
+    Setting = T.type_alias { T.any(Symbol, Base, T.class_of(Base)) }
+
+    sig { params(setting: Setting).returns(Base) }
+    def self.resolve(setting)
+      return setting if setting.is_a?(Base)
+      return setting.new if setting.is_a?(Class) && setting < Base
+
+      adapter = ADAPTERS[setting] if setting.is_a?(Symbol)
+      return adapter.new if adapter
+
+      raise ArgumentError, "unknown inliner #{setting.inspect}, expected one of #{ADAPTERS.keys.inspect}, an Inliner::Base subclass, or an instance"
+    end
+  end
+end

data/lib/activemail/parse_error_reporter.rb

@@ -7,19 +7,20 @@ require_relative 'libxml'
 
 module ActiveMail
   # Surfaces libxml2 recover-mode repairs that would otherwise silently change
-  # the rendered email, honoring ActiveMail.configuration.on_parse_error.
+  # the rendered email, honoring the config's on_parse_error.
   class ParseErrorReporter
     extend T::Sig
 
-    sig { params(known_tags: T::Array[String]).void }
-    def initialize(known_tags)
+    sig { params(known_tags: T::Array[String], config: ActiveMail::Configuration).void }
+    def initialize(known_tags, config)
+      @config = config
       # dup.freeze: the caller's array stays decoupled and cannot be mutated under us.
       @known_tags = T.let(known_tags.dup.freeze, T::Array[String])
     end
 
     sig { params(errors: T::Array[Nokogiri::XML::SyntaxError]).void }
     def call(errors)
-      mode = ::ActiveMail.configuration.on_parse_error
+      mode = @config.on_parse_error
       return if mode == :ignore
 
       relevant = errors.reject { |error| known_tag_error?(error) }

data/lib/activemail/pipeline.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module ActiveMail
+  module Pipeline
+    extend T::Sig
+
+    sig { params(html: String, config: ActiveMail::Configuration).returns(String) }
+    def self.call(html, config: ActiveMail.configuration)
+      inline(config.resolved_inliner, config.core.transpile(html))
+    end
+
+    sig { params(inliner: ActiveMail::Inliner::Base, html: String).returns(String) }
+    def self.inline(inliner, html)
+      inliner.inline(html)
+    rescue ActiveMail::Inliner::Error
+      raise
+    rescue StandardError => e
+      # A silently non-inlined mail is worse than a failed one.
+      raise ActiveMail::Inliner::Error, "[#{inliner.class}] CSS inlining failed: #{e.message}"
+    end
+    private_class_method :inline
+  end
+end

data/lib/activemail/quality/builtin_rules.rb

@@ -0,0 +1,154 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'sorbet-runtime'
+
+require_relative '../libxml'
+require_relative 'preview_renderer'
+require_relative 'rule'
+
+module ActiveMail
+  module Quality
+    class BuiltinRules
+      extend T::Sig
+
+      NAMES = T.let(
+        %i[
+          max_bytes parse_error table_role img_alt lang min_full_doc_bytes translation_missing single_root
+          translation_missing_text html_part_present text_part_present text_part_plain
+        ].freeze,
+        T::Array[Symbol]
+      )
+      MARKUP_IN_TEXT = %r{<(?:table|div|span|p|br|a)[\s>/]}i
+      MISSING_TRANSLATION = /translation[ _]missing/i
+      ROOTS = T.let({ html: /<html[\s>]/i, body: /<body[\s>]/i }.freeze, T::Hash[Symbol, Regexp])
+
+      sig { params(max_bytes: Integer, min_full_doc_bytes: Integer).void }
+      def initialize(max_bytes:, min_full_doc_bytes:)
+        # A non-positive threshold would silently disable (or invert) a check.
+        @max_bytes = T.let(::ActiveMail.positive_integer!(:max_bytes, max_bytes), Integer)
+        @min_full_doc_bytes = T.let(::ActiveMail.positive_integer!(:min_full_doc_bytes, min_full_doc_bytes), Integer)
+      end
+
+      sig { returns(T::Array[Rule]) }
+      def rules
+        structure_rules + content_rules + message_rules
+      end
+
+      private
+
+      sig { returns(T::Array[Rule]) }
+      def structure_rules
+        [
+          Rule.html(:max_bytes) { |_doc, html| size_message(html) },
+          # The Core surfaces libxml2 repairs on input; the validation layer must not
+          # silently bless malformed *output* (mismatched tags, bad entities) before send.
+          Rule.html(:parse_error) { |doc, _html| parse_error_message(doc) },
+          Rule.html(:table_role) { |doc, _html| table_role_message(doc) },
+          Rule.html(:img_alt) { |doc, _html| img_alt_message(doc) }
+        ]
+      end
+
+      sig { returns(T::Array[Rule]) }
+      def content_rules
+        [
+          Rule.html(:translation_missing) { |_doc, html| translation_missing_message(html) },
+          Rule.html(:single_root) { |_doc, html| single_root_messages(html) },
+          Rule.html(:min_full_doc_bytes) { |_doc, html| min_full_doc_message(html) },
+          Rule.html(:lang) { |doc, html| lang_message(doc, html) }
+        ]
+      end
+
+      sig { returns(T::Array[Rule]) }
+      def message_rules
+        [
+          Rule.message(:translation_missing_text) { |mail| translation_missing_text_message(mail) },
+          Rule.message(:html_part_present) { |mail| html_part_present_message(mail) },
+          Rule.message(:text_part_present) { |mail| text_part_present_message(mail) },
+          Rule.message(:text_part_plain) { |mail| text_part_plain_message(mail) }
+        ]
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def size_message(html)
+        return if html.bytesize <= @max_bytes
+
+        "HTML is #{html.bytesize} bytes, exceeds #{@max_bytes} (Gmail clipping)"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def parse_error_message(doc)
+        errors = doc.errors.reject { |e| e.code == LIBXML_UNKNOWN_TAG_CODE }
+        return if errors.empty?
+
+        "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def table_role_message(doc)
+        offenders = doc.css('table').count { |table| table['role'] != 'presentation' }
+        %(#{offenders} <table> missing role="presentation") unless offenders.zero?
+      end
+
+      sig { params(doc: Nokogiri::XML::Document).returns(T.nilable(String)) }
+      def img_alt_message(doc)
+        offenders = doc.css('img').count { |img| !img.key?('alt') }
+        "#{offenders} <img> missing an alt attribute" unless offenders.zero?
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def translation_missing_message(html)
+        'rendered HTML contains a missing i18n translation' if html.match?(MISSING_TRANSLATION)
+      end
+
+      # Counted on the raw string: libxml2 silently merges duplicate roots.
+      sig { params(html: String).returns(T::Array[String]) }
+      def single_root_messages(html)
+        ROOTS.filter_map do |tag, pattern|
+          count = html.scan(pattern).size
+          "#{count} <#{tag}> roots, expected at most one" if count > 1
+        end
+      end
+
+      sig { params(html: String).returns(T.nilable(String)) }
+      def min_full_doc_message(html)
+        return unless ::ActiveMail.full_document?(html) && html.bytesize < @min_full_doc_bytes
+
+        "full document is only #{html.bytesize} bytes (under #{@min_full_doc_bytes})"
+      end
+
+      sig { params(doc: Nokogiri::XML::Document, html: String).returns(T.nilable(String)) }
+      def lang_message(doc, html)
+        return unless ::ActiveMail.full_document?(html)
+
+        html_tag = doc.at_css('html')
+        lang = html_tag && html_tag['lang']
+        '<html> must declare a non-blank lang attribute' if lang.nil? || lang.strip.empty?
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def translation_missing_text_message(mail)
+        text = "#{mail.subject}\n#{PreviewRenderer.text_body(mail)}"
+        'subject or text part contains a missing i18n translation' if text.match?(MISSING_TRANSLATION)
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def html_part_present_message(mail)
+        'message has no HTML part' if PreviewRenderer.html_body(mail).empty?
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def text_part_present_message(mail)
+        return if mail.multipart? && !PreviewRenderer.text_body(mail).strip.empty?
+
+        'message must be multipart with a non-empty text/plain part'
+      end
+
+      sig { params(mail: T.untyped).returns(T.nilable(String)) }
+      def text_part_plain_message(mail)
+        'text/plain part contains HTML markup' if PreviewRenderer.text_body(mail).match?(MARKUP_IN_TEXT)
+      end
+    end
+  end
+end

data/lib/activemail/quality/configuration.rb

@@ -1,15 +1,20 @@
 # typed: strict
 # frozen_string_literal: true
 
+require 'i18n'
 require 'sorbet-runtime'
 
 require_relative 'guard'
+require_relative 'output_dir'
 
 module ActiveMail
   module Quality
     class Configuration
       extend T::Sig
 
+      FORMATS = T.let(%i[html text].freeze, T::Array[Symbol])
+      DEFAULT_LOCALES = T.let(->(_preview) { [I18n.default_locale] }, Proc)
+
       sig { returns(Guard) }
       attr_reader :guard
 
@@ -25,9 +30,7 @@ module ActiveMail
 
       sig { params(value: String).void }
       def output_dir=(value)
-        raise ArgumentError, 'output_dir must not be blank' if value.strip.empty?
-
-        @output_dir = value
+        @output_dir = OutputDir.validate!(value)
       end
 
       # Preview keys ("preview_name#email") that MUST render and pass the guard;
@@ -45,11 +48,88 @@ module ActiveMail
         @required_previews = value.to_a.map(&:to_s)
       end
 
+      sig { returns(T.any(T::Array[Symbol], Proc)) }
+      attr_reader :locales
+
+      sig { params(value: T.untyped).void }
+      def locales=(value)
+        @locales = value.is_a?(Proc) ? value : normalize_locales(value)
+      end
+
+      sig { params(preview: T.untyped).returns(T::Array[Symbol]) }
+      def locales_for(preview)
+        value = @locales
+        value.is_a?(Proc) ? normalize_locales(value.call(preview)) : value
+      end
+
+      sig { returns(T::Array[Symbol]) }
+      def formats
+        @formats.dup.freeze
+      end
+
+      sig { params(value: T.untyped).void }
+      def formats=(value)
+        raise TypeError, "formats must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+        formats = value.map(&:to_sym)
+        unknown = formats - FORMATS
+        raise ArgumentError, "unknown format(s): #{unknown.inspect}, expected a subset of #{FORMATS.inspect}" unless unknown.empty?
+        raise ArgumentError, 'formats must not be empty' if formats.empty?
+
+        @formats = formats.uniq
+      end
+
+      # ->(preview, email, locale, &block) wrapping each rendering; it must call block.
+      sig { returns(T.nilable(Proc)) }
+      attr_reader :around_each
+
+      sig { params(value: T.untyped).void }
+      def around_each=(value)
+        raise TypeError, "around_each must be a Proc or nil, got #{value.class}" unless value.nil? || value.is_a?(Proc)
+
+        @around_each = value
+      end
+
+      # Applied to written files only: the Guard always sees the unfiltered content.
+      sig { returns(T::Array[Proc]) }
+      attr_reader :output_filters
+
+      sig { params(value: T.untyped).void }
+      def output_filters=(value)
+        raise TypeError, "output_filters must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+        @output_filters = value.map { |filter| output_filter(filter) }
+      end
+
       sig { void }
       def initialize
         @guard = T.let(Guard.new, Guard)
         @output_dir = T.let('tmp/activemail_previews', String)
         @required_previews = T.let([], T::Array[String])
+        @locales = T.let(DEFAULT_LOCALES, T.any(T::Array[Symbol], Proc))
+        @formats = T.let(FORMATS, T::Array[Symbol])
+        @around_each = T.let(nil, T.nilable(Proc))
+        @output_filters = T.let([], T::Array[Proc])
+      end
+
+      private
+
+      sig { params(value: T.untyped).returns(T::Array[Symbol]) }
+      def normalize_locales(value)
+        raise TypeError, "locales must be an Array, got #{value.class}" unless value.is_a?(Array)
+        raise ArgumentError, 'locales must not be empty' if value.empty?
+
+        value.map(&:to_sym)
+      end
+
+      sig { params(filter: T.untyped).returns(Proc) }
+      def output_filter(filter)
+        return filter if filter.is_a?(Proc)
+
+        pattern, replacement = filter if filter.is_a?(Array) && filter.size == 2
+        raise TypeError, "output filter must be a Proc or [Regexp, String], got #{filter.inspect}" unless pattern.is_a?(Regexp) && replacement.is_a?(String)
+
+        ->(content) { content.gsub(pattern, replacement) }
       end
     end
   end

data/lib/activemail/quality/guard.rb

@@ -4,127 +4,85 @@
 require 'nokogiri'
 require 'sorbet-runtime'
 
-require_relative '../libxml'
+require_relative 'builtin_rules'
+require_relative 'preview_renderer'
+require_relative 'rule'
 
 module ActiveMail
   module Quality
     class Guard
       extend T::Sig
 
-      # One failed invariant. :rule is a stable symbol for programmatic matching;
-      # :message is human-facing.
       class Violation < T::Struct
+        extend T::Sig
+
         const :rule, Symbol
         const :message, String
+
+        sig { returns(String) }
+        def to_s
+          "[#{rule}] #{message}"
+        end
       end
 
-      DISABLEABLE = T.let(%i[max_bytes parse_error table_role img_alt lang min_full_doc_bytes].freeze, T::Array[Symbol])
+      DISABLEABLE = BuiltinRules::NAMES
       # Gmail clips messages past ~102KB.
       DEFAULT_MAX_BYTES = 102_400
       # A full HTML document smaller than this carries no real layout and is suspect.
       DEFAULT_MIN_FULL_DOC_BYTES = 1_024
 
-      # disable: any subset of DISABLEABLE to skip those checks.
-      sig { params(max_bytes: Integer, min_full_doc_bytes: Integer, disable: T::Array[Symbol]).void }
-      def initialize(max_bytes: DEFAULT_MAX_BYTES, min_full_doc_bytes: DEFAULT_MIN_FULL_DOC_BYTES, disable: [])
-        # A non-positive threshold would silently disable (or invert) a check.
-        @max_bytes = T.let(positive_threshold!(:max_bytes, max_bytes), Integer)
-        @min_full_doc_bytes = T.let(positive_threshold!(:min_full_doc_bytes, min_full_doc_bytes), Integer)
-        unknown = disable - DISABLEABLE
-        raise ArgumentError, "unknown rule(s): #{unknown.inspect}, expected a subset of #{DISABLEABLE.inspect}" unless unknown.empty?
-
-        @disabled = T.let(disable.to_set, T::Set[Symbol])
+      sig { params(max_bytes: Integer, min_full_doc_bytes: Integer, disable: T::Array[Symbol], rules: T::Array[Rule]).void }
+      def initialize(max_bytes: DEFAULT_MAX_BYTES, min_full_doc_bytes: DEFAULT_MIN_FULL_DOC_BYTES, disable: [], rules: [])
+        all = assemble_rules(BuiltinRules.new(max_bytes: max_bytes, min_full_doc_bytes: min_full_doc_bytes), disable, rules)
+        @html_rules = T.let(all.select { |rule| rule.level == :html }, T::Array[Rule])
+        @message_rules = T.let(all.select { |rule| rule.level == :message }, T::Array[Rule])
       end
 
-      sig { params(html: String).returns(T::Array[Violation]) }
-      def violations(html)
-        violations = []
-        check_size(html, violations)
-
-        doc = Nokogiri::HTML(html)
-        check_well_formed(doc, violations)
-        check_table_roles(doc, violations)
-        check_img_alts(doc, violations)
-        check_full_document(html, doc, violations) if ::ActiveMail.full_document?(html)
-        violations
-      end
-
-      sig { params(html: String).returns(T::Boolean) }
-      def valid?(html)
-        violations(html).empty?
-      end
-
-      private
-
-      sig { params(rule: Symbol).returns(T::Boolean) }
-      def enabled?(rule)
-        !@disabled.include?(rule)
-      end
+      # A String only gets the HTML rules; a message gets both levels, except a declined send.
+      sig { params(html_or_message: T.untyped).returns(T::Array[Violation]) }
+      def violations(html_or_message)
+        return html_violations(html_or_message) if html_or_message.is_a?(String)
 
-      sig { params(name: Symbol, value: Integer).returns(Integer) }
-      def positive_threshold!(name, value)
-        raise ArgumentError, "#{name} must be a positive integer, got #{value}" unless value.positive?
+        mail = PreviewRenderer.mail(html_or_message)
+        return [] if PreviewRenderer.declined?(mail)
 
-        value
+        html = PreviewRenderer.html_body(mail)
+        (html.empty? ? [] : html_violations(html)) + apply(@message_rules, [mail])
       end
 
-      sig { params(html: String, violations: T::Array[Violation]).void }
-      def check_size(html, violations)
-        return unless enabled?(:max_bytes)
-        return if html.bytesize <= @max_bytes
-
-        violations << Violation.new(rule: :max_bytes, message: "HTML is #{html.bytesize} bytes, exceeds #{@max_bytes} (Gmail clipping)")
+      sig { params(html_or_message: T.untyped).returns(T::Boolean) }
+      def valid?(html_or_message)
+        violations(html_or_message).empty?
       end
 
-      # The Core surfaces libxml2 repairs on input; the validation layer must not
-      # silently bless malformed *output* (mismatched tags, bad entities) before send.
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_well_formed(doc, violations)
-        return unless enabled?(:parse_error)
+      private
 
-        errors = doc.errors.reject { |e| e.code == LIBXML_UNKNOWN_TAG_CODE }
-        return if errors.empty?
+      sig { params(builtin: BuiltinRules, disable: T::Array[Symbol], custom: T::Array[Rule]).returns(T::Array[Rule]) }
+      def assemble_rules(builtin, disable, custom)
+        unknown = disable - DISABLEABLE
+        raise ArgumentError, "unknown rule(s): #{unknown.inspect}, expected a subset of #{DISABLEABLE.inspect}" unless unknown.empty?
 
-        violations << Violation.new(rule: :parse_error, message: "malformed HTML: #{errors.first(3).map { |e| e.message.to_s.strip }.join('; ')}")
+        unique_names!(builtin.rules.reject { |rule| disable.include?(rule.name) } + custom)
       end
 
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_table_roles(doc, violations)
-        return unless enabled?(:table_role)
-
-        offenders = doc.css('table').count { |table| table['role'] != 'presentation' }
-        return if offenders.zero?
+      sig { params(rules: T::Array[Rule]).returns(T::Array[Rule]) }
+      def unique_names!(rules)
+        duplicates = rules.map(&:name).tally.select { |_name, count| count > 1 }.keys
+        raise ArgumentError, "duplicate rule name(s): #{duplicates.inspect}" unless duplicates.empty?
 
-        violations << Violation.new(rule: :table_role, message: %(#{offenders} <table> missing role="presentation"))
+        rules
       end
 
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_img_alts(doc, violations)
-        return unless enabled?(:img_alt)
-
-        offenders = doc.css('img').count { |img| !img.key?('alt') }
-        return if offenders.zero?
-
-        violations << Violation.new(rule: :img_alt, message: "#{offenders} <img> missing an alt attribute")
+      sig { params(html: String).returns(T::Array[Violation]) }
+      def html_violations(html)
+        apply(@html_rules, [Nokogiri::HTML(html), html])
       end
 
-      sig { params(html: String, doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_full_document(html, doc, violations)
-        if enabled?(:min_full_doc_bytes) && html.bytesize < @min_full_doc_bytes
-          violations << Violation.new(rule: :min_full_doc_bytes, message: "full document is only #{html.bytesize} bytes (under #{@min_full_doc_bytes})")
+      sig { params(rules: T::Array[Rule], args: T::Array[T.untyped]).returns(T::Array[Violation]) }
+      def apply(rules, args)
+        rules.flat_map do |rule|
+          rule.messages(args).map { |message| Violation.new(rule: rule.name, message: message) }
         end
-        check_lang(doc, violations)
-      end
-
-      sig { params(doc: Nokogiri::XML::Document, violations: T::Array[Violation]).void }
-      def check_lang(doc, violations)
-        return unless enabled?(:lang)
-
-        html_tag = doc.at_css('html')
-        lang = html_tag && html_tag['lang']
-        return if lang && !lang.strip.empty?
-
-        violations << Violation.new(rule: :lang, message: '<html> must declare a non-blank lang attribute')
       end
     end
   end

data/lib/activemail/quality/minitest.rb

@@ -8,36 +8,34 @@ module ActiveMail
     module Minitest
       extend T::Sig
 
-      sig { params(html: String, guard: Guard).void }
-      def assert_email_quality(html, guard: ActiveMail::Quality.guard)
-        violations = guard.violations(html)
-        # assert is injected by the host's Minitest test class.
-        T.unsafe(self).assert violations.empty?,
-                              "email quality violations:\n#{violations.map { |v| "  - [#{v.rule}] #{v.message}" }.join("\n")}"
+      sig { params(html_or_message: T.untyped, guard: Guard).void }
+      def assert_email_quality(html_or_message, guard: ActiveMail::Quality.guard)
+        assert_no_quality_violations(guard.violations(html_or_message))
       end
 
-      sig { params(preview: T.untyped, email: String, guard: Guard).void }
-      def assert_preview_quality(preview, email, guard: ActiveMail::Quality.guard)
-        assert_email_quality(PreviewRenderer.render(preview, email), guard: guard)
+      sig do
+        params(preview: T.untyped, email: String, guard: Guard, locale: Symbol, around_each: T.nilable(Proc)).void
+      end
+      def assert_preview_quality(preview, email, guard: ActiveMail::Quality.guard, locale: I18n.default_locale,
+                                 around_each: ActiveMail::Quality.config.around_each)
+        assert_no_quality_violations(preview_violations(preview, email, locale, guard, around_each))
       end
 
       module ClassMethods
         extend T::Sig
 
-        # One test per discovered preview; a non-required preview that can't render
-        # is skipped, a required one fails (see #render_preview_or_skip).
         sig { params(guard: Guard).void }
         def assert_quality_for_all_previews(guard: ActiveMail::Quality.guard)
-          required = ActiveMail::Quality.config.required_previews
-          previews = PreviewRenderer.all
+          config = ActiveMail::Quality.config
+          cases = PreviewRenderer.cases(config)
           # A silent no-test run would look like everything passed.
-          Kernel.warn('[activemail] assert_quality_for_all_previews: no previews discovered.') if previews.empty?
-          previews.each_with_index do |(preview, email), i|
-            key = PreviewRenderer.key(preview, email)
+          Kernel.warn('[activemail] assert_quality_for_all_previews: no previews discovered.') if cases.empty?
+          cases.each_with_index do |(preview, email, locale), i|
             # Index prefix: distinct keys can normalize to the same method name.
-            T.unsafe(self).define_method("test_#{i}_#{key.gsub(/\W/, '_')}_email_quality") do
-              html = T.unsafe(self).send(:render_preview_or_skip, preview, email, key, required)
-              T.unsafe(self).assert_email_quality(html, guard: guard)
+            name = "test_#{i}_#{PreviewRenderer.key(preview, email).gsub(/\W/, '_')}_#{locale}_email_quality"
+            T.unsafe(self).define_method(name) do
+              violations = T.unsafe(self).send(:render_preview_or_skip, preview, email, locale, guard, config.required_previews)
+              T.unsafe(self).send(:assert_no_quality_violations, violations)
             end
           end
         end
@@ -50,13 +48,31 @@ module ActiveMail
 
       private
 
-      # Returns rendered HTML; a non-required preview that fails is skipped (not a
-      # silent pass), a required one fails. flunk/skip are injected by Minitest; both raise.
-      sig { params(preview: T.untyped, email: String, key: String, required: T::Array[String]).returns(String) }
-      def render_preview_or_skip(preview, email, key, required)
-        PreviewRenderer.render(preview, email)
+      sig { params(violations: T::Array[Guard::Violation]).void }
+      def assert_no_quality_violations(violations)
+        # assert is injected by the host's Minitest test class.
+        T.unsafe(self).assert violations.empty?,
+                              "email quality violations:\n#{violations.map { |v| "  - #{v}" }.join("\n")}"
+      end
+
+      sig do
+        params(preview: T.untyped, email: String, locale: Symbol, guard: Guard, around_each: T.nilable(Proc))
+          .returns(T::Array[Guard::Violation])
+      end
+      def preview_violations(preview, email, locale, guard, around_each)
+        PreviewRenderer.within(preview, email, locale, around_each) { |mail| guard.violations(mail) }
+      end
+
+      # A non-required preview that can't render is skipped, not a silent pass.
+      sig do
+        params(preview: T.untyped, email: String, locale: Symbol, guard: Guard, required: T::Array[String])
+          .returns(T::Array[Guard::Violation])
+      end
+      def render_preview_or_skip(preview, email, locale, guard, required)
+        preview_violations(preview, email, locale, guard, ActiveMail::Quality.config.around_each)
       rescue StandardError => e
-        msg = "#{key} did not render (#{e.class}: #{e.message})"
+        key = PreviewRenderer.key(preview, email)
+        msg = "#{key} [#{locale}] did not render (#{e.class}: #{e.message})"
         required.include?(key) ? T.unsafe(self).flunk("required preview #{msg}") : T.unsafe(self).skip(msg)
       end
     end