From 88bb5c120f4b2c27f42f734f1d628d3289e2f444 Mon Sep 17 00:00:00 2001 From: Marcelo Cabral Date: Mon, 20 Jan 2025 10:33:33 -0700 Subject: [PATCH] Updated documentation and unit tests --- CONTRIBUTING.md | 4 +-- docs/AddingComponents.md | 24 ++++++++-------- .../components/ComponentFactory.test.js | 28 +++++++++---------- test/brsTypes/components/RoTimespan.test.js | 4 +-- test/e2e/CustomComponents.test.js | 2 +- 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6850857e..38066747 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,9 +45,9 @@ Regardless of whether you're fixing bugs or implementing new features, there's a 1. Create a fork of this repo if you haven't already 1. Send us a [pull request](https://github.com/rokucommunity/brs/pulls)! -### Adding a component +### Adding a Node component -For guidelines on adding a component to `brs`, see [this doc](docs/AddingComponents.md). +For guidelines on adding a Node component to `brs`, see [this doc](docs/AddingComponents.md). ## What We Look For in a Pull Request diff --git a/docs/AddingComponents.md b/docs/AddingComponents.md index 6c074f90..45630a4e 100644 --- a/docs/AddingComponents.md +++ b/docs/AddingComponents.md @@ -1,22 +1,22 @@ -## Guidelines for adding components to `brs` +## Guidelines for adding node components to `brs` -This is aimed to be a quick guide for adding a component to `brs`. Note that this may not be comprehensive in all cases, but is a general plan of attack. Here are the steps you should take: +This is aimed to be a quick guide for adding a node component to `brs`. Note that this may not be comprehensive in all cases, but is a general plan of attack. Here are the steps you should take: -1. Find the documentation for your component on [Roku's developer docs](https://developer.roku.com). For example, the documentation for the `Group` component can be found [here](https://developer.roku.com/en-gb/docs/references/scenegraph/layout-group-nodes/group.md). -1. Create a file in the [components directory](https://github.com/rokucommunity/brs/tree/master/src/brsTypes/components) called `.ts`. +1. Find the documentation for your component on [Roku's developer docs](https://developer.roku.com). For example, the documentation for the `Group` component can be found [here](https://developer.roku.com/docs/references/scenegraph/layout-group-nodes/group.md). +1. Create a file in the [nodes directory](https://github.com/rokucommunity/brs/tree/master/src/brsTypes/nodes) called `.ts`. 1. Copy the following code and paste it into your new file: ``` import { FieldModel } from "./RoSGNode"; - import { AAMember } from "./RoAssociativeArray"; + import { AAMember } from "../components/RoAssociativeArray"; - export class extends { + export class extends { readonly defaultFields: FieldModel[] = [ // Add built-in fields here. // The fields can be found on the Roku docs. ]; - constructor(initializedFields: AAMember[] = [], readonly name: string = "") { + constructor(initializedFields: AAMember[] = [], readonly name: string = "") { super([], name); this.registerDefaultFields(this.defaultFields); @@ -25,10 +25,10 @@ This is aimed to be a quick guide for adding a component to `brs`. Note that thi } ``` -1. Replace all `` and `` from above with your component name. Add any built-in fields and/or class functions that the Roku docs specify. -1. Add a constructor definition to the [component factory](https://github.com/rokucommunity/brs/blob/main/src/brsTypes/components/ComponentFactory.ts). This will allow instances of your new component to be created dynamically when it is encountered in XML or BrightScript code. -1. Add a test case for your Typescript class in [the components test directory](https://github.com/rokucommunity/brs/tree/master/test/brsTypes/components). Use the existing component test files in that directory as a model for what your test should look like. +1. Replace all `` and `` from above with your node name. Add any built-in fields and/or class functions that the Roku docs specify. +1. Add a constructor definition to the [node factory](https://github.com/rokucommunity/brs/blob/main/src/brsTypes/nodes/NodeFactory.ts). This will allow instances of your new node to be created dynamically when it is encountered in XML or BrightScript code. +1. Add a test case for your Typescript class in [the nodes test directory](https://github.com/rokucommunity/brs/tree/master/test/brsTypes/nodes). Use the existing component test files in that directory as a model for what your test should look like. 1. Add an end-to-end test case. - - Create a file in [the end-to-end directory](https://github.com/rokucommunity/brs/tree/master/test/e2e) called `.brs`. In the file, write BrightScript code that exercises your component functionality. - - Add an XML file to the [the components test directory](https://github.com/rokucommunity/brs/tree/master/test/brsTypes/components) that uses your component. + - Create a file in [the end-to-end directory](https://github.com/rokucommunity/brs/tree/master/test/e2e) called `.brs`. In the file, write BrightScript code that exercises your node functionality. + - Add an XML file to the [the components test directory](https://github.com/rokucommunity/brs/tree/master/test/brsTypes/nodes) that uses your node. - Add a test block to [BrsComponents.test.js](https://github.com/rokucommunity/brs/blob/main/test/e2e/BrsComponents.test.js). In this block, verify that the code from your XML and Brightscript files is behaving as expected. diff --git a/test/brsTypes/components/ComponentFactory.test.js b/test/brsTypes/components/ComponentFactory.test.js index dc2fd153..c7f09276 100644 --- a/test/brsTypes/components/ComponentFactory.test.js +++ b/test/brsTypes/components/ComponentFactory.test.js @@ -1,18 +1,18 @@ const brs = require("../../../lib"); -const { ComponentFactory, RoSGNode, Callable, ValueKind } = brs.types; +const { NodeFactory, RoSGNode, Callable, ValueKind } = brs.types; -describe("ComponentFactory", () => { +describe("NodeFactory", () => { describe("createComponent", () => { it("returns a properly constructed built in Node with default name", () => { - const component = ComponentFactory.createComponent("Rectangle"); - expect(component.nodeSubtype).toBe("Rectangle"); - expect(component.name).toBe("Rectangle"); - expect(component.constructor.name).toBe("Rectangle"); + const node = NodeFactory.createComponent("Rectangle"); + expect(node.nodeSubtype).toBe("Rectangle"); + expect(node.name).toBe("Rectangle"); + expect(node.constructor.name).toBe("Rectangle"); }); it("returns a properly constructed built in Node with custom name", () => { - const component = ComponentFactory.createComponent("Poster", "Foo"); - expect(component.nodeSubtype).toBe("Foo"); - expect(component.constructor.name).toBe("Poster"); + const node = NodeFactory.createComponent("Poster", "Foo"); + expect(node.nodeSubtype).toBe("Foo"); + expect(node.constructor.name).toBe("Poster"); }); }); @@ -42,7 +42,7 @@ describe("ComponentFactory", () => { } it("adds a new Component to be constructed", () => { - ComponentFactory.addComponentTypes([ + NodeFactory.addNodeTypes([ [ "Foo", (name) => { @@ -50,10 +50,10 @@ describe("ComponentFactory", () => { }, ], ]); - const component = ComponentFactory.createComponent("Foo"); - expect(component.nodeSubtype).toBe("Foo"); - expect(component.name).toBe("Foo"); - expect(component.constructor.name).toBe("Foo"); + const node = NodeFactory.createComponent("Foo"); + expect(node.nodeSubtype).toBe("Foo"); + expect(node.name).toBe("Foo"); + expect(node.constructor.name).toBe("Foo"); }); }); }); diff --git a/test/brsTypes/components/RoTimespan.test.js b/test/brsTypes/components/RoTimespan.test.js index 878cd3c7..4ce1bebb 100644 --- a/test/brsTypes/components/RoTimespan.test.js +++ b/test/brsTypes/components/RoTimespan.test.js @@ -1,5 +1,5 @@ const brs = require("../../../lib"); -const { Timespan, Int32, BrsString, BrsInvalid } = brs.types; +const { RoTimespan, Int32, BrsString, BrsInvalid } = brs.types; const { Interpreter } = require("../../../lib/interpreter"); const lolex = require("lolex"); @@ -9,7 +9,7 @@ describe("Timespan", () => { beforeEach(() => { clock = lolex.install({ now: 1547072370937 }); - ts = new Timespan(); + ts = new RoTimespan(); }); afterAll(() => { diff --git a/test/e2e/CustomComponents.test.js b/test/e2e/CustomComponents.test.js index 3dc3d8eb..be5574ba 100644 --- a/test/e2e/CustomComponents.test.js +++ b/test/e2e/CustomComponents.test.js @@ -33,7 +33,7 @@ describe("Extending custom components", () => { let outputStreams; beforeAll(() => { - brs.types.ComponentFactory.addComponentTypes([["Foo", (name) => new Foo([], name)]]); + brs.types.NodeFactory.addNodeTypes([["Foo", (name) => new Foo([], name)]]); brs.types.extendBrsObjects([["Foo", (_interpreter) => new Foo()]]); outputStreams = createMockStreams();