diff --git a/README.md b/README.md index e4f5bca2..41bf7416 100644 --- a/README.md +++ b/README.md @@ -16,4 +16,7 @@ The ICT Baseline Alignment Validation Framework provides test cases as a way for ## How to Contribute Working Group members can use the [editor on GitHub](https://github.com/Section508Coordinators/BaselineTestPages/edit/master/README.md) to directly edit this file to add references. Members can also navigate to the [Baseline Test Pages repository](https://github.com/Section508Coordinators/BaselineTestPages) to add files to test. Static pages can be viewed via GitHub Pages from this repository at the following url: . -Contributors do not need to be highly technical nor make a long-term commitment, although both skills and time can certainly be helpful. The ICT Baseline Alignment Working Group needs help developing and evaluating test cases. Accessibility advocates are also needed to spread the word about the Framework, develop a governance structure, participate in governance, develop and maintain the website, provide user experience and plain language expertise, and even provide legal support. Please visit our [How You Can Help](https://section508coordinators.github.io/BaselineTestPages/contributing.html#helping) and [How We Work](https://section508coordinators.github.io/BaselineTestPages/contributing.html#how-we-work) sections or contact us at for more information about getting involved.. +Contributors do not need to be highly technical nor make a long-term commitment, although both skills and time can certainly be helpful. The ICT Baseline Alignment Working Group needs help developing and evaluating test cases. Accessibility advocates are also needed to spread the word about the Framework, develop a governance structure, participate in governance, develop and maintain the website, provide user experience and plain language expertise, and even provide legal support. Please visit our [How You Can Help](https://section508coordinators.github.io/BaselineTestPages/contributing.html#helping) and [How We Work](https://section508coordinators.github.io/BaselineTestPages/contributing.html#how-we-work) sections or contact us at for more information about getting involved. + +Ready to try your hand at creating a test case, test files, or both? Start by reading the [Guide for Developing Test Case and Test Files](https://section508coordinators.github.io/ICTTestingBaseline/testCaseGuide.html). + diff --git a/contributing.md b/contributing.md index 367caa8b..6d160bbd 100644 --- a/contributing.md +++ b/contributing.md @@ -5,9 +5,7 @@ title: Contributing to the ICT Baseline Alignment Framework # Contributing to the ICT Baseline Alignment Framework ## How you can help ### Developing and Evaluating Test Cases -Need content from people doing this work. What do you need? - -I have a note about issuing templates. Does that belong bundled with this topic? +Test Cases are essential for the Baseline Alignment Framework. These will be used to determine how well a test process aligns to the [ICT Testing Baseline for Web](https://ictbaseline.access-board.gov). If you would like to contribute to the collection of [test cases](testcases.html), please take a look at the [Guide for Developing Test Case and Test Files](testCaseGuide.html). All of the work is done on GitHub. Please email [ictbaseline@gsa.gov](mailto:ictbaseline@gsa.gov) with questions. ### Planning and Conducting Outreach We need people to know about our work so they can contribute and use it! Whether you enjoy giving presentations or would prefer to remain behind the scenes writing and editing, your skills are needed. Can you help with any of the following? diff --git a/testCaseGuide.html b/testCaseGuide.html new file mode 100644 index 00000000..ae9a238a --- /dev/null +++ b/testCaseGuide.html @@ -0,0 +1,151 @@ +--- +layout: page +title: Developing Test Cases and Test Files +--- +

Guide for Developing Test Cases and Test Files

+

Test cases and their related test files will be used to demonstrate expected outcomes for Baseline test instructions. Each test instruction is mapped in to their Section 508/WCAG requirements in Appendix A of the ICT Testing Baseline for Web.

+ +

A note on developer tools: some contributors use VSCode and others use notepad++, depending on what they are comfortable using or have access to. This work can all be done in the GitHub website, but some tasks would be much easier with a code editor.

+ +

Thank you for contributing your time and skills to this! And please contact us at ictbaseline@gsa.govif you have any questions.

+ +

Baseline Alignment Resources

+
    +
  1. Baseline for Web Alignment site - Test Cases page
    2. +
  2. Test Case map to Baseline Tests.xlsx - list of all test cases for development on Max.gov
    3. +
  3. Section508coordinators/baselinealignment – Baseline Alignment GitHub repository
    4. +
  4. ICT Testing Baseline for Web – where Baseline test instructions can be found
    5. +
  5. Our Youtube playlist for Contributing Test Cases
    6. +
+ +

Claim Your Test Case

+
    +
  1. Go to the Test Case map to Baseline Tests.xlsx on Max.gov to see a listing of all test cases that are needed.
    2. +
      +
    • This spreadsheet is used for tracking of all test case development.
      • +
    • All details for the test cases are included here, including a description of the test case and test file and filenames.
      • +
    +
  2. Enter your name (in the blank Assigned column) next to the test case you want to work on.
    3. +
  3. Change the status to “To Do” or “In Progress”, as appropriate.
    4. +
+ +

Develop the Test Case and Associated Files

+

Go to the Section508coordinators/baselinealignment GitHub repo and create a new branch for your work. If you've never used GitHub, you may want to start with Introduction to GitHub.

+ +

Create the Test File

+

The Test File contains the HTML code and includes any other supporting files needed.

