Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T23:26:21Z

Samason4: /* Model Overview & Test Implementation */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

We are unable to find anything that invokes this view_translation_subsitutor throughout the rest of the expertiza code base, so we have created unit tests to verify its functionality independently to ensure that it integrates smoothly with other modules without any issues.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
''Parameters:'' locale: A hash containing translation data organized by directory and view name.
''Returns:'' None

''Use Cases''

# The class replaces hardcoded strings in view templates with translated versions according to the provided locale hash.
# The class keeps the content of the Expertiza application up-to-date with the latest translations, maintaining consistency and relevance in multiple languages.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When interacting with a developer, the model can ensure consistent handling of translations across different parts of Expertiza.
# When interacting with a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When interacting with a developer, the model localizes static text elements while preserving dynamic content.
# When interacting with a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file, then the display placeholders indicating missing translations.
# When the filenames begin with an underscore, the files should be handled as if they don't begin with an underscore.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When interacting with a developer, the model will incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When interacting with a marketer, the model will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file, then the model will log the error.
# When the view file contains complex HTML structure with nested elements and dynamic content, the model will properly render the HTML file.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We were unable to test view_translation_substitutor.rb within Expertiza because it isn't called anywhere. We instead implemented unit tests that offer 100% coverage. We tested each of the four methods separately.

