You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Note that flags which have an attached value, like above, must take the form `-flag=value` and if `value` has spaces `-flag="value with spaces"`.
77
72
78
-
### Generated Test Suites
79
-
80
-
Generated test suites use the `bin/generator` cli.
81
-
82
-
Before using the cli it is recommended you run `bundle install` from within the ruby directory to install/update any required gems.
83
-
84
-
While many of the exercises which have canonical data already have generators, some do not.
85
-
To find out whether an exercise has a generator, run
86
-
87
-
bin/generate -h
88
-
89
-
In addition to a usage message, the `-h` flag lists all exercises with a generator.
90
-
If a generator is available for your exercise, you can
91
-
92
-
*[Regenerate the test suite][#regenerating-an-exercise] based on updated canonical data
93
-
*[Make changes to a generated exercise][#changing-a-generated-exercise]
94
-
95
-
If not, you will need to [implement a new generator][#implementing-a-generator].
96
-
97
-
Generated exercises depend on the [the shared metadata][problem-specifications], which must be cloned to the same directory that contains your clone of the ruby repository:
98
-
99
-
```text
100
-
tree -L 1 ~/code/exercism
101
-
├── problem-specifications
102
-
└── ruby
103
-
```
104
-
To explain a bit more, you must follow this commands step-by-step:
Next, you need to [configure the remote](https://help.github.com/articles/configuring-a-remote-for-a-fork/) and [synchronize](https://help.github.com/articles/syncing-a-fork/) it.
119
-
120
-
Make sure you have synced up local `main` branch and upstream `main` branch.
121
-
Since this will keep local `main` branch up-to-date with the upstream repository.
122
-
Thereby, you will able to get the latest commits.
123
-
124
-
#### Regenerating a Test Suite
125
-
126
-
From time to time, the [canonical data][canonical data] for an exercise's tests changes, and we need to keep the Ruby version's tests synced up.
127
-
Regenerating these tests is a quick and easy way to help maintain the track and get involved!
128
-
129
-
If it's your first time cloning/contributing to the repository, you'll need to install any dependencies via `bundle`:
130
-
131
-
```sh
132
-
bundle install
133
-
```
134
-
135
-
Be sure that you're working on the most up-to-date version of the repo.
136
-
From the root of your copy of the repository:
137
-
138
-
```sh
139
-
# Add the exercism repo as upstream if you haven't yet:
# Merge any upstream changes with your `main` branch
146
-
git checkout main
147
-
git merge upstream/main
148
-
```
149
-
150
-
Depending on your git workflow preferences and the state of your local repo, you may want to do some rebasing.
151
-
See the [rebasing documentation][rebasing documentation] for more information.
152
-
153
-
The generator also depends on the presence of Exercism's `problem-specifications` repository (see the file tree in the section above).
154
-
Make sure you've got an *up-to-date* version of the specifications in a `problem-specifications` folder that's in a parallel directory to your local copy of the `ruby` repository.
155
-
156
-
To check which problems have possibly been updated, run:
157
-
158
-
```sh
159
-
bin/generate --all
160
-
```
161
-
162
-
This will autogenerate all of the test cases for which generators exist.
163
-
Use `git diff` (or your preferred method) to find out which test files have changed.
164
-
Some exercises will update because someone updated the description or other exercise metadata.
165
-
Others will change because the actual test suite has changed.
166
-
167
-
Once everything has been regenerated and updated, you're almost ready to submit your changes via pull request.
168
-
Please be sure to only update one exercise per pull request.
169
-
Also, please follow the guidelines in the [Pull Requests][#pull-requests] section, being sure to follow the pattern of `<slug>: Regenerate Tests`, where slug is the slug of the exercise that your pull request is regenerating.
170
-
171
-
#### Changing a Generated Exercise
172
-
173
-
Do not edit `<slug>/<exercise_name>_test.rb`.
174
-
Any changes you make will be overwritten when the test suite is regenerated.
175
-
176
-
There are two reasons why a test suite might change:
177
-
178
-
1. the tests need to change (an incorrect expectation, a missing edge case,
179
-
etc)
180
-
1. there might be issues with the style or boilerplate
181
-
182
-
In the first case, the changes need to be made to the `canonical-data.json` file for the exercise, which lives in the problem-specifications repository.
This change will need to be submitted as a pull request to the problem-specifications repository.
192
-
This pull request needs to be merged before you can regenerate the exercise.
193
-
194
-
Changes that don't have to do directly with the test inputs and outputs should be made to the exercise's test case generator, discussed in [implementing a new generator][#implementing-a-generator], next.
195
-
Then you can regenerate the exercise with `bin/generate <slug>`.
196
-
197
-
#### Implementing a Generator
198
-
199
-
An exercise's test case generator class produces the code that goes inside the minitest `test_<whatever>` methods.
200
-
An exercise's generator lives in `exercises/<slug>/.meta/generator/<exercise_name>_case.rb`.
201
-
202
-
The test case generator is a derived class of `ExerciseCase` (in `lib/generator/exercise_case.rb`).
203
-
`ExerciseCase` does most of the work of extracting the canonical data and provides you with some accessor methods to access the values you are likely to need to use.
204
-
205
-
For example:
206
-
207
-
If a section of the `canonical-data.json` file looks like this:
208
-
209
-
```json
210
-
, { "description": "Bar'ing a name with numbers gives an error"
211
-
, "property" : "bar"
212
-
, "input" : {
213
-
"firstName" : "HAL",
214
-
"lastName" : "9000"
215
-
}
216
-
, "expected" : { "error": "You should never bar a number" }
217
-
}
218
-
```
219
-
220
-
You will be able to access input['firstName'] by the Ruby methods `first_name` (or `input_first_name`).
221
-
222
-
And the `expected["error"]` as: `error` or `expected_error`.
223
-
224
-
If there is a property name conflict the "input" version will take precedence, or you can use the `input_` and `expected_` prefixes to disambiguate.
225
-
226
-
The test template you need to write looks like this:
227
-
228
-
```ruby
229
-
require'generator/exercise_case'
230
-
231
-
class <ExerciseName>Case<Generator::ExerciseCase
232
-
233
-
defworkload
234
-
# Example workload:
235
-
"#{assert} Problem.call(#{input.inspect})"
236
-
end
237
-
238
-
end
239
-
```
240
-
241
-
where `<ExerciseName>` is the CamelCased version of the exercise's slug.
242
-
This is important, since the generator script will infer the name of the class from `<slug>`.
243
-
244
-
This class must provide the methods used by the test template.
245
-
A [default template][default template] that most exercises can (and do) use lives in `lib/generator/test_template.erb`.
246
-
The base class provides methods for the default template for everything except `#workload`.
247
-
248
-
`#workload` generates the code for the body of a test, including the assertion and any setup required.
249
-
The base class provides a variety of [assertion][assertion] and [helper][helper] methods.
250
-
251
-
Beyond that, you can implement any helper methods that you need as private methods in your derived class.
252
-
See below for more information about [the intention of #workload][#workload-philosophy]
253
-
254
-
You don't have to do anything other than implement `#workload` to use the default template.
255
-
256
-
If you really must add additional logic to the view template, you can use a custom template.
257
-
Copy `lib/generator/test_template.erb` to `.meta/generator/test_template.erb` under your exercise directory and customize.
258
-
You may need to create `.meta` and/or `.meta/generator`.
259
-
260
-
#### Workload philosophy.
261
-
262
-
Prioritize educational value over expert comprehension and make sure that
263
-
things are clear to people who may not be familiar with Minitest and even Ruby.
264
-
265
-
Provide the information the student needs to derive the code to pass the test in a clear and consistent manner.
266
-
Illustrate the purpose of the individual elements of the assertion by using meaningful variable names.
0 commit comments