Unit Testing

Unit testing should be the first and most comprehensive form of testing that you perform.

The purpose of unit testing is to ensure that each unit of software code is coded correctly, works as expected, and returns the expected outputs for all relevant inputs. A unit can be a function, method, module, object, or other entity in an app’s source code.

Unit tests are small, efficient tests created to execute and verify the lowest-level of code and to test those individual entities in isolation. By isolating functionality, we remove external dependencies that aren't relevant to the unit being tested and increase the visibility into the source of failures.

Unit tests that you create should adhere to the following principles:

• Easy to write: Unit testing should be your main testing focus; therefore, tests should typically be easy to write because many will be written. The standard testing technology stack combined with recommended development environments ensures that the tests are easily and quickly written.
• Readable: The intent of each test should be clearly documented, not just in comments, but the code should also allow for easy interpretation of what its purpose is. Keeping tests readable is important should someone need to debug when a failure occurs.
• Reliable: Tests should consistently pass when no bugs are introduced into the component code and only fail when there are true bugs or new, unimplemented behaviors. The tests should also execute reliably regardless of the order in which they’re run.
• Fast: Tests should be able to execute quickly and report issues immediately to the developer. If a test runs slowly, it could be a sign that it is dependent upon an external system or interacting with an external system.
• Discrete: Tests should exercise the smallest unit of work possible, not only to ensure that all units are properly verified but also to aid in the detection of bugs when failures occur. In each unit test, individual test cases should independently target a single attribute of the code to be verified.
• Independent: Above all else, unit tests should be independent of one another, free of external dependencies, and be able to run consistently irrespective of the environment in which they’re executed.

To shield unit tests from external changes that may affect their outcomes, unit tests focus solely on verifying code that is wholly owned by the component and avoid verifying the behaviors of anything external to that component. When external dependencies are needed, consider using mocks to stand in their place.

Component Testing

The purpose of component testing is to establish that an individual component behaves and can be interacted with according to its specifications. In addition to verifying that your component accepts the correct inputs and produces the right outputs, component tests also include checking for issues related to your component's properties, events, slots, styles, classes, lifecycle hooks, and so on.

A component is made up of many units of code, therefore component testing is more complex and takes longer to conduct than unit testing. However, it is still very necessary; the individual units within your component may work on their own, but issues can occur when you use them together.

Component testing is a form of closed-box testing, meaning that the test evaluates the behavior of the program without considering the details of the underlying code. You should begin testing a component in its entirety immediately after development, though the tested component may in part depend on other components that have not yet been developed. Depending on the development lifecycle model, component testing can be done in isolation from other components in the system, in order to prevent external influences.

If the components that your component depends on have not yet been developed, then use dummy objects instead of the real components. These dummy objects are the stub (called function) and the controller (called function).

Depending on the depth of the test level, there are two types of component tests: small component tests and large component tests.

When component testing is done in isolation from other components, it is called "small component testing." Small component tests do not consider the component's integration with other components.

When component testing is performed without isolating the component from other components, it is called "large component testing", or "component testing" in general. These tests are done when there is a dependency on the flow of functionality of the components, and therefore we cannot isolate them.

End-to-End Testing

End-to-end testing is a method of evaluating a software product by examining its behavior from start to finish. This approach verifies that the app operates as intended and confirms that all integrated components function correctly in relation to one another. Additionally, end-to-end testing defines the system dependencies of the product to ensure optimal performance.

The primary goal of end-to-end testing is to replicate the end-user experience by simulating real-world scenarios and evaluating the system and its components for proper integration and data consistency. This approach allows for the validation of the system's performance from the perspective of the user.

End-to-end testing is typically performed on finished products and systems, with each review serving as a test of the completed system. If the system does not produce the expected output or if a problem is detected, a second test will be conducted. In this case, the team will need to record and analyze the data to determine the source of the issue, fix it, and retest.

After you run this command in your app, you can create and run tests for your app using Jest and the Preact Testing Library. The add testing command adds the test-config directory to your app's root directory. This directory contains two files that are required to set up testing: jest.config.js and testSetup.ts. The testSetup.ts file imports runtime support for compiled and transpiled async functions, while jest.config.js is Jest's configuration file.

The extension for files containing tests, known as "spec files," should be .spec.tsx so that Oracle JET tooling and your Jest testing configuration recognize them. If spec files are missing from a component, the add testing command creates them. Spec files are located within a __tests__ directory inside the components directory, such as ./src/components/<component-name>/__tests__. This directory holds the test files you write for your component and, by default, the add testing command creates a spec file with the following file name pattern: <component-name>.spec.tsx.