[https://github.com/CSC517-Project4/expertiza/blob/main/spec/models/view_translation_substitutor_spec.rb Link to Rspec Repository]

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T23:24:11Z

Samason4: /* Model Overview & Test Implementation */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

We are unable to find anything that invokes this view_translation_subsitutor throughout the rest of the expertiza code base, so we have created unit tests to verify its functionality independently to ensure that it integrates smoothly with other modules without any issues.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
''Parameters:'' locale: A hash containing translation data organized by directory and view name.
''Returns:'' None

''Use Cases''

# The class replaces hardcoded strings in view templates with translated versions according to the provided locale hash.
# The class keeps the content of the Expertiza application up-to-date with the latest translations, maintaining consistency and relevance in multiple languages.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When interacting with a developer, the model can ensure consistent handling of translations across different parts of Expertiza.
# When interacting with a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When interacting with a developer, the model localizes static text elements while preserving dynamic content.
# When interacting with a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file, then the display placeholders indicating missing translations.
# When the filenames begin with an underscore, the files should be handled as if they don't begin with an underscore.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When interacting with a developer, the model will incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When interacting with a marketer, the model will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file, then .
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We were unable to test view_translation_substitutor.rb within Expertiza because it isn't called anywhere. We instead implemented unit tests that offer 100% coverage. We tested each of the four methods separately.

[https://github.com/CSC517-Project4/expertiza/blob/main/spec/models/view_translation_substitutor_spec.rb Link to Rspec Repository]

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T22:53:20Z

Samason4: /* Method Descriptions */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

We are unable to find anything that invokes this view_translation_subsitutor throughout the rest of the expertiza code base, so we have created unit tests to verify its functionality independently to ensure that it integrates smoothly with other modules without any issues.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
''Parameters:'' locale: A hash containing translation data organized by directory and view name.
''Returns:'' None

''Use Cases''

# The class replaces hardcoded strings in view templates with translated versions according to the provided locale hash.
# The class keeps the content of the Expertiza application up-to-date with the latest translations, maintaining consistency and relevance in multiple languages.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When interacting with a developer, the model can ensure consistent handling of translations across different parts of Expertiza.
# When interacting with a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When interacting with a developer, the model localizes static text elements while preserving dynamic content.
# When interacting with a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file.
# When the filenames begin with an underscore, the files should be handled as if they don't.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When interacting with a developer, the model will incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When interacting with a marketer, the model will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file.
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We were unable to test view_translation_substitutor.rb within Expertiza because it isn't called anywhere. We instead implemented unit tests that offer 100% coverage. We tested each of the four methods separately.

[https://github.com/CSC517-Project4/expertiza/blob/main/spec/models/view_translation_substitutor_spec.rb Link to Rspec Repository]

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T22:51:50Z

Samason4: /* Method Descriptions */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

We are unable to find anything that invokes this view_translation_subsitutor throughout the rest of the expertiza code base, so we have created unit tests to verify its functionality independently to ensure that it integrates smoothly with other modules without any issues.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
''Parameters:'' locale: A hash containing translation data organized by directory and view name.
''Returns:'' None
''Use Cases''

# The class replaces hardcoded strings in view templates with translated versions according to the provided locale hash.
# The class keeps the content of the Expertiza application up-to-date with the latest translations, maintaining consistency and relevance in multiple languages.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When interacting with a developer, the model can ensure consistent handling of translations across different parts of Expertiza.
# When interacting with a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When interacting with a developer, the model localizes static text elements while preserving dynamic content.
# When interacting with a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file.
# When the filenames begin with an underscore, the files should be handled as if they don't.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When interacting with a developer, the model will incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When interacting with a marketer, the model will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file.
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We were unable to test view_translation_substitutor.rb within Expertiza because it isn't called anywhere. We instead implemented unit tests that offer 100% coverage. We tested each of the four methods separately.

[https://github.com/CSC517-Project4/expertiza/blob/main/spec/models/view_translation_substitutor_spec.rb Link to Rspec Repository]

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T22:48:27Z

Samason4: /* Model Overview & Test Implementation */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

We are unable to find anything that invokes this view_translation_subsitutor throughout the rest of the expertiza code base, so we have created unit tests to verify its functionality independently to ensure that it integrates smoothly with other modules without any issues.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
''Parameters:'' locale: A hash containing translation data organized by directory and view name.
''Returns:'' None
''Use Cases''

# The class replaces hardcoded strings in view templates with translated versions according to the provided locale hash.
# The class keeps the content of the Expertiza application up-to-date with the latest translations, maintaining consistency and relevance in multiple languages.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When interacting with a developer, they ensure consistent handling of translations across different parts of Expertiza.
# When interacting with a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When interacting with a developer, the model localizes static text elements while preserving dynamic content.
# When interacting with a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file.
# When the filenames begin with an underscore, the files should be handled as if they don't.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When interacting with a developer, they will leverage the model to incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When interacting with a marketer, they will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file.
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We were unable to test view_translation_substitutor.rb within Expertiza because it isn't called anywhere. We instead implemented unit tests that offer 100% coverage. We tested each of the four methods separately.

[https://github.com/CSC517-Project4/expertiza/blob/main/spec/models/view_translation_substitutor_spec.rb Link to Rspec Repository]

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T00:38:13Z

Samason4:

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
Parameters:
locale: A hash containing translation data organized by directory and view name.

''Returns:'' None

''Use Cases''

# When it is a developer, the model will replace hardcoded strings with translated versions.
# When it is a developer, Expertiza's content will always up-to-date with the latest translations.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When it is a developer, they ensure consistent handling of translations across different parts of Expertiza.
# When it is a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When it is a developer, the model localizes static text elements while preserving dynamic content.
# When it is a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file.
# When the view file contains ambiguous strings that may have multiple possible translations.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When it is a developer, they will leverage the model to incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When it is a marketer, they will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file.
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We implemented tests which offers 100% coverage for the view_translation_substitutor.rb.

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T00:37:59Z

Samason4: /* Tasks */

==E2439 Testing for view translation substitutor.rb==

This wiki page is for the description of changes made in Spring 2024, CSC/ECE 517 for the E2439 Testing for view translation substitutor.rb assignment.

__TOC__

==Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open source software project (OSS) using [http://rubyonrails.org/ Ruby on Rails] framework. Expertiza is led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Expertiza allows students to create different teams and work on various assignments and projects. Also, students have the capability to peer review and evaluate each other's work. In Expertiza, instructors have the ability to create new assignments and edit already existing projects. The instructor can use a filter to narrow a list of subjects for students. Expertiza allows submissions from PDFs, wiki pages and URLs document types.

==Project Objective==
This class ([https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb]) is designed to automate substituting text within view templates with translation keys. Our objective is to create tests in [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb] to cover various use and edge cases. Also, we must add detailed explanations for all the tests.

==Problem Statement==
The code coverage for [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb view_translation_substitutor.rb] started at 0%, indicating a need to enhance the test coverage, particularly by focusing on testing edge cases. According to the existing test file ([https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb view_translation_substitutor_spec.rb]), some methods may be broken. Adopting TDD could be an effective strategy to address and repair these methods.

==Files Modified==

* [https://github.com/CSC517-Project4/expertiza/blob/dev/app/models/view_translation_substitutor.rb app/models/view_translation_substitutor.rb]
* [https://github.com/CSC517-Project4/expertiza/blob/dev/spec/models/view_translation_substitutor_spec.rb app/spec/models/view_translation_substitutor_spec.rb]

==Plan of Work==
We will begin by inserting some debug statements into the model and running expertiza in order to find out when the model runs and what it is accomplishing. Once finished, we will determine what is wrong with the main method of the model, substitute() and fix it. Then, we will write tests to have 100% coverage of the model. After that, we will decide what edge cases may arise. Finally, we will write tests to cover the edge cases.

==Goals==
While implementing the view translation substitution functionality using the ViewTranslationSubstitutor class, the following design goals should be ensured:

* '''Goal #1:''' Determine the purpose and invocation timing of view_translation_substitutor.rb to understand its role in the application's internationalization process and ensure proper integration with the existing codebase.

* '''Goal #2:''' Debug and fix the substitute() method to ensure it correctly processes the locale hash, generates accurate translation statistics, and writes them to the YAML file, handling any edge cases or error scenarios that may arise.

* '''Goal #3:''' Write comprehensive test cases for the key methods of the ViewTranslationSubstitutor class, including substitute, process_directory, process_view, and process_translation, to validate their correctness, robustness, and adherence to the expected behavior.

* '''Goal #4:''' Extend the test suite to cover edge cases and exceptional scenarios, such as empty or invalid locale hashes, missing view files or directories, translation keys with special characters, and performance testing with large or complex view files, ensuring the class handles these situations gracefully and maintains its reliability.

==Model Overview & Test Implementation==
The ViewTranslationSubstitutor class is designed to assist in the internationalization process of applications by substituting hardcoded text strings in view templates with dynamic translation calls. It processes a given locale hash, iterates through directories and view files, and replaces identified strings with translations from the locale hash. Additionally, it generates statistics regarding the substitutions made during the process.

===Method Descriptions===

'''substitute(locale)'''

''Description:'' Processes the given locale hash by iterating through directories and view files, replacing hardcoded strings with translations, and generating statistics.
Parameters:
locale: A hash containing translation data organized by directory and view name.

''Returns:'' None

''Use Cases''

# When it is a developer, the model will replace hardcoded strings with translated versions.
# When it is a developer, Expertiza's content will always up-to-date with the latest translations.

''Edge Cases''

# When translation files are located within nested directories, all directories should be recursively traverse to ensure that no translations are missed.
# When there are various file types (JSON, YAML, or plain text files), it should handle different file formats and parsing methods.

<pre>
describe '#substitute' do
let(:substitutor) { ViewTranslationSubstitutor.new }

it 'iterates over the locale hash and processes directories' do
# Create a sample locale hash.
locale = {
'dir1' => { 'view1' => { 'key1' => 'val1' } },
'dir2' => { 'view2' => { 'key2' => 'val2' } }
}

# Expect process_directory to be called for each directory in the locale hash.
expect(substitutor).to receive(:process_directory).with('dir1', { 'view1' => { 'key1' => 'val1' } }).and_return('stats1')
expect(substitutor).to receive(:process_directory).with('dir2', { 'view2' => { 'key2' => 'val2' } }).and_return('stats2')

# Expect File.open to be called with a regex matching translation_stats*.yml and write the processed stats to YAML.
expect(File).to receive(:open).with(/^translation_stats.*\.yml$/, 'w').and_yield(file = double)
expect(file).to receive(:write).with({ 'dir1' => 'stats1', 'dir2' => 'stats2' }.to_yaml)

# Call the substitute method with the sample locale hash.
substitutor.substitute(locale)
end
end
</pre>

'''process_directory(dir_name, view_hash)'''

''Description:'' Processes a directory within the application, iterating through view files and replacing hardcoded strings with translations.
Parameters:
dir_name: Name of the directory being processed.
view_hash: Hash containing translation data for views within the directory.

''Returns:'' A hash containing statistics for each view within the directory.

''Use Cases''

# When it is a developer, they ensure consistent handling of translations across different parts of Expertiza.
# When it is a developer, the model can be integrated into workflows that utilize TMS platforms for managing translations.

''Edge Cases''

# When the model encounters directories or files with restricted permissions or inaccessible locations, there must be proper error handling.

<pre>
describe '#process_directory' do
let(:substitutor) { ViewTranslationSubstitutor.new }

context 'when view_hash is not empty' do
let(:dir_name) { 'dir1' }
let(:view_hash) { { 'view1' => { 'key1' => 'val1' } } }

it 'processes each view in the view_hash' do
# Stub process_view method to return 'stats1' and ensure it is called with correct arguments.
allow(substitutor).to receive(:process_view).and_return('stats1')
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({ 'view1' => 'stats1' })
expect(substitutor).to have_received(:process_view).with(dir_name, 'view1', { 'key1' => 'val1' })
end
end

context 'when view_hash is empty' do
# Local variables
let(:dir_name) { 'dir2' }
let(:view_hash) { {} }

it 'returns an empty hash' do
# Call the private method process_directory with an empty view_hash and ensure it returns an empty hash.
dir_stats = substitutor.send(:process_directory, dir_name, view_hash)
expect(dir_stats).to eq({})
end
end
end
</pre>

'''process_view(directory_name, view_name, translations)'''

''Description:'' Processes a specific view file, replacing hardcoded strings with translations and updating the file accordingly.
Parameters:
directory_name: Name of the directory containing the view file.
view_name: Name of the view file.
translations: Hash containing translation data for the specific view.

''Returns:'' A hash containing statistics for the translations made in the view file.

''Use Cases''

# When it is a developer, the model localizes static text elements while preserving dynamic content.
# When it is a developer, the model will update view files with specific messaging and translations.

''Edge Cases''

# When the translations parameter is empty or contains no translations for the specified view file.
# When the view file contains ambiguous strings that may have multiple possible translations.

<pre>
describe '#process_view' do
# Local variables
let(:substitutor) { ViewTranslationSubstitutor.new }
let(:directory_name) { 'test_folder' }
let(:view_name) { 'example_view' }
let(:translations) { { 'key1' => 'value1', 'key2' => 'value2' } }

context 'when the view file exists' do
before do
# Stub File.exist? to return true and File.open to yield "Existing content".
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the view file path.
expect(File).to have_received(:open).with("./#{directory_name}/#{view_name}.html.erb", 'w').twice
end
end

context 'when the view file does not exist' do
it 'returns "<file not found>"' do
# Call the process_view method and expect it to return "<file not found>".
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)
expect(view_stats).to eq('<file not found>')
end
end

context 'when the alternate view file exists' do
before do
# Stub File.exist? to return false for main view file and true for alternate view file.
allow(File).to receive(:exist?).with("./#{directory_name}/#{view_name}.html.erb").and_return(false)
allow(File).to receive(:exist?).with("./#{directory_name}/_#{view_name}.html.erb").and_return(true)
allow(File).to receive(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').and_yield(StringIO.new("Existing content"))
end

it 'reads the alternate file, processes translations, and writes back the contents' do
# Expect process_translation to be called for each translation and return modified content and stats.
expect(substitutor).to receive(:process_translation).with("Existing content", 'key1', 'value1').and_return(['stats1', 'new_content1'])
expect(substitutor).to receive(:process_translation).with('new_content1', 'key2', 'value2').and_return(['stats2', 'new_content2'])

# Call the process_view method and expect it to return processed view stats.
view_stats = substitutor.send(:process_view, directory_name, view_name, translations)

expect(view_stats).to eq({ 'key1' => 'stats1', 'key2' => 'stats2' })

# Expect File.open to be called twice with the alternate view file path.
expect(File).to have_received(:open).with("./#{directory_name}/_#{view_name}.html.erb", 'w').twice
end
end
end
</pre>

'''process_translation(contents, key, val)'''

''Description:'' Processes translations within the contents of a view file, replacing hardcoded strings with dynamic translation calls.
Parameters:
contents: Contents of the view file as a string.
key: Key representing the translation key.
val: Value representing the translation text.

''Returns:'' A tuple containing a hash of statistics for the translations made and the updated contents of the view file.

''Use Cases''

# When it is a developer, they will leverage the model to incorporate accessibility-focused translations and alternative text descriptions into view files for images, buttons, and other interactive elements.
# When it is a marketer, they will implement A/B test variations by dynamically swapping out hardcoded strings with alternative translations.

''Edge Cases''

# When the contents parameter contains invalid markup, preventing proper parsing of the view file.
# When the view file contains complex HTML structure with nested elements and dynamic content.

<pre>
describe '#process_translation' do
# Local variables
let(:contents) { 'This is a test string with some "text" to be replaced.' }
let(:key) { 'other word' }
let(:val) { 'text' }
let(:key2) { 'skipped key' }
let(:val2) { 'string' }
let(:key3) { 'non-existent key' }
let(:val3) { 'non-existent val' }

it 'replaces the correct text with translation keys' do
# Call process_translation with a valid key and value and expect correct replacements and modified content.
replacements, new_contents = substitutor.send(:process_translation, contents, key, val)

expect(replacements).to include("replacements" => ["\"#{val}\""])
expect(new_contents).to include("#{key}")
end

it 'adds to skip when one value is not found but another value is' do
# Call process_translation with a key and value that partially match the contents and expect skips and unmodified content.
skips, new_contents = substitutor.send(:process_translation, contents, key2, val2)

expect(skips).to include("skips" => ["test string with"])
expect(new_contents).not_to include("#{key2}")
end

it 'adds <unmatched> to translation_stats when there is no match' do
# Call process_translation with a key and value that do not match any part of the contents and expect <unmatched> and unmodified content.
translation_stats, new_contents = substitutor.send(:process_translation, contents, key3, val3)

expect(translation_stats).to include("<unmatched>")
expect(new_contents).not_to include("#{key3}")
end
end
</pre>

==Design Patterns & Principles==
'''Single Responsibility Principle (SRP)''':
* Each test case has a single responsibility and focuses on a specific aspect of the application.
* The different types of tests (unit, integration, and system) are separated in order to improve clarity and organization.

'''Don't Repeat Yourself Principle (DRY)''':
* Setup and cleanup steps for all tests are the same and thus, are combined together.

'''Open/Closed Principle (OCP)''':
* Test classes are designed so that they are open for extension. New tests can be added without needing to modify the existing test code.

'''Singleton Pattern''':
* There is only a single setup that is shared for all of the test cases that need to use it.

==Test Plan==
Test coverage is currently at 100%. We have written tests to ensure coverage of each of the four methods in view_translation_substitutor.rb. Then, we added tests to cover the edge cases.

====Demo Video====
[https://www.youtube.com/watch?v=C-fbMNsrTP8 Demo Video (Youtube)]
 
[https://vimeo.com/938411539?share=copy Demo Video (Vimeo)]

====Using RSpec====
We implemented tests which offers 100% coverage for the view_translation_substitutor.rb.

====How to See Test Coverage====
Run RSpec for view_translation_substitutor.rb, <code>sudo su</code>, <code>yum install lynx</code>, then <code>lynx ./coverage/index.html</code>.

We chose to use Lynx because it displays the test coverage in an easy and readable way.

==Results==
The image below shows the test cases are passing as well as most of the code climate issues were resolved.

view_translation_substitutor.rb model coverage = 100%

[[File:2439cov.png | 700px]]

==Future Work==
Implement view_translation_substitutor.rb in Expertiza to support internationalization.

==Team==
===Mentor===
Mustafa Olmez (molmez@ncsu.edu)

===Team Members===
Shandler Mason (samason4@ncsu.edu) 
Ben Morris (bcmorri4@ncsu.edu) 
Ray Wang (rwang32@ncsu.edu) 

==References==
# [https://github.com/expertiza/expertiza Expertiza GitHub]
# [https://github.com/CSC517-Project4/expertiza Project Repository]
# [https://github.com/orgs/CSC517-Project4/projects/1 Github Project Board]
# [https://github.com/expertiza/expertiza/pull/2800 Pull Request]
# [https://www.theodinproject.com/lessons/ruby-introduction-to-rspec RSpec]

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-24T00:33:51Z

Samason4: /* References */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:26:48Z

Samason4:

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:26:41Z

Samason4:

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:25:44Z

Samason4:

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:24:36Z

Samason4: /* Files Modified */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:24:11Z

Samason4: /* Files Modified */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:23:35Z

Samason4:

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:21:09Z

Samason4: /* Plan of Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:20:54Z

Samason4: /* Plan of Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:20:01Z

Samason4: /* Plan of Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:16:41Z

Samason4: /* Method Summaries */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:16:30Z

Samason4: /* Method Summaries: */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:16:18Z

Samason4: /* Model Overview & Test Implementation */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:15:32Z

Samason4: /* Problem Statement */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:14:51Z

Samason4: /* Project Objective */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:14:31Z

Samason4: /* Project Objective */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:11:42Z

Samason4: /* Problem Statement */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:11:19Z

Samason4: /* Project Objective */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:08:33Z

Samason4: /* Problem Statement */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:07:17Z

Samason4: /* Future Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:06:53Z

Samason4: /* Future Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:06:17Z

Samason4: /* Future Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:06:11Z

Samason4: /* Future Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:03:41Z

Samason4: /* Future Work */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:02:50Z

Samason4: /* Results */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:02:41Z

Samason4: /* Results */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:02:30Z

Samason4: /* Results */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:02:23Z

Samason4: /* Results */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:01:58Z

Samason4: /* How to See Test Coverage */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:01:48Z

Samason4: /* How to See Test Coverage */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-22T17:01:34Z

Samason4: /* Test Plan */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-19T17:09:32Z

Samason4: /* References */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T01:23:04Z

Samason4: /* How to See Test Coverage */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T01:22:49Z

Samason4: /* Using RSpec */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T01:21:03Z

Samason4: /* Model Overview & Test Implementation */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:32:34Z

Samason4: /* Model Overview & Test Implementation */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:11:08Z

Samason4: /* Tasks */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:10:17Z

Samason4: /* How to See Test Coverage */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:09:11Z

Samason4: /* Using RSpec */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:08:55Z

Samason4: /* Results */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:08:12Z

Samason4: /* Work Plan */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:06:21Z

Samason4: /* Model Overview & Test Implementation */

CSC/ECE 517 Spring 2024 - E2439 Testing for view translation substitutor.rb

2024-04-09T00:05:25Z

Samason4: /* Model Overview & Test Implementation */