+
    +
  1. Open an existing test file in the Baseline Alignment GitHub repo, such as baselinealignment/testfiles/TF06/06.1-1-fail-1.html. Or create the new test file from scratch.
    2. +
  2. Save with a new filename, in the appropriate “testfiles” sub-folder (/TF##). (Create a new /TF## folder if necessary.)
    3. +
      +
    • Obtain the filename from the spreadsheet. See the Test Case ID column and remove “TC”.
      • +
    • Test files follow this naming convention: [Baseline Test ID]-[test instruction #]-[pass/fail/dna]-[sequence # of this test].html
      • +
    +
  3. Edit/create the code in the HTML test file.
    4. +
  4. Ensure that the relevant code that you want displayed in the test case is enclosed in <div id="tc_code">. (A script is used to display this code snippet in the test case’s Test Detail section.) If you find that the relevant code cannot be enclosed in a <div>, please open an issue in the Baselinealignment GitHub repo.
    5. +
  5. Commit your changes (i.e., save or upload your files to your branch)
    6. +
+ +

Create the Test Case

+

The Test Case file contains the description the Baseline’s evaluation of the test file.

+
    +
  1. Open the "_testcase_template.md" file in the "Templates" folder in the GitHub repo. + Alternatively, you can open a published test case file from the "testcases" folder, such as TC06.1-1-fail-1.
    2. +
  2. Create a copy of the file.
    3. +
  3. Rename the duplicated file with the filename identified in the spreadsheet in the Test Case ID column. The file should be saved in the “testcases” folder. Test cases follow this naming convention:
    4. +
      +
    • TC[Baseline Test ID]-[test instruction #]-[pass/fail/dna]-[sequence #].md
      • +
    • Please note that the test case starts with “TC” and is markdown file format.
      • +
    +
  4. Update the content in the front matter (enclosed by “---"). Do not modify the lines that start with “#” or the identifier terms that precede a colon.
    5. +
      +
    • Please do not edit the special characters, spaces, and blank lines, as these were inserted to format and build the page correctly.
      • +
    • Below is a sample test case markdown file. The editable text follows the identifier term and colon (and sometimes, special character) in each section.
      • + + 
      +        # The layout must be 'testcase'; DO NOT Change layout: testcase
+        layout: testcase
+
+        # Brief, descriptive title for the test case
+        title: Image - no accessible name or description
+
+        # The Test Case ID should follow the pattern: 
+        # TC[Baseline Test Procedure #]-[Test Instruction #]-[Expected Result (pass/fail/dna)]-[example #], e.g., TC05.1-1-fail-1
+        tcid: TC06.1-1-fail-1
+    
+        # Description of the Test Case, the included code sample, test considerations,
+        # and rationale for the expected result according to the applicable ICT
+        # Baseline test
+    
+        descr: | (Developer note: please do not edit the syntax here, or your file may not render as expected. Start your description entry on the next line.)
+    
+        Detect existence of attributes that would contribute to the accessible name and accessible description computation and calculate the text alternative for the image.
+
+        The code sample data input does not include any attributes that would contribute to accessible name or accessible description output. A successful test should identify a failure against Baseline 6. Images.
+    
+        #Reference and link to the applicable ICT Baseline test
+        app-baseline: | (Developer note: please do not edit the syntax here, or your file may not render as expected. Start your Baseline link entry on the next line.)
+
+        [6.1 Test Procedure for Meaningful Images](https://section508coordinators.github.io/ICTTestingBaseline/06Images.html#61-test-procedure-for-meaningful-images)
+    
+        **Baseline Test ID.**: 6.1-MeaningfulImage
+    
+        **Test Instruction.** 1
+    
+        # Expected result that the ICT Baseline would predict
+        # [Pass | Fail | DNA]
+        result: FAIL
+     
+        # Brief description of the rationale for the expected result
+        result-descr: The image in the code sample does not provide any attributes that would contribute to an accessible name or description text alternative output.
+         
+        # URL for the code sample
+        # In the sample code file, add id="tc_code" to the 
+        # element that contains the relevant code snippet.
+        #
+        # Then upload the code sample to the 'testfiles' folder 
+        # and provide the link (and only the url) below.
+        sample: /testfiles/TF06/06.1-1-fail-1.html
+
+        # Table of test instructions, including the following table headers:
+        # Test Instruction #; Instruction Detail; Expected Test Case Result  
+        #
+        # Include the table in the content section below
+
      +
    +
  5. To enter the test file's results for the Baseline Test instructions:
    6. +
      +
    • Please do not edit the table column headers:
      • + 
      +             | Test Instruction | Instruction Detail | Expected Test Case Result |
+             |------------------|--------------------|---------------------------|
+
      +
    • Use this table (defined in markdown format) to describe the Test File’s result for each corresponding Baseline Test instruction. COPY & PASTE the test instruction identifier and the Instruction Detail from the Web Baseline
      • +
    • Include all test instructions up to and including the instruction that determines the test result (pass/fail/dna). For example, if the third instruction determines the result, include the first, second, and third instructions in the table.
      • +
    • Create additional rows. Each row will have this general format (columns in markdown tables are created using "|"):
      • + 
      +            | [Baseline Test Instruction ID] | [Copy and paste the instructions from the Web Baseline | [describe the test file's result for this Baseline test instruction] |
+
      +
    +
  6. Commit your changes (i.e., save or upload your files to your branch).
    7. +
+

Update the Test Case Index File

+

This is necessary because the Test Cases page is the main navigation to all test case/files on the Alignment website.

+
    +
  1. Open the “testcases.md” file in the root folder in the GitHub repo.
    2. +
  2. Modify the list to add a link to your new test case.
    3. +
  3. Commit your changes (i.e., save or upload your files to your GitHub branch).
    4. +
+ +

Open a Pull Request

+
    +
  1. Open a pull request in Pull requests · Section508Coordinators/baselinealignment
    2. +
  2. Each pull request should include
    3. +
      +
    • test case (markdown), ex: TC06.1-1-fail-1.md
      • +
    • test file (HTML), ex: 06.1-1-fail-1.html
      • +
    • updated testcases.md
      • +
    +
  3. When you are ready for your pull request to be reviewed, assign Andrew (drewnielson) or Kathy (kengdoj) as reviewers.
    4. +
+