A small library catalogue is a useful place to learn engineering because its promises can be made concrete. A reader should find a known item, narrow a topic search and understand a missing date. Each promise can become a requirement, and each requirement can be checked against a carefully chosen example.
This guide develops a fictional six-record catalogue. It includes a complete teaching dataset, explicit search rules, acceptance cases, a traceability table and a change exercise. It is a design workshop, not a deployed application. The expected results are worked out from the specification; no performance, accessibility or user-study result is claimed for a live system.
You need no programming language. You can follow the whole exercise with paper cards or a spreadsheet. By the end, you should be able to replace “make it easy to use” with a small set of observable behaviours and explain what a passing test does, and does not, establish.
This case belongs to the Engineering, Computing and Technology Library. Read What Is Engineering? for the broader discipline. The focus here is the bridge from a reader’s need to a requirement and then to evidence about whether a proposed catalogue meets it.
Begin with two reader tasks
Our first reader remembers the title “A River Atlas” and wants to identify the right catalogue record. Our second reader wants print material about rivers and needs to see which matching items have known publication years. These tasks are narrower than “help everyone find everything,” which cannot guide a small first version.
The catalogue describes resources rather than lending individual physical copies. It does not manage reservations, membership, payment or a loan queue. A record identifier distinguishes one catalogue entry; it is not a claim that the entry has a globally recognised identifier or a complete bibliographic description.
This boundary matters when two records share a title. They might describe different editions or formats rather than accidental duplication. A real library would need a fuller policy for works, editions, copies and authority records. For this exercise, each identifier refers to exactly one supplied resource description, and title alone does not determine identity.
The two reader tasks give us a way to judge proposed features. A visual animation may be attractive without helping either task. A visible format label directly helps the second task. Scope is not a ban on future improvements; it is a statement of what this version promises and what evidence will be relevant to accepting it.
The complete teaching dataset
All six resources below are invented. Their creator names are fictional, and the titles are teaching labels rather than recommendations or references to published works. The em dash in the year column means that the publication year is unknown. It does not mean zero, the current year or the year the record was entered.
| ID | Title | Creator | Year | Format | Topic |
|---|---|---|---|---|---|
| C01 | A River Atlas | Mira Tan | 2020 | rivers | |
| C02 | River Stories | Arun Lee | 2018 | audio | rivers |
| C03 | Bridge Design Notes | Noor Lim | 2022 | bridges | |
| C04 | Reading Old Maps | Mira Tan | — | maps | |
| C05 | A River Atlas | Mira Tan | 2024 | digital | rivers |
| C06 | River Walks | Jo Sen | 2021 | rivers |
Keeping the dataset this small is deliberate. Every expected result can be checked by a person, so an error in a search rule is less likely to hide behind a large output. The records include useful contrasts: a repeated title, several formats, a missing year and a creator appearing more than once.
Save this dataset as version 1 for the exercise. If you add a seventh record, an old expected result might need to change even when the search implementation is correct. A test report therefore needs both the catalogue version and the requirement version. “It worked yesterday” is incomplete when yesterday’s data differ from today’s.
Define the search before designing the screen
Version 1 uses one keyword box. A query is matched as a contiguous piece of text within the title or creator field, ignoring letter case and spaces at the beginning or end of the query. It does not search year, identifier, format or topic. Topic and format have separate filters.
This is a deliberately simple rule. The query “river” matches “A River Atlas,” “River Stories” and “River Walks.” The query “MIRA” matches the three records with creator Mira Tan. The query “2024” matches no record because the year is outside the keyword search fields. That result is correct under this specification, even if another catalogue would sensibly choose different behaviour.
Multiple words remain one contiguous query in this first version. “river atlas” matches the two atlas titles; “atlas river” does not. There is no stemming, spelling correction, synonym expansion or translation. Those are possible later requirements, each with consequences that should be discussed rather than assumed.
An empty query, including a query consisting only of spaces, means that keyword search places no restriction on results. This makes browsing possible. Topic and format filters still apply, and the interface should make the active filters visible so that a reader can understand why some records are absent.
State how the filters combine
The topic filter offers all topics, rivers, bridges or maps. The format filter offers all formats, print, audio or digital. Selecting a specific value requires an exact match to that field. The keyword condition, topic condition and format condition combine with AND: a record must satisfy every active condition.
With keyword “river” and format print, C01 and C06 match. C02 has a matching title but the wrong format. C05 also has a matching title but is digital. With keyword “Mira” and topic maps, only C04 matches. The creator condition finds three records, then the topic condition retains one.
This distinction is easy to miss in a demonstration. A catalogue that combines filters with OR would return many plausible-looking records while failing the intended narrowing task. Correctness is not measured by whether the result list looks relevant in general. It is measured against the declared meaning of the controls.
For version 1, default ordering is identifier ascending: C01 before C02, and so on. A year-ascending option places known years from earliest to latest, with unknown years last. Ties on known year are broken by identifier ascending. The rule produces a repeatable order rather than allowing records to jump around unpredictably between checks.
Turn the decisions into requirements
NASA’s How to Write a Good Requirement discusses clarity, individual obligations, traceability and the ability to verify a requirement. We apply those general engineering principles to our own small catalogue. This is not a NASA-approved design or a claim that a classroom catalogue must follow an aerospace process.
The following requirements describe observable behaviour. The accompanying definitions in the preceding sections are part of this teaching specification. Each identifier gives us a stable way to discuss a change or connect a test to its purpose.
| Requirement | Observable obligation |
|---|---|
| R01 | Every result displays its record ID, title, creator, year status, format and topic. |
| R02 | Keyword results follow the title-or-creator substring rule defined above. |
| R03 | Topic and format selections combine with the keyword condition using AND. |
| R04 | Default result ordering is record ID ascending. |
| R05 | Year-ascending ordering places unknown years last and resolves known-year ties by ID. |
| R06 | An unknown publication year displays as “Year unknown.” |
| R07 | An empty result set displays “No matching records” and a way to clear the search. |
| R08 | Clearing the search restores an empty query, both filters to all, and default ordering. |
| R09 | A duplicate record ID is rejected during catalogue maintenance without changing existing records. |
R01 groups a defined record display as one output obligation. If fields acquire separate complex rules, split those rules into their own requirements. R06 already does this for the most error-prone field. Requirement identifiers should clarify responsibility, not create a ceremony around every label on a page.
Keep rationale beside the rule
R05 places unknown years last because the reader searching chronologically should see a known sequence before entries whose position cannot be established. This is a design choice, not a universal law of catalogues. Another interface might offer an explicit unknown-year group. The important point is that the chosen behaviour is visible and testable.
R09 prevents two distinct rows from claiming the same identity. It does not prohibit repeated titles: C01 and C05 are intentionally both called “A River Atlas.” Their years and formats distinguish the descriptions in this dataset. Rejecting every repeated title would incorrectly remove a legitimate record.
R08 defines a complete reset so that a hidden format filter does not remain active after the reader thinks they have started again. Without this detail, one developer might clear only the keyword while another clears all controls. Both could claim to have implemented “clear search,” leaving the reader to discover the difference.
Rationale explains why a requirement exists. It should not quietly add another untested obligation. If the explanation says that the catalogue “also remembers every reader’s preferences,” that is a new feature requiring a separate decision about need, data handling and scope. Keep explanatory prose from becoming an accidental second specification.
Write an acceptance case before running it
An acceptance case names the starting state, the action and the expected observable outcome. “Search works” is not enough. A reproducible case says that version 1 is loaded, the controls have been reset, the reader enters a particular query and the expected ordered identifiers are specified.
For the known-title task: given the six version-1 records and cleared controls, when the reader searches for “river atlas,” the expected result IDs are C01, C05, in that order. Both records should show their years and formats. Returning only C01 would conceal the digital description; returning C06 would violate the contiguous-query rule.
The expected result is determined from the requirement and fixture before observing an implementation. If we copy whatever a prototype returns into the expected column, the test loses its independent checking role. A mistake can then pass merely because it is repeatable.
The actual result belongs in a separate field, together with the environment and the observed status. Use pass, fail or not run. A planned case with an expected result is not run until someone performs the check on an actual implementation. This article supplies the specification and worked expectations, not fabricated execution receipts.
The core acceptance set
Each case below starts with version 1 and cleared controls unless it says otherwise. Expected IDs are listed in their required order. These cases are designed to distinguish meaningful behaviours, rather than repeat the same successful search with cosmetic variations.
| Case | Action | Expected ordered IDs or outcome |
|---|---|---|
| T01 | Search river atlas | C01, C05 |
| T02 | Search with leading and trailing spaces around MIRA | C01, C04, C05 |
| T03 | Search river; select print | C01, C06 |
| T04 | Search Mira; select maps | C04 |
| T05 | Search river; select bridges | No matching records |
| T06 | Leave query empty; select audio | C02 |
| T07 | Search 2024 with all filters | No matching records |
| T08 | Empty query; all filters; year ascending | C02, C01, C06, C03, C05, C04 |
| T09 | Inspect C04 | Year unknown; other fields remain visible |
| T10 | After T03, clear the search | C01, C02, C03, C04, C05, C06; controls reset |
| T11 | Attempt to add another record using C01 | Rejected; the original six records are unchanged |
| T12 | Search atlas river | No matching records |
T02 checks two defined normalisation behaviours together: case-insensitive comparison and trimming outer spaces. If it fails, separate checks can isolate which behaviour is wrong. T12 distinguishes contiguous substring matching from a more generous word-order-insensitive search. T07 distinguishes the declared search fields from an implementation that searches every field accidentally.
The set is useful but not exhaustive. It does not establish how the catalogue handles every writing system, enormous datasets or every assistive technology. Tests earn confidence within their exercised scope. A small honest test set is more informative than a broad claim that “all edge cases pass” without a defined boundary.
Work through one case record by record
Take T03: query river, format print, all topics, default order. C01 contains river in its title and has format print, so it passes both active conditions. C02 contains river but has format audio, so it fails. C03 is print but contains no river in its title or creator, so it also fails.
C04 is print but its searchable fields do not contain river. C05 contains river but is digital. C06 contains river and is print. The surviving identifiers are C01 and C06, which are already in ascending identifier order. This is a complete derivation of the expected result from the fixture.
Now imagine a prototype returns C01, C02, C03, C04, C05 and C06. That pattern suggests it may be treating keyword and format as alternatives: records matching either condition appear. The observation is a diagnostic clue, not a proof of the internal implementation. Several different defects could produce the same outward result.
A helpful failure report therefore records the action, expected IDs and actual IDs before offering a hypothesis. “T03 returned all six records; expected C01 and C06” is actionable. “The developer misunderstood logic” assigns a cause and a person before the evidence establishes either.
Trace each check back to a reader need
| Reader need | Requirement connection | Useful acceptance evidence |
|---|---|---|
| Identify the remembered atlas | R01, R02, R04 | T01 returns both descriptions in a stable order |
| Find print resources on rivers | R02, R03 | T03 retains only records meeting both conditions |
| Avoid treating missing dates as facts | R05, R06 | T08 and T09 place and label C04 correctly |
| Recover from an unproductive search | R07, R08 | T05 shows an empty state; T10 resets controls |
| Maintain distinct record identities | R09 | T11 preserves existing records when an ID is reused |
This table is traceability in practical form. If someone proposes removing the year-unknown label, the affected reader need and tests are visible. If a requirement has no identifiable reader, maintainer or operational purpose, ask why it is included. If a reader task has no supporting requirement, the specification may be incomplete.
Traceability also exposes tests that do not check the behaviour they claim to cover. T08 verifies ordering in the fixture, but by itself it does not check the exact visible phrase “Year unknown.” T09 supplies that inspection. A link in a table is a statement to examine, not automatic evidence of coverage.
For a larger project, this relationship can be managed in a dedicated tool. For six records, a short maintained table is enough. The engineering value lies in making dependencies inspectable, not in choosing the most elaborate tracking software available.
Verification and validation in this case
Verification asks whether the implementation satisfies the stated requirements. Does T03 return the required pair? Does C04 show the agreed label? Validation asks whether the specified system serves the intended readers’ tasks in its context. A catalogue can implement a confusing search rule perfectly and still frustrate people who expect another behaviour.
Imagine a reader entering “atlas river” because they remember both words but not their order. Version 1 correctly returns no matches. That is a verification success under R02 and T12. Repeated difficulty with this task could nevertheless be validation evidence that the chosen rule needs revision.
A small formative session could ask volunteers to find the remembered atlas and identify a print river resource. Observe where they hesitate, which controls they notice and whether they understand the two atlas descriptions. Obtain appropriate agreement to participate and use fictional tasks and records. This guide reports no such session as completed.
The response to difficulty should be specific. Perhaps the label should explain phrase matching; perhaps word-order-insensitive matching is worth adding. Do not call the person careless because the implementation met its specification. The specification is itself a design proposal that can be improved through evidence about use.
Add accessible interaction requirements carefully
A reader should be able to operate the keyword box, filters, search action, clear action and result links with a keyboard. The focused control should be visible, and each control should have a meaningful accessible name. These are sensible requirements to develop and test on the actual interface; a static article cannot certify them for a future application.
A proposed keyboard case starts at the top of the catalogue with no pointing device. The tester reaches each control in a logical sequence, enters river, selects print, submits the search, inspects the result links and clears the search. The report records where focus moved and whether every required action was possible.
Do not equate a successful keyboard sequence with complete accessibility. Screen-reader output, zoom, contrast, error communication and other needs require their own appropriately scoped checks. Conversely, an accessibility issue is not merely cosmetic if it prevents a reader from completing the central task.
For a paper prototype, you can still examine language, reading order and whether state is clear. You cannot use that paper exercise as proof that a browser’s focus behaviour works. Match the evidence to the property under discussion, and carry untested interaction requirements forward explicitly.
Replace vague performance promises
“The catalogue will be fast” does not specify what to measure. Are we timing the first page load, the search response or the appearance of all result text? On what device, connection and dataset? A performance requirement needs a defined event, environment, load and threshold before a number can be interpreted.
For a classroom prototype, the team might first record response times under an agreed local setup and use those observations to propose a reasonable target. Until that target is agreed and tested, it remains an open requirement. Inventing a two-second promise without knowing the environment does not make the design more rigorous.
A useful measurement note names the dataset version, browser and device, network condition, action timed and repeated observations. It distinguishes a cold first load from subsequent searches where resources may already be available. If reporting a percentile, define the calculation and retain the observations needed to check it.
The six-record acceptance fixture checks functional meaning. It is not a performance workload for a million-record service. Keep these purposes separate so that a quick result on a tiny fixture is not presented as evidence that a future large catalogue meets a performance target.
Handle changes without losing the old agreement
Suppose readers need multiword searches to work in either order. The team proposes version 2: split a query into words at spaces, then require each word to occur somewhere in the combined title and creator text, ignoring case. The words need not be adjacent or in the same field. Topic and format still combine with the keyword condition using AND.
Under this new rule, “atlas river” should return C01 and C05. The previous T12 expectation must change, with a note that the requirement changed deliberately. A failing old test is not necessarily a regression if it tests behaviour that has been explicitly replaced. Quietly editing the expected result without recording the change would conceal that distinction.
Add a new case: “Mira atlas” should return C01 and C05 because one word appears in the creator and the other in the title. “Mira maps” should return C04. These examples check the new cross-field word rule rather than merely the reversal that motivated the change.
Retain checks for filters, missing years, reset and identity preservation. Changing keyword behaviour should not accidentally turn AND filters into OR filters or erase the unknown-year label. This is the practical meaning of regression testing: preserve still-required behaviour while accepting an intentional, documented change.
A second change exposes an identity mistake
Now add fictional record C07: “A River Atlas,” creator Mira Tan, year 2024, format print, topic rivers. The title and year repeat information from C05, but the format differs. Under our catalogue’s record policy, C07 is a separate supplied description with a new identifier and is permitted.
Under version-1 search rules with the expanded dataset, “river atlas” now returns C01, C05 and C07 in identifier order. Query river with format print returns C01, C06 and C07. Year-ascending order places C05 before C07 because both have known year 2024 and the tie is broken by ID.
The new fixture requires updated expected results for affected tests. It does not justify rewriting every case. T09 still inspects C04’s unknown date; T07 still finds no keyword match for 2024 under version 1. Record which expectations changed because the dataset changed, rather than describing all differences as code defects.
A real catalogue might decide that these records need more edition details before publication. That is a metadata-quality question beyond this fixture’s deliberately limited fields. Use How Metadata Standards and Interoperability Work when moving from the teaching model to a richer descriptive system.
Practice: diagnose the proposed test
Try these questions using the original six records and version-1 rules unless a question explicitly changes them. Explain the reason for each answer, not just the expected identifiers.
- A tester searches Mira and expects only C01 because it is the first familiar result. Is the expectation correct?
- A catalogue returns C01, C02, C05 and C06 for river with the print filter. Which declared behaviour has not been met?
- A maintainer rejects C05 because C01 has the same title. Does R09 require that rejection?
- C04 appears first in year-ascending order because the implementation stores missing years as zero. Is that acceptable?
- A test has a written expected result but no observation from a prototype. Should it be marked pass?
- A reader fails to find the atlas with atlas river, and the system returns no results. Is that necessarily an implementation defect in version 1?
- What additional case would check that reset clears a topic filter as well as a format filter?
- A prototype passes every six-record search case. What major claim about scale remains unestablished?
For a useful extension, write one new test that distinguishes two plausible implementations. Avoid merely changing river to RIVER unless you are specifically checking case handling. A case earns its place when it reveals a meaningful uncertainty about required behaviour.
Answers and engineering commentary
Question 1: Mira matches the creator field of C01, C04 and C05. Familiarity with one result does not define completeness. The expected output should contain all three in identifier order. This is why an independent fixture derivation is valuable before observing the prototype.
Question 2: The print filter has not narrowed the matching set as R03 requires. C02 is audio and C05 is digital. The correct ordered result is C01, C06. The observed result suggests that the format condition was ignored or misapplied, but further inspection is needed to identify the internal cause.
Question 3: No. R09 concerns duplicate identifiers, not duplicate titles. C01 and C05 have different IDs and describe different formats and years. A title-based rejection would impose a different identity rule that conflicts with the supplied fixture.
Question 4: No. R05 explicitly places unknown years last, and R06 labels the uncertainty. Treating unknown as zero creates a false chronological position. An internal representation is acceptable only if the required outward meaning is preserved.
Question 5: No. The status is not run. A well-designed expectation is valuable preparation, but it is not evidence of actual behaviour. Marking it pass would make the report claim an observation that never occurred.
Question 6: No. The empty result satisfies the version-1 contiguous-query rule. The difficulty may support changing that rule after considering the reader’s need. That is a validation and design question, distinct from a failure to implement the current requirement.
Question 7: Select topic maps, confirm C04 appears, then clear the search. Expect all six records in default order and the topic control returned to all. Inspect the control state as well as the list, because a coincidentally broad result would not establish that reset works correctly.
Question 8: Performance and suitability at substantially larger scale remain unestablished. The fixture also does not cover every writing system, accessibility context or operational maintenance condition. A passing functional set should be reported with its dataset and requirement boundary.
A delayed transfer task
Tomorrow, design a paper catalogue for four fictional plants. Give each an ID, common name, light requirement and watering category. Define one search rule and two filters. Then write three acceptance cases: a successful combination, an empty result and a reset from a restricted view.
Your cases should name exact expected IDs. If a plant fits one filter but fails the other, explain whether the rule includes or excludes it. Add one missing value and decide how it should appear. You are transferring the requirement-to-evidence relationship, not memorising the six library records.
Review your work by asking whether another person could perform each check without guessing your intention. If they cannot tell what “suitable plants” means or which field the search examines, revise the specification before expanding the test list. Clear requirements reduce the amount of interpretation hidden inside a supposedly objective pass or fail.
Continue from the prototype to the wider library
Use What Is Computer Science? for the wider ideas behind computation and data. Use What Is Project Management? when coordinating changes, responsibilities and delivery decisions. The Guided Reading and Inquiry hub connects this workshop to other forms of evidence-based practice.
Keep three small artefacts together when you use the method: the versioned fixture, the agreed requirements and the test record separating expected from actual results. They let someone reconstruct what was promised, what was checked and what remains unknown. That is the practical foundation for improving a catalogue without losing track of what its readers depend on.