Improved CI: Key Steps to Add Gramma

Background

To ensure the quality of software builds, continuous integration has been practiced to guarantee that a developer's commit does not introduce errors. Bugs, errors, or other glitches would be likely to occur in software development, particularly on new untested code. Therefore, detecting these mistakes early are crucial to maintain usability and reliability.

One particular example is this website itself which employs continuous integration to run different tests such as unit tests. Some of these tests check for grammatical errors in the text content of different pages.

The reason is that grammar is particularly important in formal contexts. Even in informal context, having a good grammar helps the writer to convey the ideas correctly. It is even recommended by a search engine to avoid mistakes in grammar or spellings.

Prerequisites

The readers of this article are expected to have intermediate knowledge in JavaScript yet may be a beginner in employing continuous integration. They are also assumed to have knowledge in using Node.js CLI to install packages or run scripts.

Additionally, it is encouraged (but not required) to have a sample website to follow the steps and have a hands-on experience. Should the reader opt to do a hands-on, the website may even have a single page only for simplicity.

Local Setup

The steps below assumes that there is a website, real or hypothetical, that would be checked for its grammar.

1. Installation of Required Package
2. Setup of E2E Testing Framework

Installation of Required Package

The first step is dependent on the reader's Node.js environment version. Regardless of the version, the package to be installed locally provides methods to request to a LanguageTool server.

npm install gramma

npm install git+ssh://git@github.com:KennethTrecy/gramma.git#v1.7.0-rc1

Setup of E2E Testing Framework

The second step is to set up the E2E testing framework to be used. For this guide, Playwright package would be used. The readers may choose their preferred framework to scrape the contents of the website as long as they could request through the package from the first step.

npm install @playwright/test

If the reader chose Playwright package, use the following configuration below and save it as playwright.config.ts in the project root. Note that npm run preview would run HTTP server bound on a certain port. In the configuration below, it requires the server should be found on port 4173. The readers may customize the command and port according to their setup.

import type { PlaywrightTestConfig } from "@playwright/test"

const configuration: PlaywrightTestConfig = {

"webServer": {

"command": "npm run preview",

"port": 4173

},

"testDir": "t/e2e"

}

export default configuration

Workflow Configuration

Copy the code below and paste it a file under . github/workflows from the project root. The readers may name it whatever they like.

name: E2E Tests

on:

  push: []

  pull_request:

    types:

      - opened

      - synchronize

      - reopened

      - review_requested

    branches:

      - master

    paths:

      - '.github/workflows/e2e.yml'

      - 'src/**'

jobs:

  initial_e2e_tests:

    runs-on: ubuntu-latest

    steps:

    - uses: actions/checkout@v3

    - name: Testing on Node.js 16.x

      uses: actions/setup-node@v3

      with:

        node-version: 16.x

    - name: Install general dependencies

      run: npm install

    - name: Install dependencies to do E2E tests

      run: npx playwright install --with-deps

    - name: Install server to check grammar

      run: npx gramma server install

    - name: Identify the server before explicitly enabling it to check grammar

      run: npx gramma server info

    - name: Initiate server to check grammar

      run: npx gramma server start

    - name: Identify the server after explicitly enabling it to check grammar

      run: npx gramma server info

    - run: npm run test:e2e

On lines 30 – 31, it double-checks if the LanguageTool server is not yet running. After that, the lines 34 – 35, explicitly starts it. The line 36 – 37 just confirms if the server is running. The grammar-checking activity starts at line 38.

Execution

Below is a sample test code of a grammar-checking activity. It should be in a file placed under t/e2e from the project root. It may be improved upon depending on the reader's use case, situation, or goal. Next to test code is the explanation or the idea behind the test code, regardless whether the reader chose Playwright package or not.

import { check } from "gramma"

import { test, expect } from "@playwright/test"

test("page has correct grammar", async ({ page }) => {

await page.goto("/")

const allTexts = await page.locator(`css=p`).allInnerTexts()

const pendingResults: Promise<any>[] = allTexts.map(async text => {

const result = await check(text, {

"api_url": "http://0.0.0.0:8081/v2/check",

// Put the words in this array that are not in the English dictionary like names.

"dictionary": []

})

return result.matches

})

const expectedMatches = allTexts.map(() => [])

const matches = await Promise.all(pendingResults)

await expect(matches).toEqual(expectedMatches)

});

1. Page Selection Step.Line 5 visits the page. This selects the page to be scanned for texts.
2. Extraction Step.Line 7 searches for all of the paragraphs found on the visited page. After that, all texts of the paragraphs would be extracted.
3. Analysis Step.Lines 9 - 18 send the extracted texts to the server for checking. This is the core step. Each result should return an empty array signifying that there that the checked paragraph is correct and free from errors.
4. Review Step.After getting all results of checking, line 22 expects that each result is an empty array.

After creating a test code, push the changes to a remote repository. The reader should check the "Actions" tab of the remote repository to see if the grammar checking tests work properly. If not, the mismatches would be shown by the chosen testing framework.

Below is a snapshot of previous results of successful grammar check using the Playwright package. Note that the presentation of results may vary per framework used for testing.

Summary

Good grammar is important both in formal and informal contexts, as it helps convey ideas correctly and is recommended by search engines. By utilizing continuous integration, grammatical errors can be caught early in the development before publishing document, article, or any group of texts.

The testing framework to be used is wholly dependent on the current progress in the system development, preferences, and other factors. It recommended having unanimous decision for ease and fast progress of development.

Regardless of the framework, this article has presented a pattern to conduct grammar checks. The reader may even request directly to the API of LanguageTool server if they know how to translate the code according to their chosen technologies and programming language.

References

Some portions in this article were based on third-party work(s) for educational purposes. They are copyright of the respective groups, organizations, companies, or persons that have been attributed below. Note that these works may have been shared under different licenses and may have notices (e.g. disclaimer of warranties) in the linked licenses. Should a work has no existing license(s), a link to the work have been still provided.