In the following steps, we demonstrate how to set up an Oracle JET app for testing, and how to run a unit test and a component test.

1. Open a terminal window in a directory of your choice to create a new Oracle JET app using the basic template:

   npx @oracle/ojet-cli create vdomTestApp --template=basic --vdom

2. Navigate to the newly created app's root directory and create a new VComponent component:

   cd vdomTestApp
   npx ojet create component hello-world

3. Open the ./vdomTestApp/src/components/content/index.tsx file to import and display the newly-created HelloWorld component:

   import { HelloWorld } from "hello-world/loader"
   
   export function Content() {
     return (
       <div class="oj-web-applayout-max-width oj-web-applayout-content">
         <HelloWorld />
       </div>
     );
   };
   

   Note:

   We render the HelloWorld component using the Preact component class syntax (import {HelloWorld} . . . and <HelloWorld />) because Jest cannot test the custom element alternative (import "hello-world/loader" . . . and <hello-world></hello-world>).

4. To run the app in your browser and confirm that the app renders the newly-created HelloWorld component, enter the following command in the terminal window for the app’s root directory:

   npx ojet serve

   This is also a required step for testing. Before you can test components, you must build the component using the Oracle JET CLI.

   
   
   
   
   

   Note:

   The HelloWorld component passes "Hello from hello world" to the app through its message property. This confirms that the app and component function as expected.

5. In the terminal window of your app's root directory, add the testing libraries:

   npx ojet add testing

   This adds the test-config directory to the root directory of your app and the __tests__ directory to the component directory (./src/components/hello-world ). The __tests__ directory contains a spec file (hello-world.spec.tsx) with a component test for your HelloWorld component that verifies that it renders. Jest provides the test case and assertions (describe(), test(), and expect(true).not.toBeUndefined;), whereas the render() function from the Preact Testing Library tests that the component renders in the app.

   ./vdomTest/test-config
   jest.config.js
   testSetup.ts

   The add testing command also updates the package.json file with the testing dependencies, such as the Jest preset that allows Oracle JET Web Elements to be used in Jest tests, and two convenience scripts, test and test:debug.

6. To provide a function for a unit test to test, open the ./VDOMTestApp/src/components/hello-world/hello-world.tsx file for the HelloWorld component that we created previously and add the sum function at the end of the file:

   . . .
   >> = registerCustomElement("hello-world", HelloWorldImpl);
   
   // function for doc example
   export const sum = (a: number, b: number) => {
     return a + b;
   };

7. To write a unit test for this function, open the ./src/components/hello-world/__tests__/hello-world.spec.tsx file and add the following entries:

   import { render } from "@testing-library/preact";
   import { HelloWorld } from "hello-world/hello-world";
   import { sum } from "hello-world/hello-world";
   
   describe("Test description", () => {
     test("Your test title", async () => {
       const content = render(
         <div data-oj-binding-provider="preact">
           <HelloWorld />
         </div>
       );
       expect(true).not.toBeUndefined;
     });
   
     it("The sum is 10", () => {
       expect(sum(6, 4)).toBe(10);
     });
   });
   

8. In the terminal window of your app’s root directory, enter the following commands to build the Oracle JET app and execute the tests:

   npx ojet build
   npm run test

   The terminal window displays the test results:

   vdomTest
   $ npm run test
   
   > vdomTestJET15@1.0.0 test
   > jest -c test-config/jest.config.js
   vdomTest
   $ npm run test
   
   > vdomTestJET15@1.0.0 test
   > jest -c test-config/jest.config.js
   
   PASS  src/components/hello-world/__tests__/hello-world.spec.tsx
     Test description
       √ Your test title (5 ms)                                                                                                                                    
       √ The sum is 10 (1 ms)                                                                                                                                      
                                                                                                                                                                   
   Test Suites: 1 passed, 1 total                                                                                                                                  
   Tests:       2 passed, 2 total                                                                                                                                  
   Snapshots:   0 total
   Time:        1.966 s, estimated 3 s
   Ran all test suites.
   
   
   PASS  src/components/hello-world/__tests__/hello-world.spec.tsx
     Test description
       √ Your test title (5 ms)                                                                                                                                    
       √ The sum is 10 (1 ms)                                                                                                                                      
                                                                                                                                                                   
   Test Suites: 1 passed, 1 total                                                                                                                                  
   Tests:       2 passed, 2 total                                                                                                                                  
   Snapshots:   0 total
   Time:        1.966 s, estimated 3 s
   Ran all test suites.